Integrating with Keycloak

This article explains how to connect a self-hosted Keycloak realm to Valven for single sign-on over SAML 2.0. In Keycloak, your realm acts as the identity provider, and Valven is registered inside it as a SAML client.

You'll need admin access to a Keycloak realm, and permission to change SSO settings in Valven.

Connect Your Application

Visit Settings → Single Sign-On on the Valven sidebar, and open the Keycloak tab. Every provider tab uses the same layout — a form on the left, and a “Set these in Keycloak” panel on the right that gives you the three values you'll need to paste into Keycloak's client configuration: the Identifier (Entity ID), the Reply URL (ACS), and the Sign on URL.

Create a SAML Client in Keycloak

Step 1: In the Keycloak admin console, go to Clients → Create client.

Step 2: Set Client type to SAML.

Step 3: For Client ID, paste the Identifier (Entity ID) value from the Valven panel above.

Step 4: Click Next.

On the Login settings step, paste the Reply URL (ACS) value into both Valid redirect URIs and Master SAML Processing URL, then click Save.

Review Client Settings

Once the client is created, its Settings tab shows the full configuration in one place — general info, access settings, signature and encryption, and login settings:

• Name ID format: set to email.

• On the Keys tab: Client signature required: leave this Off — Valven does not currently sign its authentication requests, and turning this on will cause sign-in to fail with an invalid_requester error.

Add Attribute Mappers

Keycloak does not send user attributes by default; each one needs an explicit mapper. Open the client's Client scopes tab, select the entry ending in -dedicated, and add mappers from there.

At minimum, add three User Property mappers — email, firstName, and lastName — each pointing at the matching SAML Attribute Name, plus a Group list mapper for role information:

Once complete, the mapper list should look like this (username is optional, used only if you plan to sign in by username rather than email):

The most common mistake — Full group path

Open the Group list mapper and check the Full group path setting:

Make sure Full group path is switched OFF. If it's left on, group values arrive as “/developer” instead of “developer”, and will never match a role name configured in Valven.

You can create Groups;

Import the Realm Metadata into Valven

Open the following URL in your browser, replacing your server address and realm name:

Copy the full XML content and paste it into the Federation metadata XML box on the Valven Keycloak tab. This automatically fills in the Identity Provider Issuer, Login URL, and Signing Certificate fields.

Create a Test User

Step 1: In Keycloak, go to Users → Add user and fill in username, email, first name, and last name.

Step 2: On the new user's Credentials tab, click Set password, choose a password, and switch Temporary off.

Step 3: To test role mapping, go to Groups → Create group, then add the user to that group from the user's Groups tab. Use the same name as a Role already configured in Valven.

Verifying the Connection

Back in Valven, turn on Single sign-on enabled and Use this provider for sign-in, then click Save Changes. Test SSO Configuration confirms the connection details were read correctly.

From the Valven sign-in page, enter your email address and choose “Sign in with SSO” — you should land on your Keycloak realm's login page. Signing in with the test user should bring you back to Valven with the correct name and role.

Common Errors

• invalid_requester: Keycloak is rejecting Valven's request because it expects it to be signed — revisit "Review Client Settings" step and confirm Client signature required is off.
• Role or group information doesn't reach Valven: confirm Full group path is off, and that the test user is actually a member of the group.