Keycloak SSO: realms, clients and the settings that decide how long users stay signed in

Keycloak SSO is single sign-on provided by Keycloak: users sign in once to a realm, and every application registered as a client in that realm can accept that login without asking for a password again. Keycloak speaks OpenID Connect, OAuth 2.0 and SAML 2.0, so one deployment can serve modern apps, enterprise SaaS and legacy clients.

Most Keycloak problems are not protocol problems. They are configuration problems: a redirect URI that does not match, a session timeout nobody tuned, or a cookie that a browser refuses to send.

The two objects that explain everything

Realm: an isolated namespace with its own users, clients, roles and login settings. A common pattern is one realm per environment or per tenant. Users and clients in different realms cannot see each other, and SSO does not cross realms.

Client: an application that asks Keycloak to authenticate users. The client holds the protocol settings: redirect URIs, client authentication, scopes and mappers.

A user belongs to a realm; an application is a client in that realm. Get those two placements wrong and nothing else will line up.

OIDC client setup

For a modern web or mobile app the OIDC client needs:

• Client ID and, for confidential clients, a client secret.
• Valid redirect URIs: exact matches, no wildcards unless you really need them.
• Web origins for browser-based apps that call the token endpoint from JavaScript.
• Client authentication on for server-side apps, off for single-page and native apps that use PKCE.
• Scopes and mappers for the claims the app reads: email, profile, groups.

Endpoints come from the realm's discovery document, at /realms//.well-known/openid-configuration. Do not hard-code the authorization and token URLs by hand if you can read discovery instead.

SAML client setup

For a SAML application, the client has:

• A client ID that is the SP entity ID.
• A valid redirect URI that is the ACS URL.
• NameID format and attribute mappers.
• Signing and encryption settings, depending on what the SP expects.

Keycloak signs responses and assertions by default; some SPs expect one or the other, and a mismatch shows up as an invalid signature error even though the certificate is correct.

Sessions: the part everyone gets wrong

Keycloak has two levels of session, both under Realm settings → Sessions:

The realm session is what makes SSO "single": as long as it lives, opening another client skips the login page. The client session controls how long that individual application's token and session last.

Two consequences follow. First, "users are logged out too fast" is usually SSO Session Idle, not the application's own timeout. Second, "users stay signed in for ten hours" is SSO Session Max, and shortening the idle timeout does not help if activity keeps refreshing it. Offline sessions and remember-me are separate settings with their own lifetimes.

Identity brokering

Keycloak can also delegate login to an upstream provider: an OIDC or SAML identity provider such as Entra ID, Okta or Google. The upstream is configured under Identity providers, with mappers that translate its claims into Keycloak user attributes. The first-login flow decides what happens when an unknown user arrives: create the account, link an existing one, or deny.

This is how Keycloak acts as both an identity provider and a service provider at the same time. It is the same role chaining described in identity provider vs service provider.

Common failures

• Invalid redirect URI: the exact string differs in scheme, host, port, path or trailing slash. Keycloak compares strings, not intent.
• Invalid client credentials: client authentication is on but the app sends no secret, or the secret was rotated.
• CORS errors: the app calls the token endpoint from the browser and the client's web origins do not include the app's origin.
• Cookie not sent: third-party cookie blocking breaks iframe and cross-site SSO patterns; SameSite settings decide whether the browser includes the session cookie.
• SAML signature invalid: the SP expects the assertion signed and Keycloak signed the response, or the SP has an old certificate.
• Unexpected logout: SSO Session Max reached, or the client's own session expired first.

Keycloak and Casdoor

Keycloak is a mature, Apache-2.0 identity provider with a large ecosystem. Casdoor is an alternative with a smaller footprint (Go instead of Java), a web console for users and organizations, and built-in SAML, OIDC, CAS, LDAP and RADIUS servers. If you are comparing them, see Casdoor vs Keycloak, Keycloak alternatives and migrating from Keycloak.

Checklist

1. Decide the realm layout before creating clients.
2. Register exact redirect URIs and web origins.
3. Read the discovery document instead of copying endpoints.
4. Tune SSO Session Idle and Max deliberately, and document them.
5. Configure mappers for the claims your app actually reads.
6. Test login, logout, token refresh and an expired session.
7. Plan certificate and secret rotation.

FAQ

Is Keycloak free? Yes. Keycloak is open source under Apache-2.0. Red Hat sells a supported product built on it, but the project itself has no license fee.

Does Keycloak support both SAML and OIDC? Yes. A client can use OpenID Connect or SAML 2.0, and one realm can serve both kinds of applications.

What is a realm in Keycloak? A realm is an isolated namespace with its own users, clients, roles and login settings. SSO works inside a realm, not across realms.

How long does a Keycloak SSO session last? By default, the realm session is idle for 30 minutes and lives at most 10 hours. Both values are configurable under Realm settings → Sessions, and clients can override them.

Can Keycloak connect to Active Directory or LDAP? Yes, through user federation: Keycloak reads users from an LDAP or Active Directory server instead of storing them locally. That is the opposite direction from Casdoor, which can also serve LDAP to applications.

Related reading: what is single sign-on, SAML SSO and Keycloak alternatives.

Casdoor is an open-source identity provider that speaks OIDC, SAML, CAS, LDAP and RADIUS, with a hosted option from $9 per month and no per-user fees.