Keycloak Identity Brokering with FusionAuth

Introduction

In this article, we demonstrate how to use FusionAuth as an external Identity Provider (IdP) and authenticate users in your application through Keycloak.

Using Identity Brokering allows you to delegate authentication to external providers such as FusionAuth, Auth0, Okta, etc. Keycloak acts as the broker, your application remains the relying party, and FusionAuth becomes the authentication source.

This article focuses on using FusionAuth as an Identity Provider via the OpenID Connect (OIDC) protocol.

Overview

Below is the high-level sequence when a user logs in through FusionAuth via Keycloak:

The user accesses your application.
Your application redirects the user to Keycloak for authentication.
On the Keycloak login screen, the user selects “FusionAuth”.
Keycloak redirects the user to FusionAuth for login.
The user authenticates at FusionAuth.
FusionAuth redirects back to Keycloak with an authorization code.
Keycloak exchanges the code for an access token from FusionAuth
Keycloak fetches the user’s FusionAuth profile.
Keycloak creates (or updates) a local user identity.
Keycloak completes login and redirects the user back to your application with an ID token and/or access token for OIDC client.

This process allows your application to integrate only with Keycloak, while FusionAuth handles user authentication.

For more details on Identity Provider, please refer the Keycloak server admin guide.

For this article, we do not use a separate client application. Instead, we demonstrate the flow using Keycloak’s built-in Account Console.

Configuration Steps

Summary of steps

Client application registration at Keycloak (we use the built-in account console rather than simulating through an external client application)
Configure FusionAuth as OIDC Provider
Configure Keycloak Identity Provider (Broker)
Map user attributes
Test the integration

Configure FusionAuth as OIDC provider

logout - Skycloak — FusionAuth OIDC application snippet

In this article, we use a self-hosted FusionAuth instance running on:

http://localhost:9011

FusionAuth is running via Docker.

Since this is a local setup, both FusionAuth and Keycloak must run locally.

Step 1: Create an Application in FusionAuth

Navigate to:

Applications → Add Application

Fill the essential fields:

Name: keycloak-broker-app (arbitrary name)
Tenant: default

Click Save.

From the Applications list:

Click the dropdown next to keycloak-broker-app → Select Edit → Go to OAuth tab

Step 2: Enable Grants & specify URLs

✔ Authorization Code
✔ Refresh Token

Authorized Redirect URL

http://localhost:8080/realms/acme/broker/fusionauth/endpoint

This must match the Redirect URL shown in Keycloak when configuring the Identity Provider.

Logout URL

http://localhost:8080/realms/acme/broker/fusionauth/endpoint/logout_response

Save the changes.

Step 3: Obtain client credentials

Inside the same application:

Copy:

Client ID
Client Secret

You will need these in Keycloak.

Step 4: OIDC discovery URL

FusionAuth provides an OpenID Connect discovery endpoint:

http://localhost:9011/.well-known/openid-configuration

You can verify this URL in a browser.

Configuring Keycloak Identity Broker

Log in to the Keycloak Admin Console.
Select your realm (e.g., acme).
Navigate to:

Identity Providers → Add Provider → OpenID Connect v1.0

Configure Provider

Alias: fusionauth
Client ID: (from FusionAuth)
Client Secret: (from FusionAuth)
Discovery Endpoint: http://localhost:9011/.well-known/openid-configuration

Click Show Metadata to auto-populate endpoints.

Click Save.

Make note of the Redirect URL shown in Keycloak — it must match the Authorized Redirect URL configured in FusionAuth.

Mapping Attributes During First Login

To map attributes from FusionAuth to Keycloak:

Navigate to:

Identity Providers → fusionauth → Mappers → Add Mapper

Username Mapper

Mapper Type: Attribute Importer
Claim: username
User Attribute: username

Email Mapper

Mapper Type: Attribute Importer
Claim: email
User Attribute: email

If your FusionAuth token includes given_name and family_name, you may also map:

given_name → firstName
family_name → lastName

These mappers allow Keycloak to store FusionAuth user attributes in the local user profile.

Test the intergration

Use the Keycloak Account Console:

http://localhost:8080/realms/<realm_name>/account

Example:

http://localhost:8080/realms/acme/account

Test Flow

Access the Account Console URL.
You will be redirected to the Keycloak login page.
You should see a “FusionAuth” login option.
Click FusionAuth.
You are redirected to the FusionAuth login page.
Enter FusionAuth credentials.
After successful authentication, FusionAuth redirects back to Keycloak.
Keycloak exchanges the authorization code and creates a local user (on first login).
Authentication completes and you are redirected to the Account Console

Summary

In this article, we implemented Identity Brokering using a local instance of Keycloak and FusionAuth.

When FusionAuth is publicly accessible, you can use a managed Keycloak platform such as Skycloak instead of a local Keycloak installation.

This setup enables:

Centralized authentication management in FusionAuth
Applications integrating only with Keycloak
Clean separation of authentication and application logic
Standards-based OpenID Connect federation

About Skycloak

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 power of open-source Keycloak IAM without the operational overhead of installing, maintaining, and scaling production-grade Keycloak environments—delivered securely and cost-effectively.