Keycloak als Identity Provider
Voraussetzung
Sie haben Keycloak installiert und besitzen administrativen Zugriff auf Keycloak und BPC.
Sie sollten möglichst immer die neuste Version von Keycloak einsetzen, um Sicherheitsrisiken zu vermeiden. |
Konfiguration Keycloak
Legen Sie bitte ein Realm für das BPC an oder nutzen Sie einen bestehenden Realm, den Sie evtl. bereits für andere Anwendungen nutzen.
Es wird davon abgeraten den Realm |
Ein Skript, das die folgenden Punkte per API konfiguriert, finden Sie im Abschnitt Skript für automatische Einrichtung.
Client anlegen
Damit das BPC mit dem Keycloak kommunizieren kann, muss ein Client angelegt werden.
-
Stellen Sie sicher, dass Sie den richtigen Realm ausgewählt haben.
-
Wählen Sie "Clients" auf der linken Seite
-
Erzeugen Sie über "Create client" einen neuen Client
-
Wählen Sie "OpenID Connect" als "Client type"
-
Vergeben Sie eine Client-ID, wie z.B.
bpc
.
Diese muss später mit der Konfigurationclient_id
im BPC übereinstimmen. -
Aktivieren Sie "Client authentication". In älteren Keycloak-Versionen entspricht das dem Access-Type "confidential".
-
Tragen Sie unter "Valid redirect URIs" die URL ihres BPCs ein. Z.B. "https://bpc.example.com/"
-
Speichern Sie den Client
-
Im Tab "Passwörter"(oder "Credentials") können Sie das Client secret einsehen (und auch ändern).
Dieses muss später mit der Konfigurationclient_secret
im BPC übereinstimmen.
BPC Rollen anlegen
Um BPC Administratoren ernennen zu können, benötigen Sie die Rolle bpcadmin
.
-
Wählen Sie "Realm-Rollen" auf der linken Seite
-
Legen Sie über "Create role" die Rolle
bpcadmin
an.
BPC Administrator anlegen oder zuweisen
Damit ein Benutzer im BPC Administrator ist, benötigt er die Rolle bpcadmin
.
-
Wählen Sie "Benutzer" auf der linken Seite
-
Legen Sie über "Benutzer hinzufügen" einen neuen Benutzer an oder wählen Sie einen bestehenden Benutzer aus
-
Weisen Sie dem Benutzer die Rolle
bpcadmin
zu
Konfiguration BPC
Im BPC muss Keycloak unter den Backend Connections als Identity Provider angelegt und anschließend in den Core Services Einstellungen als zu verwendender Identity Provider festgelegt werden.
Beim Start des BPC werden automatisch Backend Connections angelegt, die für den Keycloak genutzt werden können.
Diese enthalten eine passende Platzhalter-Konfiguration und haben die Namen |
Identity Provider Keycloak vs. OIDC
Sie haben die Möglichkeit Keycloak in zwei verschiedene Varianten (IdentityProvider OpenID Connect (OIDC)
oder Keycloak
) anzubinden.
In beiden Varianten erfolgt die eigentliche Authentifizierung über das OpenID Connect Protokoll.
In der reinen OpenID Connect (OIDC)
Variante erfolgt die Benutzer Administration ausschließlich im Keycloak.
Wählen Sie "Keycloak" kann die im BPC integrierte Benutzerverwaltung / Identity Manager verwendet werden.
Bis einschließlich BPC 4.2.4 muss bei der Verwendung des Typs |
Spezifische Konfiguration der Backend Connection
Folgende für diesen Identity Provider spezifischen Einstellungen finden sich an der Backend Connections vom Typ identity_provider
.
Für die allgemeine Konfiguration der Backend Connections vom Typ identity_provider
siehe Allgemeine Identity Provider Konfiguration.
Setting (Key) | Gruppe | Wert | Beschreibung |
---|---|---|---|
config |
|
Keycloak bzw. OIDC für die Backend Connection als IdP festlegen. |
|
IdentityProvider_URL |
config |
`https://localhost:8080/auth/realms/bpc/.well-known/openid-configuration` |
OIDC Discovery Endpoint |
IdentityProvider_Configuration |
config |
|
Die Konfiguration für den Keycloak Zugriff.
Die URLs müssen hier entsprechend dem BPC und dem Keycloak angepasst werden. |
OIDC / Keycloak Verbindungsparameter
In dem JSON Setting identityProvider_configuration
können folgende Parameter konfiguriert werden:
Für BPC Installationen bis einschließlich Version 4.2.4 sind weitere Konfigurationen nötig. Siehe dafür die Dokumentation BPC 4.1. Diese gilt an dieser Stelle auch bis Version 4.2.4. |
Attribut | Beispielwert | Beschreibung |
---|---|---|
An diese Adresse wird der Benutzer weitergeleitet, nachdem ein Login ausgeführt wurde. |
||
|
Komma separierte Liste aller Claim Namen aus denen die Rollen des Benutzers extrahiert werden. |
|
|
Komma separierte Liste aller Claim Namen aus denen die Organisationen des Benutzers extrahiert werden. |
|
|
Komma separierte Liste aller Claim Namen aus denen die Rechte des Benutzers extrahiert werden. |
|
|
OIDC Scopes die bei der Authentisierung beim OIDC Provider angefragt werden. Werden Scopes angefragt, die es nicht gibt oder für die der Client nicht berechtigt ist, kann es zu Fehlern bei der Authentifizierung kommen. |
|
|
ID des im OIDC Provider konfigurierten Clients über den der Zugriff erfolgen soll. |
|
|
Secret für die Authentifizierung des Clientzugriffs. |
|
An diese Adresse wird der Benutzer weitergeleitet, nachdem ein Logout ausgeführt wurde. |
||
|
Optional. Siehe Keycloak und dynamische Redirect URIs. |
BPC Integration
Sollten Sie an der Einstellung identityProvider
den Typ Keycloak
gewählt haben, stehen Ihnen verschiedene Integrationen bereit.
Das BPC bietet Zugriff auf verschiedene Funktionen der Benutzerverwaltung durch die integrierte Benutzerverwaltung.
Über das User Account Menu Plugin können auch diverse Aktionen gegenüber dem Keycloak vom Benutzer ausgeführt werden.
Skript für automatische Einrichtung
Für Entwicklungs- und Testumgebungen kann das folgende Skript genutzt werden.
Dieses Skript geht gegen die Admin REST API von Keycloak und richtet einen neuen Realm bpc
ein.
Dieser ist anschließend so konfiguriert, dass er mit dem vorkonfiguriertem Identity Provider Keycloak
(ID: idp_keycloak
) funktioniert.
Die Konfiguration der vom BPC initial bereitgestellten Backend Connection Keycloak
(ID: idp_keycloak
) wurde im BPC 4.2.5 angepasst, so das diese zu diesem Beispiel passt.
Sollten Ihr BPC initial mit einer Version < 4.2.5 installiert worden sein, dann können Sie diesen Identity Provider aus den Backend Connections löschen.
Nach einem Neustart wird dieser erneut mit den neuen Standardeinstellungen wiederhergestellt.
Alternativ können Sie das Skript anpassen (z.B: die ID den Clients).
Das Skript kann z.B. genutzt werden, wenn man temporär zum Testen ein Keycloak via Docker startet.
|
Die Variablen des Skriptes sollten nach Bedarf angepasst werden.
Es ist jedoch nicht nötig ADMIN_USER
und ADMIN_PASSWORD
zu setzen.
Diese beiden Variablen werden beim Start über das Terminal abgefragt.
createBpcRealm.sh
#!/bin/bash
# Keycloak Server URL und Admin Credentials
KEYCLOAK_URL="http://localhost:8080"
KEYCLOAK_REALM="master"
ADMIN_USER=""
ADMIN_PASSWORD=""
# Neue Realm-, Client- und Benutzer-Konfiguration
NEW_REALM="bpc"
NEW_CLIENT="bpc"
CLIENT_SECRET="bpc-test-only"
NEW_ROLE="bpcadmin"
BPC_USER="bpcuser"
BPC_ADMIN="bpcadmin"
# Benutzer-Daten
BPC_USER_FIRSTNAME="BPC"
BPC_USER_LASTNAME="User"
BPC_USER_EMAIL="bpcuser@example.com"
BPC_ADMIN_FIRSTNAME="BPC"
BPC_ADMIN_LASTNAME="Admin"
BPC_ADMIN_EMAIL="bpcadmin@example.com"
# Redirect-URL für den Client
REDIRECT_URL="http://localhost*"
# Funktion zur Eingabe von Benutzername und Passwort
read -p "Gib den Keycloak Admin Benutzernamen ein: " ADMIN_USER
read -s -p "Gib das Keycloak Admin Passwort ein: " ADMIN_PASSWORD
echo ""
# Abrufen eines Tokens vom Keycloak-Server
TOKEN=$(curl -s \
-d "client_id=admin-cli" \
-d "username=$ADMIN_USER" \
-d "password=$ADMIN_PASSWORD" \
-d "grant_type=password" \
"${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token" | jq -r .access_token)
# Prüfen, ob das Token erfolgreich abgerufen wurde
if [ -z "$TOKEN" ]; then
echo "Fehler beim Abrufen des Tokens. Überprüfe Benutzername/Passwort und Keycloak-URL."
exit 1
fi
# Realm "bpc" erstellen mit Internationalisierung
# Für Login Theme die folgende Zeile mit aufnehmen
# "loginTheme": "theme-id",
echo "Erstelle den Realm '${NEW_REALM}' mit Login-Theme 'foo-theme' und Internationalisierung..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"realm": "'"${NEW_REALM}"'",
"enabled": true,
"internationalizationEnabled": true,
"supportedLocales": ["en", "de"],
"defaultLocale": "en"
}'
# Client "bpc" erstellen
echo "Erstelle den Client '${NEW_CLIENT}' im Realm '${NEW_REALM}' mit Redirect-URL '${REDIRECT_URL}'..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/clients" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"clientId": "'"${NEW_CLIENT}"'",
"secret": "'"${CLIENT_SECRET}"'",
"enabled": true,
"redirectUris": ["'"${REDIRECT_URL}"'"],
"directAccessGrantsEnabled": true
}'
# Realm-Rolle "bpcadmin" erstellen
echo "Erstelle die Realm-Rolle '${NEW_ROLE}'..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/roles" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "'"${NEW_ROLE}"'"
}'
# Benutzer "bpcuser" erstellen
echo "Erstelle den Benutzer '${BPC_USER}'..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/users" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "'"${BPC_USER}"'",
"firstName": "'"${BPC_USER_FIRSTNAME}"'",
"lastName": "'"${BPC_USER_LASTNAME}"'",
"email": "'"${BPC_USER_EMAIL}"'",
"enabled": true,
"credentials": [{
"type": "password",
"value": "'"${BPC_USER}"'",
"temporary": false
}]
}'
# Benutzer "bpcadmin" erstellen
echo "Erstelle den Benutzer '${BPC_ADMIN}'..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/users" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "'"${BPC_ADMIN}"'",
"firstName": "'"${BPC_ADMIN_FIRSTNAME}"'",
"lastName": "'"${BPC_ADMIN_LASTNAME}"'",
"email": "'"${BPC_ADMIN_EMAIL}"'",
"enabled": true,
"credentials": [{
"type": "password",
"value": "'"${BPC_ADMIN}"'",
"temporary": false
}]
}'
# Benutzer-ID des Benutzers "bpcadmin" abrufen
BPC_ADMIN_ID=$(curl -s -X GET "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/users?username=${BPC_ADMIN}" \
-H "Authorization: Bearer $TOKEN" | jq -r '.[0].id')
# Rollen-ID der Rolle "bpcadmin" abrufen
ROLE_ID=$(curl -s -X GET "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/roles/${NEW_ROLE}" \
-H "Authorization: Bearer $TOKEN" | jq -r '.id')
# Rolle "bpcadmin" dem Benutzer "bpcadmin" zuweisen
echo "Weise die Rolle '${NEW_ROLE}' dem Benutzer '${BPC_ADMIN}' zu..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/users/${BPC_ADMIN_ID}/role-mappings/realm" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '[
{
"id": "'"${ROLE_ID}"'",
"name": "'"${NEW_ROLE}"'"
}
]'
# Abrufen der Scope-ID für "profile" im Realm "bpc"
echo "Rufe die Scope-ID für 'profile' im Realm '${NEW_REALM}' ab..."
PROFILE_SCOPE_ID=$(curl -s -X GET "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/client-scopes" \
-H "Authorization: Bearer $TOKEN" | jq -r '.[] | select(.name == "profile") | .id')
# Prüfen, ob die Scope-ID für "profile" gefunden wurde
if [ -z "$PROFILE_SCOPE_ID" ]; then
echo "Fehler: Der Scope 'profile' wurde im Realm '${NEW_REALM}' nicht gefunden."
exit 1
fi
# Mapper "Impersonator User ID" zum "profile" Scope hinzufügen
echo "Füge dem Scope 'profile' den Mapper 'Impersonator User ID' hinzu..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/client-scopes/${PROFILE_SCOPE_ID}/protocol-mappers/models" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Impersonator User ID",
"protocol": "openid-connect",
"protocolMapper": "oidc-usersessionmodel-note-mapper",
"config": {
"user.session.note": "IMPERSONATOR_ID",
"id.token.claim": "true",
"introspection.token.claim": "true",
"access.token.claim": "true",
"claim.name": "impersonator.id",
"jsonType.label": "String"
}
}'
# Mapper "Impersonator Username" zum "profile" Scope hinzufügen
echo "Füge dem Scope 'profile' den Mapper 'Impersonator Username' hinzu..."
curl -s -X POST "${KEYCLOAK_URL}/admin/realms/${NEW_REALM}/client-scopes/${PROFILE_SCOPE_ID}/protocol-mappers/models" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Impersonator Username",
"protocol": "openid-connect",
"protocolMapper": "oidc-usersessionmodel-note-mapper",
"config": {
"user.session.note": "IMPERSONATOR_USERNAME",
"id.token.claim": "true",
"introspection.token.claim": "true",
"access.token.claim": "true",
"claim.name": "impersonator.username",
"jsonType.label": "String"
}
}'
echo "Fertig!"
Die Ausführung des Skriptes erfolgt auf eigene Gefahr. Für die Funktion wird keine Gewährleistung übernommen. In dem Skript wird für den Client ein unsicheres Secret gesetzt. Dieses sollte so nie in produktiven Umgebungen genutzt werden. |