Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Identity Brokering and Social Login

External OIDC and SAML Identity Providers

Connect Keycloak to a corporate OpenID Connect or SAML 2.0 identity provider: discovery import, metadata exchange, claim and attribute mappers, and role mapping.

Social buttons cover consumers. Business customers bring their own identity systems: Microsoft Entra ID, Okta, Ping, ADFS, or another Keycloak. For those you add a generic OpenID Connect v1.0 or SAML v2.0 provider. The setup takes a few more steps than a social button, and most of the real work happens in mappers, which translate what the provider says about a user into attributes and roles in your realm.

Keycloak does not run on this site. The mapping code below is a JavaScript stand-in that models how mappers behave so you can test rules safely.

Adding an OpenID Connect provider

Under Identity providers, choose OpenID Connect v1.0. Set an alias such as acme-oidc. Then supply the provider's endpoints in one of two ways:

  • Discovery: paste the provider's discovery URL (the /.well-known/openid-configuration document) into Discovery endpoint. Keycloak fills the authorization, token, user info, JWKS, and logout URLs.
  • Manual: type each endpoint yourself if discovery is unavailable.

Then set the Client authentication method (client secret, private key JWT, or none for public clients), the Client ID and secret issued by the provider, and keep Validate signatures on with the provider's JWKS URL so that incoming ID tokens are checked. Copy the Keycloak redirect URI back to the provider, as in social login.

Useful options:

  • Scopes: extra scopes beyond openid, such as profile email groups.
  • Pass login_hint and Pass current locale: forward helpful hints.
  • Use PKCE: enable PKCE toward the provider when it supports it.
  • Allowed clock skew: tolerate small time differences between servers.

Adding a SAML provider

Choose SAML v2.0. Here the exchange is metadata-based:

  1. Import the provider's IdP metadata XML (by URL or file) into Keycloak: it contains the single sign-on URL, the entity ID and the signing certificate.
  2. Download Keycloak's service provider metadata from the provider's page (the SAML SP descriptor link) and upload it into the IdP's console, so the IdP knows your Assertion Consumer Service URL and entity ID.
  3. Set the NameID policy format to match what the IdP sends (persistent, email, or unspecified), and decide whether to want assertions signed.

SAML identities identify the user with a NameID, which plays the same role as sub in OIDC. Attributes travel inside the assertion as named Attribute elements.

Mappers: translating claims into users

On the Mappers tab of an IdP you add rules that run on every login (or first login, depending on sync mode). Common mapper types:

Mapper What it does
Attribute Importer Copies a claim or SAML attribute to a user attribute
Claim to Role / SAML Attribute to Role Grants a realm or client role when a claim has a given value
Hardcoded Role / Attribute / Group Gives every user from this IdP the same role, attribute, or group
Username Template Importer Builds the username from a template
Advanced Claim to Role Matches several claims with regular expressions

Here is a small stand-in showing how claim rules produce a user and roles:

JS Stand-in: claim mappers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Reading what the IdP actually sent

When a mapper does not behave, look at the raw claims. An OIDC ID token is three base64url parts separated by dots; the middle part is JSON. The Store tokens setting and the debug log help in Keycloak, and this helper shows how decoding works:

JS Stand-in: decode the claims of an ID token

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Sync mode and updates

If you set the mapper Sync mode override to force, role grants and attributes are recalculated at every login, so removing someone from the finance group at the IdP removes the Keycloak role at their next login. With import, the value is set once and later changes at the IdP are ignored. Pick force for roles that must follow the corporate directory, and import for attributes users may edit locally.

Multiple tenants and discovery of the right IdP

SaaS products often have one external IdP per customer. Two patterns appear:

  • One Keycloak realm with many IdPs, plus a custom step that picks the provider from the user's email domain. Newer Keycloak versions support this through Organizations, where each organization can own a domain and a linked IdP. See the multi-tenant design project.
  • One realm per customer, which isolates everything but multiplies operations.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the discovery endpoint save you from doing?

    The /.well-known/openid-configuration document lists the authorization, token, JWKS, and other endpoints, and Keycloak imports them.
  2. 2. In SAML brokering, which items must be exchanged between Keycloak and the IdP?

    Each side needs the other's endpoints, entity ID and certificate, which are carried in metadata documents.
  3. 3. Which sync mode makes roles follow the IdP at every login?

    force overwrites the mapped values at each login, so changes at the IdP take effect immediately.
  4. 4. Is decoding the payload of an ID token the same as validating it?

    Anyone can base64-decode a JWT. Trust comes from verifying the signature and the claims.

Summary

  • Generic OIDC providers use discovery; SAML providers exchange metadata.
  • Mappers turn claims or attributes into user attributes, roles, groups, and usernames.
  • Sync mode decides whether values refresh at each login.
  • Always verify signatures; decoding a token proves nothing.
  • Multi-tenant products need a plan for choosing the right provider per user.

Next: LDAP and Active Directory User Federation