Keycloak SSO Configuration — OIDC, SAML & User Federation

Navigate to Client Registration

1. Open the Keycloak Admin Console: http://localhost:8080/admin
2. Ensure you are in the sandbox realm (check the top-left dropdown)
3. Click Clients in the sidebar
4. Click Create client

Configure Client — General Settings

Click Next.

Configure Client — Capability Config

Click Next.

Configure Client — Login Settings

Click Save.

Retrieve Client Secret

After saving, the client configuration page opens:

1. Go to the Credentials tab
2. You will see the Client secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
3. Copy this secret — you need it when configuring your application

Configure Client Roles

1. Go to the Roles tab within the client configuration
2. Click Create role
3. Role name: admin
4. Description: Web app administrator
5. Click Save
6. Repeat: Create role editor with description Content editor

Test the OIDC Flow

Keycloak provides a built-in test endpoint to verify the client configuration:

# Step 1: Get the authorization URL (open in browser)
echo "http://localhost:8080/realms/sandbox/protocol/openid-connect/auth?
  client_id=web-app&
  redirect_uri=http://localhost:3000/callback&
  response_type=code&
  scope=openid&
  state=test123"

# Open this URL in a browser — it will redirect to Keycloak's login page

1. Open the URL constructed above in a browser
2. Log in as alice / Alice@Lab2026
3. Keycloak will redirect to http://localhost:3000/callback?code=... (the redirect will fail since there is no app on port 3000, but you can see the auth code in the URL)

# Step 2: Exchange the auth code for tokens (using curl)
# Replace {AUTH_CODE} with the code from the redirect URL
AUTH_CODE="<paste-code-here>"
CLIENT_SECRET="<paste-client-secret-here>"

curl -s -X POST http://localhost:8080/realms/sandbox/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=web-app" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "code=$AUTH_CODE" \
  -d "redirect_uri=http://localhost:3000/callback" | jq

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "token_type": "Bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "not-before-policy": 0,
  "session_state": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "openid email profile"
}

Decode the Access Token

# Decode the JWT (copy-paste your access_token)
# A JWT has three base64-encoded parts separated by dots
# Part 1: Header, Part 2: Payload, Part 3: Signature

echo "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ..." | \
  cut -d. -f2 | \
  base64 -d 2>/dev/null || true | \
  jq

The decoded payload shows:

{
  "exp": 1718541234,
  "iat": 1718540934,
  "auth_time": 1718540934,
  "jti": "abcdef01-2345-6789-abcd-ef0123456789",
  "iss": "http://localhost:8080/realms/sandbox",
  "aud": ["web-app", "account"],
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "typ": "Bearer",
  "azp": "web-app",
  "session_state": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "acr": "1",
  "allowed-origins": ["http://localhost:3000"],
  "realm_access": {
    "roles": ["app-admin", "offline_access", "uma_authorization"]
  },
  "resource_access": {
    "account": {
      "roles": ["manage-account", "manage-account-links", "view-profile"]
    }
  },
  "scope": "openid email profile",
  "sid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email_verified": true,
  "name": "Alice Johnson",
  "preferred_username": "alice",
  "given_name": "Alice",
  "family_name": "Johnson",
  "email": "alice@example.com"
}

This confirms the OIDC flow is working correctly — Keycloak authenticated Alice, included her profile information in the ID token, and issued an access token with role information.

Create the Client

1. Go to Clients → Create client
2. Client ID: spa-app
3. Name: Single Page App (Lab)
4. Click Next
5. Client authentication: OFF (public client)
6. Standard flow: ON
7. Direct access grants: OFF
8. Click Next
9. Valid redirect URIs: http://localhost:5173/*
10. Web origins: http://localhost:5173
11. Click Save

Public Client vs Confidential Client

Create the Client

1. Go to Clients → Create client
2. Client ID: saml-app
3. Name: SAML Application (Lab)
4. Click Next
5. Client authentication: ON (SAML entities are always confidential)
6. Toggle to SAML protocol (click the protocol dropdown and select SAML)
7. Capability config appears — configure:

8. Click Next

Configure SAML Settings

Click Save.

Configure SAML-Specific Settings

After saving, go to the Settings tab and configure:

Export SAML Metadata

SAML service providers need IdP metadata to establish trust:

1. In the client page, go to the Action menu (top-right)
2. Click Download adapter config
3. Select SAML Metadata format
4. The metadata XML contains:
   • IdP entity ID
   • SSO endpoint URL
   • Logout endpoint URL
   • Signing certificate (public key)
5. This XML is uploaded to the SAML SP (e.g., Salesforce) to establish the trust relationship

The metadata looks like:

<EntityDescriptor entityID="http://localhost:8080/realms/sandbox"
  xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <KeyInfo>
        <X509Data>
          <X509Certificate>MIIC... (base64 cert)</X509Certificate>
        </X509Data>
      </KeyInfo>
    </KeyDescriptor>
    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="http://localhost:8080/realms/sandbox/protocol/saml"/>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="http://localhost:8080/realms/sandbox/protocol/saml"/>
  </IDPSSODescriptor>
</EntityDescriptor>

Add OpenLDAP to Docker Compose

Edit ~/keycloak-lab/docker-compose.yml and add:

  openldap:
    image: osixia/openldap:1.5.0
    container_name: keycloak-ldap
    environment:
      LDAP_ORGANISATION: "Lab Corp"
      LDAP_DOMAIN: "lab.corp"
      LDAP_ADMIN_PASSWORD: "Ldap@dmin2026"
      LDAP_BASE_DN: "dc=lab,dc=corp"
    ports:
      - "389:389"
      - "636:636"
    volumes:
      - ldap_data:/var/lib/ldap
      - ldap_config:/etc/ldap/slapd.d
    networks:
      - keycloak-network
    restart: unless-stopped

  phpldapadmin:
    image: osixia/phpldapadmin:0.9.0
    container_name: keycloak-ldap-admin
    environment:
      PHPLDAPADMIN_LDAP_HOSTS: openldap
      PHPLDAPADMIN_HTTPS: "false"
    ports:
      - "8090:80"
    networks:
      - keycloak-network
    depends_on:
      - openldap
    restart: unless-stopped

volumes:
  ldap_data:
  ldap_config:

Then restart:

cd ~/keycloak-lab
docker compose up -d

Add Test Users to LDAP

Access the LDAP admin interface at http://localhost:8090

• Login DN: cn=admin,dc=lab,dc=corp
• Password: Ldap@dmin2026

Or use LDIF files via the command line:

# Create an LDIF file with test users
cat > test-users.ldif << 'EOF'
dn: ou=people,dc=lab,dc=corp
objectClass: organizationalUnit
ou: people

dn: cn=John Doe,ou=people,dc=lab,dc=corp
objectClass: inetOrgPerson
cn: John Doe
sn: Doe
uid: jdoe
mail: jdoe@lab.corp
userPassword: John@Ldap2026

dn: cn=Jane Smith,ou=people,dc=lab,dc=corp
objectClass: inetOrgPerson
cn: Jane Smith
sn: Smith
uid: jsmith
mail: jsmith@lab.corp
userPassword: Jane@Ldap2026

dn: ou=groups,dc=lab,dc=corp
objectClass: organizationalUnit
ou: groups

dn: cn=engineering,ou=groups,dc=lab,dc=corp
objectClass: groupOfNames
cn: engineering
member: cn=John Doe,ou=people,dc=lab,dc=corp
member: cn=Jane Smith,ou=people,dc=lab,dc=corp
EOF

# Import into OpenLDAP
docker compose exec openldap ldapadd -x -D "cn=admin,dc=lab,dc=corp" \
  -w "Ldap@dmin2026" -f test-users.ldif -H ldap://localhost

Configure User Federation in Keycloak

1. In Keycloak Admin Console → sandbox realm
2. Go to User Federation in the sidebar
3. Click Add provider → ldap
4. Configure:

5. Click Test connection — you should see a success message

6. Configure LDAP Searching and Updating:

7. Click Save

8. Go to the Mappers tab of the LDAP provider

9. Click Add mapper → select user-attribute-ldap-mapper

10. Add a mapper for givenName → first name (since our LDIF has cn but not givenName explicitly):

Click Save.

Sync Users from LDAP

1. Go to the LDAP provider settings
2. Click Synchronize all users
3. The sync will import jdoe and jsmith as Keycloak users
4. Go to Users — you should see them listed
5. Unlike Keycloak-native users, LDAP users show:
   • Federation Link: lab-openldap (indicating they came from LDAP)
   • No password can be set in Keycloak (passwords are verified against LDAP)

Test LDAP Authentication

1. Open a private/incognito browser window
2. Go to: http://localhost:8080/realms/sandbox/account/
3. Log in as jdoe with password John@Ldap2026
4. Authentication succeeds against OpenLDAP

Navigate to Authentication

1. In the sandbox realm, go to Authentication in the sidebar
2. Click the Policies tab

Configure MFA Policy

Configure Required MFA for All Users

1. Go to the Flows tab
2. Click Duplicate on the browser flow (never modify built-in flows)
3. Name the copy: browser-with-mfa
4. Edit the new flow:

5. Click Bind flow → select Browser Flow → choose browser-with-mfa

Make MFA Required via Authentication Policy

1. Go to Authentication → Policies tab
2. Click Require OTP under “Required actions for all users”
3. Click Register

Test MFA

1. Log out of the admin console
2. Log back in as alice
3. You will be prompted to set up MFA:

┌─────────────────────────────────────────────────────────┐
│  Setup Two-Factor Authentication                         │
│                                                           │
│  1. Install an authenticator app:                        │
│     Google Authenticator, Authy, 1Password, etc.         │
│                                                           │
│  2. Scan this QR code with your app:                     │
│     ┌─────────────────────────────────────────────┐     │
│     │             [QR CODE IMAGE]                  │     │
│     └─────────────────────────────────────────────┘     │
│                                                           │
│     Or manually enter:                                    │
│     Issuer: Keycloak (sandbox)                            │
│     Account: alice                                        │
│     Secret: JBSWY3DPEHPK3PXP                             │
│                                                           │
│  3. Enter the 6-digit code from your app:                 │
│     [______]                                              │
│                                                           │
│     [Submit]                                              │
└─────────────────────────────────────────────────────────┘

4. Set up your authenticator app and submit the code
5. On subsequent logins, you will enter your password then a TOTP code