Skip to content

Federated identity and custom claims

Keycloak supports federating identities from external providers such as Google, Microsoft, GitHub, or any SAML/OIDC provider. You can also enrich the tokens issued to your application with additional attributes from user profiles or custom (unmanaged) attributes.

Adding an identity provider

  1. Log in to the Keycloak admin console and select your application realm

  2. Navigate to Identity providers and click Add provider

  3. Choose a social provider (Google, GitHub, Microsoft, …) or a standard protocol:

Type When to use
OpenID Connect Any OIDC-compliant provider
SAML Enterprise SSO, Active Directory Federation Services
Social logins Built-in connectors for popular platforms

  1. Fill in the provider-specific settings (client ID, client secret, issuer URL, etc.)

    Tip

    The Redirect URI that you need to register in the external provider's application settings (e.g. the callback URL in a GitHub OAuth app) is shown at the top of this page in the Keycloak admin console.

  2. Click Save

  3. Optionally enable Trust email if the provider already verifies email addresses, to skip re-verification

Refer to the Keycloak identity provider documentation for step-by-step instructions for each provider type.

Adding custom claims to the token

Keycloak uses protocol mappers to include additional attributes in the access and ID tokens sent to your application.

From user profile attributes

User profile attributes are managed fields visible in the Keycloak admin console under Users → select a user → Attributes.

  1. Navigate to Clients → select your client → Client scopes → select the dedicated scope → Add mapper → By configuration

  2. Choose User Attribute

  3. Set User Attribute to the attribute name and Token Claim Name to the claim name that will appear in the token

  4. Choose the token types to include the claim in (access token, ID token, userinfo) and click Save

See the Keycloak protocol mappers documentation for all available mapper types.

From unmanaged attributes

Unmanaged attributes are arbitrary key-value pairs that are not declared in the user profile schema. They are useful for ad-hoc or migration scenarios.

  1. Navigate to Realm settings → User profile → Settings and set Unmanaged attributes to Enabled (or Admin can view and edit for a more restricted policy)

  2. Add the attribute value to a user under Users → select a user → Attributes

  3. Create a User Attribute mapper (as described above) pointing to the same attribute name

Note

Unmanaged attributes bypass user-profile validation. For production use, prefer declaring attributes explicitly in the user profile schema. See the Keycloak user profile documentation for details.

From identity provider claims

When a user authenticates through a federated identity provider, you can map claims from the provider's token into your realm token:

  1. Navigate to Identity providers → select your provider → Mappers → Add mapper

  2. Choose a mapper type such as Attribute Importer to copy a provider claim into a user attribute, then expose that attribute via a protocol mapper as described above

See the identity provider mapper documentation for the full list of available mapper types.

Disabling username and password login

If you want users to authenticate exclusively through a federated identity provider, you can disable the local username/password flow:

  1. Navigate to Authentication → Flows

  2. Select the browser flow and disable (or delete) the Username Password Form step

  3. Alternatively, navigate to Realm settings → Login and disable User registration and any password-related settings to prevent new local accounts from being created

  4. To hide the login form entirely and redirect users straight to the identity provider, navigate to Identity providers → select your provider → enable Hide on login page for all other providers, then set the provider as the default by enabling Default identity provider under Authentication → Flows → browser flow → add an Identity Provider Redirector step configured to your provider

Warning

Before disabling local login, ensure at least one realm administrator account can still authenticate (for example via a separate admin-only flow or by keeping a local admin account). Locking yourself out of the admin console will require direct database access to recover.

Refer to the Keycloak authentication flows documentation for full details on customizing authentication flows.