Keycloak’s SAML integration lets you delegate authentication to external identity providers (IdPs) like Okta, Azure AD, or ADFS, so your users don’t need a separate Keycloak login.
Let’s see this in action. Imagine we have a Keycloak realm named myrealm and we want to use Okta as our external IdP.
First, in Okta, you’d create a SAML application. This involves providing some basic information and then, crucially, downloading Okta’s SAML signing certificate and noting down its Entity ID and SSO URL.
{
"oidc": {
"issuer": "https://mycompany.okta.com/app/mycompany_myapp_1/sso/saml/metadata",
"authorization_endpoint": "https://mycompany.okta.com/app/mycompany_myapp_1/sso/saml",
"jwks_uri": "https://mycompany.okta.com/app/mycompany_myapp_1/sso/saml/descriptor",
"token_endpoint": "https://mycompany.okta.com/app/mycompany_myapp_1/sso/saml",
"userinfo_endpoint": "https://mycompany.okta.com/app/mycompany_myapp_1/sso/saml"
}
}
In Keycloak, you navigate to myrealm -> Identity Providers -> Add provider and select SAML.
You’ll need to fill in the following fields, mapping directly from your Okta configuration:
- Alias: A unique name for this provider in Keycloak, e.g.,
okta-idp. - Display Name: What users see on the login screen, e.g.,
Login with Okta. - Enabled: Set to
On. - Import Users: Set to
Onif you want Keycloak to automatically create user accounts based on SAML assertions. - First Login Flow: Typically
first login. - Validating Users: This is where you paste the contents of Okta’s SAML signing certificate.
- Single Sign On Service URL: The SSO URL from Okta.
- Single Logout Service URL: Often the same as the SSO URL, or a dedicated SLO endpoint if Okta provides one.
- Name ID Format: Usually
Unspecified. - Signing Certificate: Paste the content of the
.cerfile downloaded from Okta. - Client ID: This is Okta’s Entity ID.
- Client Secret: Not used in SAML, leave blank.
After saving, Keycloak will present you with its own SAML metadata URL. You’ll need to take this URL and configure it within your Okta SAML application. This is the crucial handshake: Keycloak tells Okta who it is, and Okta tells Keycloak how to trust it for authentication.
The fundamental problem Keycloak’s SAML IdP integration solves is centralizing authentication. Instead of managing user credentials for every application, you can leverage an existing, trusted IdP. Keycloak acts as a Service Provider (SP), relying on the external IdP for the actual user verification. When a user tries to access a Keycloak-protected application, Keycloak redirects them to the external IdP. The IdP authenticates the user and sends a SAML assertion back to Keycloak. Keycloak validates this assertion, and if successful, issues its own token (like an OIDC token) to the user, granting them access to the application.
The Name ID field in the SAML assertion is how the IdP identifies the user. Keycloak can be configured to map this Name ID to a specific attribute in the user’s Keycloak profile, such as their email address or username. This is configured under myrealm -> Identity Providers -> [Your IdP Alias] -> Mappers. A common mapping is Username Template Integrator where you can use %{username} or %{email} to populate the Keycloak username field from the SAML assertion.
When you configure the Validating Users field in Keycloak, you’re providing the public key of the external IdP. Keycloak uses this public key to verify the digital signature on the SAML assertion sent by the IdP. This signature proves that the assertion hasn’t been tampered with in transit and that it genuinely originated from the trusted IdP. If the signature verification fails, Keycloak rejects the assertion, preventing unauthorized access.
The Client ID in Keycloak’s SAML IdP configuration corresponds to the Entity ID of the external IdP. This is a globally unique identifier for the IdP. Keycloak uses this to know which external IdP it’s trying to communicate with, especially when you have multiple IdPs configured. The external IdP, in turn, will likely have its own configuration referencing Keycloak’s Entity ID as the Service Provider. This mutual identification is essential for establishing trust.
A subtle but powerful aspect of SAML integration is the ability to control which users from the external IdP are allowed to log in. This is often managed through attribute statements within the SAML assertion. For instance, the IdP might send an attribute like memberOf with a value of App-Users. In Keycloak, you can configure a Role Importer mapper to only grant access if this attribute is present and matches a specific value. This allows for fine-grained access control at the IdP level that Keycloak respects.
The next step is often configuring logout, ensuring that when a user logs out of Keycloak, they are also logged out of the external IdP, and vice-versa.