Skycloak Identity Providers Recipe: Add OIDC or SAML IdP in 5 Minutes

Last updated: September 2026

Adding an external identity provider to Skycloak (or upstream Keycloak) is a five-minute task once you know the steps. Whether you are connecting Google for social login, Entra ID for workforce SSO, or a customer’s Okta tenant for B2B federation, the process follows the same pattern: configure the IdP, add it to Keycloak, map attributes, and test.

This is the canonical recipe. It covers OIDC and SAML providers, includes step-by-step instructions for the most common IdPs (Google, Entra ID, Okta), and explains troubleshooting and domain routing. By the end, you will know how to add any identity provider to Skycloak.

What is an identity provider in Keycloak?

An identity provider (IdP) is an external authentication service that Keycloak trusts to verify user identities. Instead of storing usernames and passwords locally, Keycloak delegates authentication to the IdP and receives an assertion or token proving the user is who they claim to be.

Common identity providers include:

• Social providers: Google, GitHub, Apple, Facebook.
• Enterprise IdPs: Microsoft Entra ID (Azure AD), Okta, ADFS, PingFederate.
• Workforce directories: LDAP, Active Directory (via SAML or Kerberos).
• Other OIDC or SAML-compliant services.

Keycloak acts as an identity broker: users authenticate with the external IdP, and Keycloak creates or updates their local account and issues tokens to your applications.

For federated SSO architecture, see Federated SSO vs a Single IdP: When You Need an Identity Hub.

OIDC vs SAML: which protocol to use

Both OpenID Connect (OIDC) and SAML 2.0 achieve the same outcome (federated authentication), but they use different formats and workflows.

Rule of thumb: Use OIDC unless the IdP only supports SAML. Google, GitHub, and most modern IdPs prefer OIDC. Entra ID and Okta support both (use OIDC). ADFS and legacy enterprise IdPs often require SAML.

Prerequisites

Before adding an identity provider to Skycloak:

1. A Skycloak account or self-hosted Keycloak 26.x instance. This guide uses Skycloak, but the steps are identical on upstream Keycloak.
2. Admin access to your realm. You need permission to create identity providers and mappers.
3. Credentials from the external IdP. For OIDC: client ID, client secret, and discovery URL. For SAML: metadata XML or URL.

Recipe: Add an OIDC identity provider

Skycloak provides guided recipe wizards for common OIDC integrations. For Microsoft Entra ID (Azure AD), the fastest path is the built-in recipe. For other providers or self-hosted Keycloak, use the universal manual method below.

Recommended: Use the Azure AD SSO recipe (for Microsoft Entra ID)

For Microsoft Entra ID OIDC integration:

1. Log into your Skycloak account.
2. Navigate to Recipes in the left sidebar.
3. Select Azure AD SSO Integration from the recipe list.
4. Click Start Recipe.
5. Follow the guided wizard, which walks you through:
   • Creating the app registration in Azure Portal
   • Setting the correct redirect URI
   • Copying the Client ID and Client Secret into Skycloak
   • Configuring attribute mappers for email, first name, and last name
   • Testing the integration end-to-end

The recipe handles OIDC discovery, trust settings, and first login flows automatically. This is the fastest way to connect Entra ID to Skycloak.

Alternative: Universal manual method (for Google, Okta, GitHub, or self-hosted Keycloak)

For providers without a recipe, or when using self-hosted Keycloak 26.x, follow these steps.

Step 1: Get credentials from the IdP

Every OIDC provider requires you to register an OAuth application. The outcome is: client ID, client secret, and discovery URL.

Google example:

1. Go to the Google Cloud Console.
2. Navigate to APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client ID.
3. Choose Web application.
4. Add redirect URI: https://your-realm.skycloak.io/realms/your-realm/broker/google/endpoint.
5. Copy the Client ID, Client Secret, and note the discovery URL: https://accounts.google.com/.well-known/openid-configuration.

Okta example:

1. Log into Okta Admin Console.
2. Go to Applications > Create App Integration > OIDC > Web Application.
3. Set redirect URI to https://your-realm.skycloak.io/realms/your-realm/broker/okta/endpoint.
4. Copy Client ID, Client Secret, and note the discovery URL: https://your-org.okta.com/.well-known/openid-configuration.

Step 2: Add the IdP to Keycloak

1. Log into the Keycloak admin console at https://your-realm.skycloak.io/admin/.
2. Select your realm, click Identity providers > Add provider > OpenID Connect v1.0.
3. Configure:

4. Click Add.

Step 3: Verify the redirect URI

After saving, Keycloak displays the Redirect URI. Go back to the IdP’s OAuth app and verify it matches.

Step 4: Add attribute mappers

Attribute mappers pull user attributes from the IdP’s ID token and store them in Keycloak’s user profile. Without mappers, users log in successfully but have blank names and missing attributes.

1. Go to Identity providers > [your-provider] > Mappers.
2. Click Add mapper.
3. Add a mapper for each attribute you need:

Mapper configuration example (email):

Click Save and repeat for other attributes.

To inspect the claims an IdP sends, use the JWT Token Analyzer.

Step 5: Test the integration

1. Open the Keycloak account console: https://your-realm.skycloak.io/realms/your-realm/account/.
2. You should see a button labeled with your IdP’s display name (e.g., “Sign in with Google”).
3. Click it.
4. Authenticate with the external IdP.
5. You should be redirected back to Keycloak and logged in.
6. Verify the user appears in Users with email, first name, and last name populated.

For deeper OIDC brokering details, see the Keycloak identity providers documentation, the Keycloak identity providers feature page, and the enterprise SSO setup guide.

Recipe: Add a SAML identity provider

SAML identity providers use XML metadata exchange instead of OIDC discovery. The setup is similar, but you import metadata instead of entering a discovery URL.

Step 1: Get SAML metadata from the IdP

Every SAML IdP publishes a metadata XML document. For example:

• Okta: Download from the SAML app’s Sign On tab.
• Entra ID: Download Federation Metadata XML from the Enterprise Application’s SAML configuration.
• ADFS: https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml.

Some IdPs provide a metadata URL, others require you to download the XML file. Either works.

Step 2: Add the IdP to Keycloak

1. Log into the Keycloak admin console.
2. Select your realm.
3. Go to Identity providers > Add provider > SAML v2.0.

Step 3: Import metadata

At the top of the form, use the Import from file or Import from URL control:

• File: Upload the metadata XML you downloaded.
• URL: Paste the metadata URL (e.g., https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml).

Keycloak auto-populates:

• Single Sign-On service URL
• Single Logout service URL
• Validating X509 certificate (the IdP’s signing certificate)

Step 4: Configure provider settings

Click Add.

Step 5: Copy the ACS URL

After saving, Keycloak displays the Redirect URI (also called the Assertion Consumer Service URL):

https://your-realm.skycloak.io/realms/your-realm/broker/okta/endpoint

Go back to the IdP’s SAML app configuration and add this URL as the ACS URL or Reply URL. If it is missing or incorrect, SAML assertions will fail with an invalid ACS error.

Step 6: Add attribute mappers

SAML attribute names vary by IdP. Common patterns:

Entra ID:

Okta:

Add mappers:

1. Go to Identity providers > [your-provider] > Mappers.
2. Click Add mapper.
3. Set Mapper type to Attribute Importer.
4. Enter the Attribute Name (the SAML attribute from the IdP).
5. Enter the User Attribute Name (the Keycloak attribute).
6. Click Save.

To inspect SAML assertions, use the SAML Decoder tool.

For a complete Entra ID SAML walkthrough, see How to Set Entra ID SAML in Keycloak as an IdP.

Step 7: Test the integration

Same as OIDC: open the account console, click the IdP button, authenticate, and verify the user is created with correct attributes.

Domain routing with Organizations

If you are using the Organizations feature (Keycloak 25+) for B2B multitenancy, you can link each Organization to a specific identity provider and enable automatic domain routing.

Setup

1. Enable Organizations in Realm Settings.
2. Create an Organization for each customer: Organizations > Create organization.
3. Add the customer’s domain (e.g., acme.com).
4. Go to Identity Providers tab and click Link Identity Provider.
5. Select the IdP you created above.
6. Enable Redirect when email domain matches.

Now when a user enters [email protected], Keycloak automatically redirects them to the linked IdP.

For full details, see Multitenancy in Keycloak Using the Organizations Feature and Federated Identity Management for B2B SaaS on Skycloak Organizations.

Brokering deep dives (links to existing guides)

This recipe covers the basics. For specific IdP integrations and advanced brokering topics, see:

• SAML brokering: How to Set Entra ID SAML in Keycloak as an IdP
• OIDC brokering and attribute mapping: Attribute Mapping in Keycloak During OIDC Identity Brokering
• FusionAuth as IdP: Using Keycloak Identity Brokering to Connect FusionAuth as an External IdP
• GitHub social login: Using Keycloak Identity Brokering to Add GitHub Social Login
• Skip IdP selection with kc_idp_hint: Use kc_idp_hint to Choose Identity Provider in Keycloak

Troubleshooting

Redirect URI mismatch

Symptom: After clicking the IdP button, you see redirect_uri_mismatch or a similar error.

Cause: The redirect URI configured in the external IdP does not match the one Keycloak generated.

Fix:

1. Go to Identity providers > [your-provider] in Keycloak and copy the Redirect URI.
2. Go to the external IdP’s app configuration and add that exact URL as an authorized redirect URI.
3. Watch for trailing slashes, HTTP vs HTTPS, and typos.

User attributes not populating

Symptom: Users authenticate successfully, but their email, name, or other attributes are blank in Keycloak.

Cause: Attribute mappers are missing or misconfigured.

Fix:

1. Inspect the token or assertion the IdP sends. For OIDC, use the JWT Token Analyzer. For SAML, use the SAML Decoder.
2. Compare the claim or attribute names in the token against the mappers you configured in Keycloak.
3. Update the mappers to match the exact claim names the IdP sends.

Clock skew errors (SAML only)

Symptom: SAML authentication fails with a ProcessingException about timing or NotBefore.

Cause: The Keycloak server’s clock and the IdP’s clock are out of sync.

Fix:

1. Ensure your Keycloak server uses NTP for time synchronization: timedatectl set-ntp true.
2. In Keycloak, go to Identity providers > [your-provider] and increase Allowed clock skew to 30-60 seconds.

Certificate validation failures (SAML only)

Symptom: SAML authentication fails with Signature validation failed or No signing certificate configured.

Cause: The IdP’s signing certificate in Keycloak does not match the one the IdP is currently using (often after a certificate rollover).

Fix:

1. Download fresh metadata XML from the IdP.
2. In Keycloak, go to Identity providers > [your-provider] and re-import the metadata.
3. This updates the Validating X509 certificate field with the current certificate.

In-app recipes vs manual setup

Skycloak ships an in-app Azure AD SSO Integration recipe (Recipes sidebar) that walks you through connecting Microsoft Entra ID as an OIDC identity provider. That is the recommended path for Entra ID and is covered in the OIDC section above.

For other providers (Google, Okta, GitHub, generic OIDC/SAML), there is not yet a dedicated guided recipe card. Use the universal manual method in this guide, the provider templates on the Identity Providers page, or the Skycloak identity providers docs. Feedback on which additional recipes would help most is welcome.

Frequently asked questions

What identity providers does Keycloak support?

Keycloak supports any OIDC or SAML 2.0 compliant identity provider. Common examples: Google, Microsoft Entra ID (Azure AD), Okta, GitHub, Apple, ADFS, PingFederate, Auth0, FusionAuth, and any custom OIDC or SAML service. Pre-configured templates exist for major providers (Google, Azure, GitHub, etc.), but the generic OIDC and SAML options work for any IdP.

Should I use OIDC or SAML for my identity provider?

Use OIDC unless the IdP only supports SAML. OIDC is lighter (JSON/JWT vs XML), has automatic discovery via .well-known/openid-configuration, and works better on mobile. SAML is still common in enterprise IdPs (Entra ID, Okta support both, ADFS is SAML-only). If the IdP offers both, choose OIDC.

How do I route users to the correct IdP automatically?

Use the kc_idp_hint parameter in the authorization URL to force a specific IdP, or use the Organizations feature (Keycloak 25+) to configure domain-based routing natively. With Organizations, you assign each customer org a domain (e.g., acme.com), link it to an IdP, and Keycloak automatically redirects users based on their email domain. See Use kc_idp_hint to Choose Identity Provider and Multitenancy in Keycloak Using the Organizations Feature.

Can I add multiple identity providers to one realm?

Yes. One Keycloak realm supports unlimited identity providers (OIDC, SAML, social, etc.). Users choose which IdP to use at login, or your app routes them automatically via kc_idp_hint or Organizations domain routing. This is the standard pattern for B2B SaaS: each customer brings their own IdP, and they all coexist in one realm.

What attribute mappers should I configure?

At minimum, map email, firstName, and lastName. For OIDC, these typically come from the email, given_name, and family_name claims. For SAML, claim names vary by IdP (see the SAML attribute mapper section above). Inspect the token or assertion with the JWT Analyzer or SAML Decoder to see exactly what the IdP sends.

Conclusion

Adding an identity provider to Skycloak or Keycloak is a five-minute recipe: get credentials from the IdP, add the IdP to Keycloak (OIDC or SAML), configure attribute mappers, and test. OIDC providers use discovery URLs, SAML providers use metadata exchange, and both follow the same attribute mapping pattern.

For federated SSO architecture, see Federated SSO vs a Single IdP: When You Need an Identity Hub. For B2B multitenancy with per-customer IdPs, see Federated Identity Management for B2B SaaS on Skycloak Organizations. For managed Keycloak hosting with built-in identity provider support, see Skycloak’s Identity Providers feature or start with the Skycloak documentation.