Connect Keycloak

Keycloak connects as a generic OpenID Connect provider. This page covers the Keycloak side and the settings that catch people out. The protocol settings, the warnings and the sign-in refusals are on Connect an OpenID Connect provider.

Create the client

In the Keycloak admin console, choose your realm, then Clients → Create client.

1. Client type: OpenID Connect. Client ID: anything you like, for example deploybase.
2. Capability config: turn Client authentication on. That makes it a confidential client, which is what the connection needs. Leave Standard flow on and turn the other flows off.
3. Valid redirect URIs: the redirect URI shown next to the connection at Settings → Single sign-on in deploybase. It is the sign-in service’s callback, not a deploybase address, and it is the same for every connection. Copy it from the page rather than typing it.
4. Save, then open the Credentials tab and copy the client secret.

Keycloak includes the openid, profile and email scopes on a new client by default, which is what the connection asks for.

Find the issuer URL

The issuer is the realm’s base URL:

https://id.example.com/realms/engineering

Confirm it rather than assembling it: in Realm settings → General, open the OpenID Endpoint Configuration link. The issuer field of that document is the exact value to paste into deploybase.

A realm name with a capital letter or a space is part of the URL. Use the value from the document.

Legacy auth path

Keycloak 17 dropped the /auth prefix. Both layouts exist in the wild:

Layout	Issuer
Keycloak 17 and later, default	https://id.example.com/realms/engineering
Keycloak 16 and earlier, or started with --http-relative-path=/auth	https://id.example.com/auth/realms/engineering

The Red Hat build ships with the /auth prefix, so the older shape is legitimate and the connection is saved with it. You get a warning rather than a refusal: the connection works as long as that setting stays. If someone later removes --http-relative-path=/auth, the issuer changes and every sign-in breaks, so update the connection at the same time.

The reverse case is the confusing one. If you entered /auth/realms/… on a Keycloak 17 that does not use the prefix, the old URL still reaches a running Keycloak, which answers 404. The message says so: Keycloak is up, the path is wrong. Drop the /auth.

Signed userinfo

This is the one Keycloak setting that breaks the connection outright, and it cannot be detected from outside.

In Clients → your client → Advanced → Fine grain OpenID Connect configuration there is a User info signed response algorithm setting. Its default is unsigned, which is what you want. Set to anything else, Keycloak returns the userinfo response as a signed JWT with Content-Type: application/jwt, and the sign-in service cannot read that: it expects JSON. The result is a sign-in that authenticates correctly and then fails to read who the person is.

Two ways to avoid it:

• Leave User info signed response algorithm unset, which is the default.
• Or turn on Read the profile from the ID token for the connection, so the userinfo endpoint is not called at all. A Keycloak connection created without an explicit choice gets this turned on for you, and the connection tells you it happened. Set it to false explicitly if you need userinfo.

If you have signed userinfo on for other clients that need it, use the second option rather than changing a setting other systems depend on.

PKCE method

Sign-in always sends an S256 code challenge. Keycloak accepts it out of the box, so most connections need nothing here.

If you have set Proof Key for Code Exchange Code Challenge Method on the client (Advanced → Advanced settings), it has to be S256 or left empty. Setting it to plain makes Keycloak reject every sign-in request the connection sends.

Email verified

Keycloak stores a per-user Email verified switch, in Users → the user → Details. A person whose switch is off cannot sign in: the connection matches people by a verified address, and Keycloak reports theirs as unverified.

This is easy to miss because it is per user, not per realm. A user you created by hand in the admin console has the switch off unless you turned it on, while a user who registered and clicked a confirmation link has it on. So the connection works for you and fails for the colleague you added manually.

Check the switch on the people you are rolling this out to. Users imported from LDAP or synced from another directory are the other common source of unverified addresses.

If you would rather not audit every account, the connection has a Trust unverified email addresses setting. Turning it on means addresses from this Keycloak are accepted whether or not it calls them verified, so only use it where you control who can set an address in that realm. Only the team Owner can turn it on.