> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.id.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server.

# Keycloak OIDC integration guide

> Configure Keycloak to use IDMe as an OpenID Connect identity provider for federated authentication.

## Overview

This guide provides steps to integrate Keycloak with IDMe using the OpenID Connect (OIDC) protocol.

**Intended audience** \
Developers and IAM administrators responsible for configuring federation between Keycloak and IDMe.

**What you will build** \
A federated authentication flow where Keycloak delegates user authentication to IDMe.

**Result** \
A federated OIDC authentication flow where Keycloak delegates authentication to IDMe, allowing users to sign in to a target application.

**Identity proofing behavior** \
Authentication behavior, identity verification settings, and returned attributes are driven by IDMe policy configurations.

## Authentication flow

The following steps outline the OIDC authentication flow between the user, Keycloak, and IDMe:

The user navigates to the Keycloak-hosted landing page

The user selects the **IDMe-Sandbox** option

Keycloak redirects the user to IDMe

The user completes authentication and identity verification at IDMe

IDMe redirects the user back to Keycloak with an authorization code

Keycloak exchanges the code for tokens

Keycloak redirects the user to the target application (for example, `jwt.ms`) with the final ID token

## Prerequisites

* A running instance of Keycloak (Docker is recommended for easy installation)
* Administrator access to the Keycloak admin console
* An IDMe sandbox account for testing your integration
* Understanding of [OIDC flows](/guides/oidc/overview) and terminology

## Environments

IDMe provides two environments:

#### Sandbox

`https://api.idmelabs.com/`

#### Production

`https://api.id.me/`

> **Note**
>
> All IDMe OIDC and SAML endpoints are derived from the base URL above. For production, replace the sandbox base URL in every IDMe endpoint you configure.

### Examples

* OIDC issuer (Sandbox): `https://api.idmelabs.com/oidc`
* OIDC issuer (Production): `https://api.id.me/oidc`
* SAML metadata URL (Sandbox): `https://api.idmelabs.com/saml/metadata`
* SAML metadata URL (Production): `https://api.id.me/saml/metadata`

## Configure Keycloak

### Create a realm

Log in to the Keycloak admin console (default `http://localhost:8080`)

Click the realm dropdown in the top left corner (the default is "Master")

Select **Create Realm**

Enter a **Realm name** (for example, `myrealm`)

Select **Create**

### Configure IDMe as an OpenID Connect identity provider

Navigate to **Identity Providers** in the left menu

Select **Add provider** > **OpenID Connect v1.0**

Configure the identity provider settings:

| Field                  | Value                                                                                                              |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------- |
| Alias                  | `idme-sandbox`                                                                                                     |
| Display Name           | `IDMe-Sandbox`                                                                                                     |
| Use Discovery Endpoint | `On`                                                                                                               |
| Discovery Endpoint     | `https://api.idmelabs.com/.well-known/openid-configuration`                                                        |
| Client ID              | The Client ID provided by your IDMe Solution Consultant.                                                           |
| Client Secret          | The Client Secret provided by your IDMe Solution Consultant.                                                       |
| Client Authentication  | `Client secret sent as post`                                                                                       |
| Validate Signatures    | `On`                                                                                                               |
| Scopes                 | `openid <policy_handle>` (Replace `<policy_handle>` with your specific IDMe policy handle, e.g., `nist_aal2_ial2`) |

> **Note**
>
> After entering the Discovery Endpoint, Keycloak may automatically populate metadata fields. Verify them against the values above.

Select **Add** or **Save**

### Map user claims

Navigate to **Identity Providers** > **idme-sandbox** > **Mappers**

Select **Create**

Configure the mapper:

* **Name**: Enter a name for the mapper (e.g., `firstName`)
* **Sync mode override**: Select `Force`
* **Mapper type**: Select `Attribute Importer`
* **Claim**: Enter the name of the IDMe claim (e.g., `fname`)
* **User Attribute name**: Select `firstName` (or type a custom attribute name)

Select **Save**

Repeat these steps for other claims as necessary (e.g., `lname` to `lastName`, `email` to `email`)

### Configure a target app

Navigate to **Clients** > **Create Client**

Set **Client type** to `OpenID Connect`

Enter a **Client ID** (e.g., `TestApp`) and select **Next**

Toggle **Client authentication** to `On` (or `Off` for public clients like `jwt.ms`)

Toggle **Implicit flow** to `On` (recommended for testing with `jwt.ms`)

Select **Next**

In **Valid redirect URIs**, enter your application's redirect URI (e.g., `https://jwt.ms`)

Select **Save**

## Configure IDMe

This portion of the configuration is completed by an IDMe Solution Consultant. You will need to provide the following information to complete the setup:

**Redirect URIs**

The Keycloak redirect URI typically follows this pattern: \
`http://localhost:8080/realms/<your realm name>/broker/idme-sandbox/endpoint`

> **Note**
>
> Ensure the port (`8080`) and domain match your specific Keycloak deployment. The `idme-sandbox` segment must match the **Alias** you configured in the Identity Provider settings.

**Policy handle name**

The IDMe policy handle (e.g., `nist_aal2_ial2` or `teacher`). This value corresponds to the policy configured in your IDMe Consumer and should be included in the **Scopes** field in Keycloak.

## Test the integration

### Option 1: Log in to the Keycloak account console

Navigate to the Keycloak account console: \
`http://localhost:8080/realms/\<your realm name>\/account`

Select **Sign In**

On the login screen, select **IDMe-Sandbox**

Complete the authentication and verification at IDMe

You should be redirected back to the Keycloak account console as a logged-in user

![Screenshot of the Users list in the Keycloak Administration Console for "myrealm," showing two provisioned users with IDMe email addresses, confirming successful federated user creation after sign-in.](/_fern-files/_img/8f3ca58d7bd3f66efe174771d1beb0f421335bbe5b7581163ea76d97266a795b.webp)

### Option 2: Manually construct URL

Construct an authorization URL to test the flow with a tool like `jwt.ms`.

Copy the following URL pattern and replace the placeholders:

```text
```

Paste the modified URL into your browser

You should see the Keycloak login screen:

![Screenshot of the Keycloak "MYREALM" sign-in page, showing a username/password form with "admin" entered, and an "IDMe Sandbox" federated login option below.](/_fern-files/_img/e17a4f8d4518279915d6cb54e2339e36a600f19026f0bd491f8290002cafb5ff.webp)

Select the **IDMe-Sandbox** button

Complete login and verification at IDMe

If the user exists, you will be logged in. If not, the account will be automatically provisioned in Keycloak.

![Screenshot of the Users list in the Keycloak Administration Console for "myrealm," showing two provisioned users with IDMe email addresses, confirming successful federated user creation after sign-in.](/_fern-files/_img/8f3ca58d7bd3f66efe174771d1beb0f421335bbe5b7581163ea76d97266a795b.webp)