Getting Keycloak SSO configuration right is one of those tasks that looks straightforward on paper but quickly turns into a maze of redirect URIs, token mappings, and protocol-specific quirks. Whether you're setting up OIDC for a modern web app or wiring SAML into an enterprise identity provider, the details matter, and a single misconfigured claim can block every authentication attempt across your system.

This is especially true in healthcare, where SSO underpins secure access to clinical applications and EHR-integrated workflows. At VectorCare, we build and manage SMART on FHIR applications that plug directly into EPIC EHR systems, and identity management sits at the core of every deployment. We've configured Keycloak across enough environments to know exactly where teams get stuck, and where the documentation falls short.

This guide walks you through the full Keycloak SSO setup process, covering both OIDC and SAML from realm creation to production-ready configuration. You'll get concrete steps for creating and configuring clients, mapping user attributes, connecting external identity providers, and troubleshooting the errors that actually come up in practice. If you've been circling the Keycloak admin console trying to piece things together from scattered docs, this is the single reference you need to get it done.

Prerequisites and planning

Before you write a single configuration line, getting your environment and decisions in order saves hours of backtracking. A Keycloak SSO configuration that works smoothly in production starts with clear planning, not trial and error in the admin console. Skipping this step is the most common reason teams end up rebuilding realms from scratch two weeks into a project.

What you need installed and running

You need a working Keycloak instance before any configuration makes sense. The steps in this guide apply to Keycloak 22 or later, which uses the Quarkus-based distribution. If you're still running the legacy WildFly-based version, most concepts carry over but some menu paths will differ.

Here's what you need in place before you start:

• Keycloak 22+ installed and accessible via a local Docker container or a cloud-hosted instance
• A PostgreSQL or MariaDB database connected to Keycloak rather than the default H2 embedded database (H2 is for development only, not production)
• Admin console access at http(s)://your-host/auth/admin/
• At least one target application you want to protect, with its redirect URI and base URL documented
• Network access between Keycloak and your application servers, with firewall rules verified before you start debugging auth flows
• A TLS/HTTPS certificate on your Keycloak host for anything beyond a local development environment

Running Keycloak behind a reverse proxy like NGINX or an AWS Application Load Balancer requires setting KC_PROXY=edge or KC_PROXY=passthrough so Keycloak generates correct redirect URLs instead of internal hostnames.

Choose your protocol: OIDC or SAML

Your protocol choice determines the entire configuration path. OpenID Connect (OIDC) is the right call for most modern web apps, mobile applications, and anything built on REST APIs. It's lightweight and JSON-based, and it natively supports the authorization code flow that browsers handle well. SAML 2.0 is the right call when you're integrating with enterprise identity providers like Active Directory Federation Services, older internal portals, or any vendor that hands you a SAML metadata XML file.

If you control both sides of the integration, pick OIDC. If your health system, enterprise partner, or existing identity provider mandates SAML, you don't have a choice, and that's fine. Keycloak handles both protocols equally well, and this guide covers both so you can follow whichever path applies to your situation.

Factor	OIDC	SAML
Token format	JSON (JWT)	XML
Best for	Modern apps, APIs, mobile	Enterprise IdP integration
Logout support	Front-channel + back-channel	Single logout (SLO) via XML
Setup complexity	Lower	Higher

Map out your realm structure before you click anything

A realm in Keycloak is an isolated namespace for users, clients, roles, and identity providers. The master realm exists by default, but you should never use it for your applications. Create a dedicated realm per environment (development, staging, production) or per product line if you're managing multiple independent applications that require separate user populations.

Sketching out the following before you open the admin console ensures you make architectural decisions once rather than rebuilding realms mid-project:

• How many realms you need and what they map to in your infrastructure
• Which users or groups belong to each realm
• Whether you're managing users locally in Keycloak or federating from LDAP, Active Directory, or an external identity provider
• What roles your applications need: application-level roles, realm roles, or composite roles that combine both
• Whether any realm will act as a broker that delegates authentication to an upstream IdP

Step 1. Create a realm, users, and roles

Every keycloak sso configuration starts here. The realm is the container for everything else: clients, users, roles, and identity providers. Getting this foundation right means you won't need to rebuild structures later when your application demands a specific user attribute or a client expects a role that doesn't exist yet.

Create a new realm

Log into the Keycloak admin console and click the realm selector at the top left of the sidebar. Select "Create Realm." Give it a name that maps to your environment or product, such as myapp-production. Avoid spaces and special characters in realm names since they appear directly in authentication URLs.

Key settings to confirm when creating your realm:

• Display Name: Set a readable name for the login screen
• Enabled: Toggle to On before saving
• Realm ID: Auto-populates from the name, but double-check it matches what your app expects

Never use the master realm for application clients. Reserve it strictly for Keycloak administration tasks.

Add users and set credentials

Navigate to Users > Add User inside your new realm. Fill in the username field and toggle "Email Verified" to On if you're creating a test user who won't go through the email verification flow. Click "Create" to save the new user record.

After creation, open the Credentials tab and click "Set Password." Enter a password, toggle "Temporary" to Off if you don't want the user forced to reset it on first login, and click "Save Password." For production environments, you'll typically federate users from LDAP or an external IdP rather than creating them manually, but local users are essential for testing your SSO flows before connecting an upstream directory.

Define and assign roles

Keycloak gives you two types of roles: realm roles that apply globally across clients, and client roles that are scoped to a specific application. For most integrations, client roles are the right choice because they keep permissions isolated to the app that needs them.

To create a client role, navigate to Clients, open your target client, and go to the Roles tab. Click "Create Role," name it something descriptive like app-user or billing-admin, and save. To assign it, open your user record, go to Role Mapping, select the client from the dropdown, and move the role into the assigned column.

Step 2. Configure OIDC SSO for an app

OIDC is the faster half of any keycloak sso configuration project, and it's where most modern application integrations begin. The authorization code flow handles the heavy lifting: Keycloak issues a short-lived authorization code, your app exchanges it for tokens, and the user lands in your application already authenticated. The steps below walk you through building that connection correctly the first time.

Create and configure the OIDC client

Inside your realm, navigate to Clients > Create Client. Set the client type to "OpenID Connect" and assign a Client ID that matches what your application will send in its auth requests, such as myapp-client. Click Next and enable "Client Authentication" if your app runs on a server (confidential client). Leave it off for single-page applications that cannot securely store a secret.

On the next screen, fill in these three fields before saving:

• Root URL: The base URL of your application, e.g., https://app.example.com
• Valid Redirect URIs: The exact callback path your app expects after login, e.g., https://app.example.com/auth/callback
• Web Origins: Set to + to auto-derive from the root URL, or list specific origins for CORS

A wildcard redirect URI like * will work in development but creates an open redirect vulnerability in production. Always specify the exact callback URL.

After saving, open the Credentials tab and copy the client secret. Your application needs this value alongside the Client ID to complete token exchange.

Map claims and test the token

Keycloak does not include custom user attributes in tokens by default. To surface roles or profile fields your app depends on, navigate to Clients > your client > Client Scopes, open the dedicated scope, and click "Add Mapper > By Configuration." Select "User Realm Role" or "User Attribute" depending on what your app needs.

A basic mapper configuration for roles looks like this:

Mapper Type:    User Realm Role
Token Claim Name: roles
Claim JSON Type:  String
Add to ID token:  On
Add to access token: On

Once the mapper is saved, use the Evaluate tab under Client Scopes to generate a sample token for a test user. Paste the access token into jwt.io to confirm the roles claim appears with the expected values before you connect your application.

Step 3. Configure SAML SSO for an app

SAML configuration in Keycloak follows a different path than OIDC, but the underlying structure is the same. You're still creating a client, mapping attributes, and testing the flow before connecting your application. The difference is that SAML relies on XML-based assertions and signed redirects rather than JSON tokens, which means the client setup involves more certificate management and metadata exchange between Keycloak and your service provider.

Create and configure the SAML client

Navigate to Clients > Create Client inside your realm and set the client type to "SAML." Assign a Client ID that matches your application's SP entity ID exactly. This value must match what your service provider sends in its authentication requests, so confirm it with your SP documentation before saving.

Fill in these fields on the configuration screen before saving the client:

• Root URL: Base URL of your service provider, e.g., https://app.example.com
• Valid Redirect URIs: The ACS (Assertion Consumer Service) URL your SP exposes, e.g., https://app.example.com/saml/acs
• Name ID Format: Set to email for most enterprise applications, or persistent if your SP tracks users by opaque identifiers
• Sign Assertions: Toggle On so Keycloak signs the SAML assertion with its realm certificate
• Signature Algorithm: Use RSA_SHA256 as the minimum; avoid RSA_SHA1 in any production deployment

Once you save the client, open the Keys tab and verify that "Client Signature Required" matches what your SP expects. If your SP does not sign AuthnRequests, toggle this Off or every incoming request will fail signature validation.

Download metadata and connect your service provider

After saving your SAML client, Keycloak generates an IdP metadata XML file that your service provider needs to complete the trust relationship. Retrieve it from this endpoint, replacing {realm} and {client-id} with your values:

https://your-keycloak-host/realms/{realm}/protocol/saml/descriptor

Your SP ingests this file to learn Keycloak's signing certificate, SSO endpoint, and logout endpoint automatically. Most enterprise applications and identity-aware platforms accept this URL directly so the metadata stays current when certificates rotate.

Once imported on the SP side, trigger a test login and capture the SAML response using your browser's developer tools or a SAML tracer extension. Confirm the NameID value and any mapped attributes match what your application expects before you move on to hardening the session configuration.

Step 4. Harden sessions, tokens, and logout

A completed keycloak sso configuration is not production-ready until you've locked down the token lifespans, session limits, and logout behavior. The default Keycloak settings are permissive by design, which makes development easier but leaves real security gaps in a live environment. Tokens that live too long and logout flows that only invalidate one side of a session are two of the most common issues that surface in security reviews.

Set token lifespans and session limits

Token lifespan settings live at the realm level under Realm Settings > Sessions and Realm Settings > Tokens. Keycloak separates access tokens, refresh tokens, and SSO session cookies, and each has its own expiry you control independently.

Use these values as a production-ready baseline and adjust tighter if your security policy requires it:

Setting	Recommended Value	Where to set it
Access Token Lifespan	5 minutes	Realm Settings > Tokens
Client Session Idle	30 minutes	Realm Settings > Sessions
SSO Session Idle	30 minutes	Realm Settings > Sessions
SSO Session Max	8 hours	Realm Settings > Sessions
Refresh Token Max Reuse	0	Realm Settings > Tokens

Setting Refresh Token Max Reuse to 0 forces Keycloak to issue a new refresh token on every refresh grant and invalidate the previous one. This closes the refresh token replay window that attackers exploit if a token leaks from a client-side cache or log.

For SMART on FHIR applications and any HIPAA-covered workflow, an access token lifespan above 15 minutes typically fails a security review. Keep it short and rely on refresh grants to maintain the session.

Configure logout correctly

Single logout is where most teams cut corners, and it directly impacts whether a user's session actually ends across all connected applications. For OIDC clients, enable both front-channel and back-channel logout so Keycloak notifies your app when it terminates a session.

Open your OIDC client settings and fill in the logout fields with your application's endpoint:

Front-channel logout URL:  https://app.example.com/logout/front
Backchannel logout URL:    https://app.example.com/logout/back
Backchannel logout session required: On

For SAML clients, confirm Single Logout Service URL is populated in your client's SAML settings. Without it, Keycloak cannot send the LogoutRequest to your SP, and the user's SP session stays alive even after the Keycloak session ends. Test both logout paths explicitly by checking active sessions in the Keycloak admin console under Users > Sessions after triggering a logout from your application.

Next steps

You now have a complete keycloak sso configuration covering realm setup, OIDC client configuration, SAML client configuration, and production-hardened session settings. From here, the logical next moves are testing your logout flows under real network conditions, setting up user federation with LDAP or Active Directory if you're sourcing identities from an external directory, and reviewing your mapper configurations against what your application actually reads from the token at runtime.

If you're integrating with EPIC EHR systems or building SMART on FHIR applications that need to meet HIPAA compliance requirements, identity configuration is just one layer of a more complex infrastructure problem. Getting the auth layer right matters, but so does the FHIR data access layer, the clinical workflow logic, and the App Orchard submission process. VectorCare handles all of that for healthcare vendors who want to skip the engineering overhead entirely. See how VectorCare accelerates SMART on FHIR deployment.