Configuring Keycloak as a SAML Service Provider

Introduction

In this article, we demonstrate how to use Okta as a SAML Identity Provider (IdP) and configure Keycloak as a SAML Service Provider (SP) using Keycloak’s Identity Brokering feature.

With this setup, your applications—whether OIDC or SAML—can authenticate users stored in Okta through Keycloak, without modifying application code.

Brief Overview of SAML

What is SAML?

Security Assertion Markup Language (SAML) is an XML-based framework that enables identity and authentication information to be securely exchanged between online business partners.

For more details you may visit official documentation available here.

In SAML:

• Identity Provider (IdP): where the user authenticates (in our case: Okta)
• Service Provider (SP): the relying party that consumes authentication assertions (in our case: Keycloak)

The IdP issues SAML Assertions, which are signed XML documents containing:

• Authentication information
• Optional user attributes
• Optional authorization data

SAML Flows

SAML supports two main flows:

1. SP-Initiated Flow
2. IdP-Initiated Flow

In this article, we focus on the SP-Initiated Flow.

Because Keycloak is the SP, users will start authentication from the Keycloak login page by clicking “Sign in with Okta”.

How SP-Initiated Authentication Works

1. User navigates to Keycloak-protected application -> redirected to Keycloak login page.
2. User clicks “Sign in with Okta”.
3. Keycloak (SP) generates a SAML Authentication Request.
4. The request is sent through the browser to Okta.
5. Okta identifies the registered SP configuration.
6. Okta prompts the user to authenticate (password, MFA, etc.).
7. After successful authentication, Okta creates a session.
8. Okta generates a signed SAML Assertion.
9. Okta sends the assertion to Keycloak via HTTP POST binding.
10. Keycloak validates the XML signature using Okta’s public certificate.
11. If valid, Keycloak creates (or maps) a local user automatically.
12. The user session is established, and the user is logged in to Keycloak.
13. Keycloak redirects the user to the application.

Configuration Steps

Configuration Steps

The configuration involves two main parts:

1. Configure Okta (as SAML IdP)
2. Configure Keycloak (as SAML SP)

Part 1: Configure at Okta as SAML IDP

Step 1: Log in to Okta console and choose a SAML application

Go to:

1. Navigate to:
   Applications → Applications → Create App Integration
2. Choose:
   • Sign-in method: SAML 2.0
3. Click Next.

Step 2: Configure SAML settings

In General Settings:

• App Name: kc-client

Click Next.

Step 3: Configure SAML – SAML settings

Fill the following fields:

Single Sign-On URL (Assertion Consumer Service – ACS URL)

Use Keycloak’s SAML broker ACS URL:

https://<skycloak-domain>/realms/<realm-name>/broker/<idp-alias>/endpoint

Substitute at the above place holders with actual Skycloak host name , realm name. For idp_alias give as okta

select checkbox – Use this for Recipient URL and Destination URL

Audience URI(SP Entity ID)

Use Keycloak’s broker Entity ID:

https://<skycloak-domain>/realms/<realm-name>

Substitute at the above place holders with actual Skycloak host name , realm name

Name ID Format

Unspecified

This ensures Okta sends the Okta username in the SAML NameID (recommended if you want username-based mapping).

Click Next -> Finish.

Go to:

Assignments ->Assign People -> Add users

Assign test users to the application.

Step 3: Copy the metadata URL

Go to:

Sign-On -> Metadata details -> Copy the Metadata URL

You will use this URL in Keycloak.

Part 2: Configure Keycloak as SP

Step 1: Add Okta 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 okta

Import metadata from URL

Paste the metadata URL you copied from Okta.

Click Show metadata for Import.

This automatically fills:

• SSO URL (SingleSignOnService)
• SLO URL
• IdP public certificate

Step 2: Verify Redirect URI

The Redirect URI displayed by Keycloak must match the ACS URL you provided in Okta

https://<skycloak-domain>/realms/<realm-name>/broker/okta/endpoint

If correct -> proceed.

Step 3: Save the Identity Provider

Click Add to save

Testing the Integration

1. Open a Keycloak-protected application or visit the Keycloak account console.
2. At the login page, click “Sign in with Okta”.
3. Authenticate at Okta.
4. Okta returns a signed SAML Assertion.
5. Keycloak logs you in and creates a user entry using the NameID (Okta username).
6. Attributes like email, first name and last name we have not populated in this article. Hence Keycloak will prompt you to enter them on first login.

Summary

In this article, we configured:

• Okta as a SAML Identity Provider
• Keycloak 26.x (Skycloak) as a SAML Service Provider
• ‘SP-initiated login flow from Keycloak
• User mapping based on NameID = Okta username

Skycloak provides production-ready managed Keycloak hosting, helping teams avoid the complexity of maintaining and scaling Keycloak themselves.

If you’re new to Skycloak, visit the Skycloak Getting Started Guide to learn more.