Sessions-clients

Bridging IdP-Initiated SAML to OIDC with Keycloak

by

Introduction

In this article, we discuss how to enable access to an OIDC-based custom application using an IdP-initiated SAML flow, with Keycloak acting as the Service Provider (SP) and Auth0 acting as the SAML Identity Provider (IdP).

As per the OpenID Connect (OIDC) specification, there is no concept of an IdP-initiated login flow. OIDC strictly supports SP-initiated (client-initiated) authentication. However, in real-world enterprise scenarios, there are business requirements where authentication must start from an external IdP. In such cases, a controlled workaround can be implemented.

Recommendation: Always prefer SP-initiated flows wherever possible. The approach described in this article should be used only when an IdP-initiated flow is mandatory.

High-Level Overview of the Approach

The solution involves bridging an IdP-initiated SAML flow into an SP-initiated OIDC flow using Keycloak’s identity brokering capabilities.

Flow Summary

  1. Authentication is initiated at Auth0 using an IdP-initiated SAML flow
  2. Auth0 sends a SAML assertion to Keycloak, which acts as a SAML SP
  3. Keycloak forwards the SAML response (Redirect binding) to a custom, unprotected endpoint in the application
  4. The application does not process or validate the SAML assertion
  5. The application redirects the user to a protected OIDC endpoint
  6. This triggers an OIDC Authorization Code flow with kc_idp_hint
  7. Keycloak reuses the existing brokered Auth0 session, enabling seamless login

What We Will Configure

To implement this flow, we need the following components:

  1. A SAML Identity Provider configured in Keycloak (Auth0 as IdP)
  2. An Auth0 application configured for SAML IdP-initiated login
  3. A SAML client in Keycloak (used only for IdP-initiated entry)
  4. An OIDC client in Keycloak
  5. An OIDC-based application that sends kc_idp_hint in the authorization request

For steps related to OIDC client creation and kc_idp_hint usage, you may refer to an existing OIDC integration article available here. In this setup, the key substitution is:

additionalParams.put("kc_idp_hint", "auth0-saml");

Note:If you are using an IdP other than Auth0, ensure it supports IdP-initiated SAML and allows configuration of multiple callback URLs

For more details on IDEP initiated login, please refer the Keycloak System admin guide.

Configure Auth0 as SAML IDP

In Auth0, you must create an application that acts as the SAML bridge and enables the IdP-initiated flow. 

  • Create Application: In the Auth0 Dashboard, navigate to Applications > Applications and create a “Regular Web Application”.
  • Enable SAML2 Addon: Under the Addons tab, toggle SAML2 Web App to enabled.
  • Configure Settings: In the SAML2 Web App settings:
    • Application Callback URL: Provide the Keycloak IdP-initiated SAML client endpoint:.(sample format https://{keycloak-domain}/realms/{realmname}/broker/{alias}/endpoint/clients/{IDP_initated_URL_name}.
    • Settings JSON (Sample)
{
  "audience": "https://{your_keycloak_domain}/realms/{realm-name}",
  "recipient": "https://{your_keycloak_domain}/realms/{realm-name}/broker/{alias}/endpoint"
}

in this demo, I am using place holders alias as auth0-saml and IDP_initated_URL_name as auth0-client.

The value of IDP_INITIATED_URL_NAME must match the “IdP-Initiated SSO URL Name” configured in the Keycloak SAML client. (we are yet to come to that)

  • Copy IdP Metadata

From the Usage tab of the Auth0 application, copy the Identity Provider Metadata URL.
This will be imported into Keycloak.

Configuring Keycloak as a SAML Service Provider

Step 1: Add Auth0 as a SAML Identity Provider

  1. Log in to Keycloak Admin Console.
  2. Navigate to: Identity Providers -> Add provider -> SAML v2.0
  3. Provide: Alias as auth0-saml

Import metadata from URL

Paste the metadata URL you copied from Auth0

Click Show metadata for Import.

Verify:

  • SSO URL
  • SLO URL
  • IdP public certificate

You can also turn on Validate Signature
Step 2: Verify Redirect URI

Ensure the broker endpoint matches the recipient configured in Auth0

https://{your_keycloak_domain}/realms/<realm-name>/broker/auth0-saml/endpoint

If correct -> proceed.

Step 3: Save the Identity Provider

Click Add to save

Create SAML client in Keycloak

  1. Navigate to Clients ->Create client
  2. Select SAML as the client type

Client Settings

  • Valid Redirect URIs http://localhost:9089/*
  • Valid Post Logout Redirect URIs http://localhost:9089/*

Advanced Settings

Navigate to Advanced -> Fine-Grain SAML Endpoint Configuration

  • Assertion Consumer Service Redirect Binding URL http://localhost:9089/customep

Additional Settings

  • Disable Force POST Binding

Testing the SAML Flow

Initiate an IdP-initiated login from Auth0:

https://{your-auth0-domain}/samlp/{auth0-saml-client-id}

You should see the SAML assertion being sent to:

http://localhost:9089/customep

OIDC Configuration

Ensure the following are already configured:

  • An OIDC client in Keycloak
  • A Spring Boot OIDC application
  • The application sends kc_idp_hint=auth0-saml in the authorization request

Handling the Assertion in the Application

The application exposes an unprotected endpoint to receive the SAML Redirect binding.

// Spring Boot sample
@GetMapping("/customep")
public String receiveAssertion() {
    // Do NOT parse or validate the SAML response
    return "redirect:http://localhost:9089";
}

The redirect points to a secured OIDC endpoint, which triggers an OIDC Authorization Code flow with Keycloak.

Security Note:
The application must never process or trust the SAML assertion.
SAML validation and trust decisions must remain entirely within Keycloak.

Additional Auth0 change

Since the application now triggers an SP-initiated OIDC flow, Auth0 must allow the corresponding callback.

  1. Navigate to Applications -> Applications -> {SAML App} → Settings
  2. Add the Allowed Callback URLs https://{keycloak-domain}/realms/{realmname}/broker/{alias}/endpoint/clients/{IDP_initated_URL_name},https://{keycloak-domain}/realms/{realmname}/broker/{alias}/endpoint

Allowed Callback URLs

Auth0 Settings tab snippet

Note: I had been using local Keycloak for this test. You will have to specify your Skycloak host name

Separate multiple URLs using commas.

Testing the complete flow

Access the IdP-initiated SAML URL:

https://{your-auth0-domain}/samlp/{auth0-saml-client-id}

Expected result:

  • User is authenticated via Auth0
  • SAML session is established in Keycloak
  • OIDC login is triggered automatically
  • User lands in the OIDC application without reauthentication

In the Keycloak Admin Console → Sessions, you should see both:

  • The SAML client
  • The OIDC client
SAML tracer screen shot

Summary

In this article, we demonstrated how access to an OIDC application can be enabled using an IdP-initiated SAML flow by leveraging Keycloak’s identity brokering features.

While SP-initiated authentication is always recommended, this approach provides a reliable workaround when an IdP-initiated scenario is unavoidable due to business constraints.

If you’re new to Skycloak, visit the Skycloak Getting Started Guide to learn more and securing your Keycloak deployments.

Skycloak is a fully managed Keycloak platform hosted in the cloud. It enables organizations to leverage the powerful capabilities of the open-source Keycloak Identity and Access Management (IAM) solution without the operational overhead of installing, maintaining, and scaling Keycloak for production-grade environments. All of this is delivered in a secure and cost-effective manner.

Leave a Comment

© 2026 All Rights Reserved. Made by Yasser