Zu Content springen
Supportanfrage Anmelden
  • Es gibt keine Vorschläge, da das Suchfeld leer ist.

SSO-Konfigurationsbeispiel des Identitäsanbieters Keycloak

Dieser Artikel beschreibt die notwendige Konfiguration innerhalb des Identitätsanbieters Keycloak, um eine SSO Anmeldung bereitzustellen.

Schritt 1: Keycloak lokal starten

 In unserem Beispiel nutzen wir Keycloak in Verbindung mit Docker und starten Keycloak lokal gemäß der Anleitung Erste Schritte mit Keycloak auf Docker.

docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.6.4 start-dev

Über ein Terminal wird Keycloak lokal über den Port 8080 gestartet und ein Admin-Benutzer admin mit dem Passwort admin angelegt. Keycloak sollte nun über http://localhost:8080 im Webbrowser erreichbar sein. 

keycloak-startbildschrim

Schritt 2: Realm anlegen

Ein Realm ist bei Keycloak grob vergleichbar mit einem Tenant/Mandanten. Keycloak beschreibt Realms als isolierte Bereiche für Anwendungen und Benutzer.

In der Admin Console:

  1. In der Navigation auf Manage realms klicken.

  2. Create realm klicken.

  3. Realm Name: customx

    keycloak-create-realm

  4. Create-Schaltfläche klicken.

    keycloak-created-customx-realm

Ab jetzt lautet der lokale Issuer:

http://localhost:8080/realms/customx

Zum Prüfen kann diese URL geöffnet werden:

http://localhost:8080/realms/customx/.well-known/openid-configuration

 Der .well-known/openid-configuration-Endpunkt ist der zentrale OIDC-Metadaten-Endpunkt von Keycloak (Keycloak-Guides).

Schritt 3: Testbenutzer für den Login anlegen

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Users klicken.
  3. Create new user klicken.
  4. Beispiel:
    Email verified: On
    Username: r_zufall
    Email: rainer.zufall@muster.com
    First name: Rainer
    Last name: Zufall


    keycloak-create-user-testuser 

  5. Create klicken.
  6. Den Tab Credentials wechseln.
  7. Set password klicken.
  8. Passwort festlegen. Zum Beispiel
    Password: test1234
    Temporary: Off


    keycloak-testuser-set-credantials

  9. Save klicken.
  10. Save password klicken.


Schritt 4: Web-Client anlegen

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Clients klicken.
  3. Create client klicken.

  4. Beispiel:

    Client type: OpenID Connect
    Client ID: customx-web
    Name: customX Web

     

    keycloak-creat-web-client-1

  5. Next klicken.

  6. Capability config:

    Client authentication: Off
    Authorization: Off
    Standard flow: On
    Direct access grants: optional Off
    Require PKCE: On
    PKCE Method: S256


    keycloak-creat-web-client-2

  7. Next klicken.

  8. Login settings:
    Valid redirect URIs:
    http://localhost/CustomXApp/Start.html

    Valid post logout redirect URIs:
    http://localhost/CustomXApp/Start.html

    Web origins:
    http://localhost

     

    keycloak-creat-web-client-3

  9. Save klicken.

    keycloak-creat-web-client-4


Schritt 5: API-Client anlegen


In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Clients klicken.
  3. Create client klicken.
  4. Beispiel:
    Client type: OpenID Connect
    Client ID: customx-api
    Name: customX API

     

    keycloak-creat-api-client-1
  5. Next klicken.
  6. Capability config:
    Client authentication: Off
    Authorization: Off
    Standard flow: Off
    Direct access grants: Off
    Require PKCE: Off

    keycloak-creat-api-client-2

  7. Next klicken.
  8. Login settings:

    keycloak-creat-api-client-3
  9. Save klicken.

    keycloak-creat-api-client-4

Schritt 6: Client Scope anlegen

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Client scopes klicken.
  3. Create client scope klicken.

  4. Beispiel:

    Name: customx-user-access
    Type: Default
    Protocol: OpenID Connect
    Display on consent screen: On
    Consent screen text: Zugriff auf customX
    Include in token scope: On

    keycloak-create-client-scope-1

  5. Save klicken.


Schritt 7: Client Scope dem Web-Client zuordnen

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Clients klicken.
  3. customx-web klicken.
  4. Den Tab Client scopes wechseln.

  5. Add client scope klicken.

    keycloak-link-client-scope-to-web-client

  6. Add klicken.

  7. Optional klicken.

    keycloak-link-client-scope-to-web-client-2

 Die customX Anwendung nutzt nun die Scopes openid profile email customx-user-access. 


Schritt 8: Audience Mapper anlegen

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Client scopes klicken.
  3. customx-user-access klicken.
  4. Den Tab Mappers wechseln.
  5. Configure a new mapper klicken.

  6. Mapper type Audience klicken.

    Name: customx-api-audience
    Included Client Audience: customx-api
    Add to access token: On

    keycloak-create-audience-mapper-1

  7. Save klicken.

    keycloak-create-audience-mapper-2

Schritt 9: customX konfigurieren

  1. "C:\customX\Config\customX.ini" öffnen.

  2. Einstellungen eintragen.

    [SSO]
    Authentication=3

    [OpenIdConnectAuthentication]
    issuer=http://localhost:8080/realms/customx
    redirect-uri=http://localhost/CustomXApp/Start.html
    web-client-id=customx-web
    api-client-id=customx-api
    scopes=customx-user-access

    [SSOParameterMapping]
    cxEmail=email

Schritt 10: (Optional) Benutzerdefinierte Anwendungsansprüche (Claims) übergeben

Benutzerattribute anlegen

Es können beliebig viele Benutzerattribute angelegt werden. Hier zwei Beispiele:

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Realm settings klicken.
  3. Den Tab User profile wechseln.

  4. Create attribute klicken.

    General settings
    Attribute [Name]: customerId
    Display name: Kunden-ID

    Permissions
    Who can edit? Admin
    Who can view? User, Admin

    keycloak-create-user-attribute-1

  5. Create klicken.

    keycloak-create-user-attribute-2

  6. Create attribute klicken.

    General settings
    Attribute [Name]: configuratorUserRole
    Display name: Konfigurator Benutzerrolle
    Default value: standard

    Permissions
    Who can edit? Admin
    Who can view? User, Admin

    keycloak-create-user-attribute-3

  7. Create klicken.

Benutzerattribute Werte setzen

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Users klicken.
  3. Testbenutzer r_zufall klicken.
  4. Wert Kunden-ID setzen.

  5. Wert Konfigurator Benutzerrolle überprüfen.

    keycloak-testuser-set-custom-attributes

  6. Save klicken.

Anwendungsanspruch dem Token hinzufügen

In der Admin Console:

  1. Prüfen, ob customx der aktuelle Realm ist.
  2. In der Navigation auf Client scopes klicken.
  3. customx-user-access klicken.
  4. Den Tab Mappers wechseln.
  5. Add mapper klicken.

  6. By configuration klicken.

    keycloak-create-new-user-attribute-mapper

  7. User Attribute klicken.

    Name: customer-id-mapper
    User Attribute: customerId
    Token Claim Name: customer-id
    Claim JSON Type: String
    Add to access token: On
    Add to ID token: optional
    Add to userinfo: optional

    keycloak-customer-id-mapper

  8. Save klicken.

  9. Add mapper klicken.

  10. By configuration klicken.

  11. User Attribute klicken.

    Name: configurator-user-role-mapper
    User Attribute: configuratorUserRole
    Token Claim Name: configurator-user-role
    Claim JSON Type: String
    Add to access token: On
    Add to ID token: optional
    Add to userinfo: optional

     

    keycloak-configurator-user-role-mapper

  12. Save klicken.

    keycloak-created-user-attributes-mappers

 Die Mappers sollten in einem Client Scope (hier: customx-user-access) angelegt werden, die dem Web-Client (hier: customx-web) zugeordnet sind. 

Mapping in den customX-Einstellungen hinzufügen

  1. "C:\customX\Config\customX.ini" öffnen.

  2. Einstellungen eintragen.

    [SSOParameterMapping]
    cxEmail=email # Bereits in Schritt 9 gesetzt
    IdentityProviderCustomerID=customer-id
    IdentityProviderConfiguratorUserRole=configurator-user-role

    keycloak-custom-user-attributes-in-debugger

Schritt 11: Access token überprüfen

  1. Webbrowser öffnen.
  2. DevTools öffnen z. B. Taste F12 drücken.
  3. Tab Network/ Netzwerk öffnen.
  4. customX Startseite aufrufen (http://localhost/CustomXApp/Start.html).
  5. SSO-Button klicken.
  6. In Keycloak authentifizieren.
  7. Im Network-Tab im Filter nach token suchen.
  8. Token auswählen.
  9. Tab Preview auswählen

    oidc-token-inspecten
  10. access_token Wert kopieren.
  11. JSON-Web Token encoder öffnen (https://www.jwt.io/).
  12. Access-Token encoden.
  13. Inhalt auf wichtige Claims prüfen.
{
 ...
 "iss": "http://localhost:8080/realms/customx",
 "aud": [
  "customx-api",
  ...
 ],
 ...
 "azp": "customx-web",
 ...
 "scope": "openid email customx-user-access profile",
 ...
 "customer-id": "4711",
 "name": "Rainer Zufall",
 "preferred_username": "r_zufall",
 "given_name": "Rainer",
 "family_name": "Zufall",
 "email": "rainer.zufall@muster.com",
 "configurator-user-role": "standard"
}

Das bedeutet:

Claim Bedeutung Bewertung
iss Aussteller (Issuer) des Tokens Sollte zum Realm passen
aud Zielanwendung (Audience) des Tokens customx-api ist enthalten
azp Autorisierte Anwendung, die das Token angefordert hat customX-web ist korrekt
scope Berechtigungen (Scopes), die dem Benutzer erteilt wurden customx-user-access ist enthalten
customer-id Benutzerdefinierter Claim vorhanden
configurator-user-role Benutzerdefinierter Claim vorhanden