Version: Weekly Build

OIDC-Rollenzuordnung

Die OIDC-Rollenzuordnung vergibt Organization- und Resource-Group-Rollen anhand der Claims, die dein Identitätsanbieter in das ID-Token einfügt. Du legst fest, welche Claim-Werte welche Rollen vergeben. Zum Beispiel kannst du jeden Nutzer in einer IdP-Gruppe namens engineering zu einem Member deiner Organization und einem Admin ausgewählter Resource Groups machen.

Die OIDC-Rollenzuordnung erfordert einen konfigurierten OIDC-Identitätsanbieter. Wende dich an Codesphere, um sie für deine Installation zu aktivieren.

Funktionsweise

Zwei Arten von Zuordnungen arbeiten zusammen.

Zuordnung	Verwaltet von	Ordnet zu	Zweck
Org-Zuordnung	Cluster-Admin	Claim → Organization	Entscheidet, welche Rollenzuordnungen welcher Organization auf ein Token angewendet werden
Rollenzuordnung	Organization Owner	Claim → Rolle auf der Organization oder einer ihrer Resource Groups	Vergibt die tatsächlichen Rollen

Bei jeder OIDC-Anmeldung führt Codesphere folgende Schritte aus:

Liest die Claims des signierten ID-Tokens und wandelt sie in Schlüssel/Wert-Paare um.
Sucht die Org-Zuordnungen, deren Schlüssel und Wert im Token vorkommen. Das ergibt eine Menge von Organizations.
Lädt die Rollenzuordnungen dieser Organizations und behält jene, deren Schlüssel und Wert im Token vorkommen.
Vergibt die passenden Rollen an den Nutzer.

Eine Org-Zuordnung vergibt allein noch keine Rolle. Sie schaltet lediglich die Rollenzuordnungen einer Organization frei. Damit ein Nutzer Mitglied wird, braucht diese Organization zusätzlich eine Rollenzuordnung mit dem Ressourcentyp Organization.

Claims werden zu Schlüssel/Wert-Paaren

Codesphere flacht das ID-Token vor dem Abgleich ab. Betrachte dieses Token:

{
  "email": "[email protected]",
  "groups": ["engineering", "platform"],
  "realm_access": { "roles": ["developer"] },
  "tier": 3
}

Daraus ergeben sich folgende Paare:

Claim-Schlüssel	Claim-Wert
`email`	`[email protected]`
`groups`	`engineering`
`groups`	`platform`
`realm_access.roles`	`developer`
`tier`	`3`

Jedes Element eines Arrays wird zu einem eigenen Paar.
Verschachtelte Objekte werden mit Punkten verbunden, zum Beispiel realm_access.roles.
Zahlen und Booleans werden als Zeichenketten verglichen.
Leere Zeichenketten und null-Werte werden verworfen.

Nur das ID-Token zählt

Codesphere gleicht Claims ausschließlich aus dem signierten ID-Token ab. Ein Claim, den dein IdP vom Userinfo-Endpoint liefert, aber nicht im ID-Token enthält, wird ignoriert. Konfiguriere deinen IdP so, dass der Claim in das ID-Token aufgenommen wird, siehe Identitätsanbieter konfigurieren.

Der Abgleich erfolgt exakt und case-sensitiv sowohl beim Schlüssel als auch beim Wert. Engineering entspricht nicht engineering, und es gibt keinen Wildcard- oder Präfix-Abgleich.

Claims einer Organization zuordnen

Org-Zuordnungen gelten clusterweit und können nur von einem Cluster-Admin über die Public API verwaltet werden. Dafür gibt es keine UI.

Org-Zuordnungen über die Public API verwalten

Alle Anfragen benötigen ein API-Token im Authorization-Header, siehe Public API.

Eine Org-Zuordnung erstellen

curl -X POST "https://<base-domain>/api/clusters/organizations/idp-mappings" \
  -H "Authorization: Bearer $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "claimKey": "groups",
    "claimValue": "engineering",
    "organizationId": "<organization-id>"
  }'

Feld	Beschreibung
`claimKey`	Abgeflachter Claim-Schlüssel, zum Beispiel `groups` oder `realm_access.roles`
`claimValue`	Exakter Wert, den der Claim enthalten muss
`organizationId`	UUID einer bestehenden Organization

Fehler:

NotFound, wenn die Organization nicht existiert.
AlreadyExists, wenn das Claim-Paar bereits einer Organization zugeordnet ist.
InvalidArgument, wenn ein Feld leer ist oder organizationId keine UUID ist.

Ein Claim-Paar kann nur auf eine Organization verweisen. Mehrere Claim-Paare können auf dieselbe Organization verweisen.

Org-Zuordnungen auflisten

curl "https://<base-domain>/api/clusters/organizations/idp-mappings" \
  -H "Authorization: Bearer $CS_TOKEN"

Die Antwort listet alle Zuordnungen auf, neueste zuerst:

[
  {
    "claimKey": "groups",
    "claimValue": "engineering",
    "organizationId": "<organization-id>",
    "createdAt": "2026-10-13T09:00:00.000Z"
  }
]

Eine Org-Zuordnung löschen

curl -X DELETE "https://<base-domain>/api/clusters/organizations/idp-mappings" \
  -H "Authorization: Bearer $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"claimKey": "groups", "claimValue": "engineering"}'

Das Löschen einer nicht vorhandenen Zuordnung ist erfolgreich.

Um ein Claim-Paar auf eine andere Organization umzuleiten, lösche die Zuordnung und erstelle sie neu.

Beim Löschen einer Organization werden auch ihre Org-Zuordnungen und Rollenzuordnungen gelöscht.

Claims Rollen zuordnen

Organization Owners verwalten Rollenzuordnungen für ihre eigene Organization. Eine Rollenzuordnung vergibt eine dieser Rollen:

Ressourcentyp	Rollen
Organization	Owner, Member
Resource Group	Admin, Member

Eine Resource-Group-Rolle gilt nur, wenn der Nutzer bereits Mitglied der Organization ist. Ordne denselben Claim auch einer Organization-Rolle zu, sofern nicht alle Nutzer mit diesem Claim bereits Mitglieder sind.

Öffne deine Organization und gehe zu Access Management → OIDC Role Mapping. Nur Organization Owners sehen diese Seite.
Klicke auf Add New Mapping.
Gib unter Claim Details den Claim-Key (zum Beispiel groups) und den Value (zum Beispiel engineering) ein. Verwende Punkte für verschachtelte Claims, zum Beispiel realm_access.roles.
Wähle unter Mapped Resources den Resource Type, die Resource und die Role aus.
Klicke auf Add resource, um weitere Rollen für denselben Claim zu vergeben. Jede Ressource kann pro Claim nur eine Rolle erhalten.
Klicke auf Save.

Existiert bereits eine Zuordnung für den Claim, werden die neuen Zeilen hinzugefügt. Um eine Zuordnung zu ändern oder zu entfernen, verwende die Bearbeiten- und Löschaktionen in der Spalte Actions der Tabelle.

Alle Endpunkte erfordern ein API-Token eines Organization Owners. Andere Nutzer erhalten NotAuthorized.

Eine Rollenzuordnung erstellen

curl -X POST "https://<base-domain>/api/organizations/<organization-id>/oidc-role-mappings" \
  -H "Authorization: Bearer $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "claimKey": "groups",
    "claimValue": "engineering",
    "resourceType": "resource_group",
    "resourceId": "42",
    "relation": "admin"
  }'

Feld	Beschreibung
`claimKey`	Abgeflachter Claim-Schlüssel
`claimValue`	Exakter Wert, den der Claim enthalten muss
`resourceType`	`organization` oder `resource_group`
`resourceId`	Die Organization-ID für `organization`, die numerische Resource-Group-ID für `resource_group`
`relation`	`owner` oder `member` für `organization`. `admin` oder `member` für `resource_group`

Das Erstellen einer bereits vorhandenen Zuordnung hat keine Auswirkung. InvalidArgument wird zurückgegeben, wenn:

Die Relation nicht zum Ressourcentyp passt.
Die Ressource nicht existiert oder einer anderen Organization gehört.
Ein Feld leer ist.

Rollenzuordnungen auflisten

curl "https://<base-domain>/api/organizations/<organization-id>/oidc-role-mappings" \
  -H "Authorization: Bearer $CS_TOKEN"

Eine Rollenzuordnung löschen

Sende denselben Body, den du zum Erstellen verwendet hast:

curl -X DELETE "https://<base-domain>/api/organizations/<organization-id>/oidc-role-mappings" \
  -H "Authorization: Bearer $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "claimKey": "groups",
    "claimValue": "engineering",
    "resourceType": "resource_group",
    "resourceId": "42",
    "relation": "admin"
  }'

Das Löschen einer nicht vorhandenen Zuordnung ist erfolgreich.

Das Löschen einer Zuordnung entzieht keinen Zugriff

Rollenzuordnungen fügen nur Zugriff hinzu. Das Löschen einer Zuordnung oder das Entfernen eines Nutzers aus der Gruppe in deinem IdP entfernt keine bereits vergebenen Rollen. Entferne den Nutzer auf der Members-Seite der Organization oder der Resource Group.

Organization-Members-Seite mit der organisatorischen Rolle jedes Mitglieds und einem Aktionsmenü pro Zeile

Identitätsanbieter konfigurieren

Dein IdP muss den Claim, den du zuordnest, in das ID-Token einfügen. Verwende als Redirect-URI https://<base-domain>/ide für den Codesphere-Client.

authentik
Keycloak

authentik fügt die Gruppennamen eines Nutzers über das Standard-Scope-Mapping profile in den groups-Claim ein.

Gehe zu Applications → Providers und erstelle einen OAuth2/OpenID Provider.
Setze Client type auf Confidential.
Füge https://<base-domain>/ide als Redirect URI hinzu.
Prüfe unter Advanced protocol settings, dass Scopes die Standard-Mappings openid, email und profile enthält.
Stelle sicher, dass Include claims in id_token aktiviert ist. Andernfalls erscheint groups nur in der Userinfo-Antwort und Codesphere ignoriert es.
Gehe zu Applications → Applications, erstelle eine Anwendung und wähle den Provider aus.
Kopiere Client ID, Client Secret und OpenID Configuration Issuer von der Provider-Seite. Der Issuer hat die Form https://<authentik-host>/application/o/<application-slug>/.
Gehe zu Directory → Groups und füge Nutzer Gruppen hinzu, zum Beispiel engineering.

Das ID-Token enthält dann:

{
  "groups": ["engineering"]
}

Ordne groups = engineering zu. Der Wert ist der Gruppenname genau so, wie er in authentik angezeigt wird.

Keycloak kann Gruppen oder Rollen bereitstellen. Standardmäßig ist keines von beiden im ID-Token enthalten.

Gehe in deinem Realm zu Clients und erstelle einen OpenID Connect-Client, zum Beispiel codesphere.
Aktiviere Client authentication und den Standard flow.
Füge https://<base-domain>/ide zu Valid redirect URIs hinzu.
Kopiere das Client Secret vom Tab Credentials. Die Issuer-URL lautet https://<keycloak-host>/realms/<realm>.

Füge anschließend den Claim hinzu, den du zuordnen möchtest.

Gruppen

Öffne den Client, gehe zu Client scopes und wähle <client-id>-dedicated, zum Beispiel codesphere-dedicated.
Klicke auf Configure a new mapper (oder Add mapper → By configuration) und wähle Group Membership.
Setze Token Claim Name auf groups.
Deaktiviere Full group path. Andernfalls enthalten die Werte einen führenden Schrägstrich und den übergeordneten Pfad, zum Beispiel /engineering.
Aktiviere Add to ID token.

Ordne groups = engineering zu.

Realm- oder Client-Rollen

Gehe zu Client scopes → roles → Mappers.
Öffne realm roles und aktiviere Add to ID token. Verfahre für client roles ebenso, falls du Client-Rollen zuordnest.

Realm-Rollen kommen als realm_access.roles an. Client-Rollen kommen als resource_access.<client-id>.roles an. Ordne zum Beispiel realm_access.roles = developer zu.

Token prüfen

Öffne den Client, gehe zu Client scopes → Evaluate, wähle einen Nutzer aus und öffne Generated ID token. Der Claim, den du zuordnest, muss dort erscheinen.

Trage Issuer-URL, Client-ID und Client Secret in deiner Installation ein, wie unter Identitätsanbieter beschrieben.

Beispiel

Mitglieder der IdP-Gruppe dev sollen der Organization Rolemapping Organization als Member beitreten, Admins der Resource Group Dev werden und Member der Resource Group QA werden.

Hinzufügen einer Rollenzuordnung für die IdP-Gruppe dev.

Der Cluster-Admin erstellt eine Org-Zuordnung groups = dev → Rolemapping Organization.
Ein Owner von Rolemapping Organization erstellt eine Rollenzuordnung für groups = dev mit drei Zeilen:
- Resource Type Organization, Resource Rolemapping Organization, Role Member
- Resource Type Resource Group, Resource Dev, Role Admin
- Resource Type Resource Group, Resource QA, Role Member
Ein Nutzer in dev meldet sich über OIDC an. Er wird Member von Rolemapping Organization, Admin von Dev und Member von QA.

Verhalten und Einschränkungen

Wird bei jeder Anmeldung angewendet. Zuordnungen werden bei jeder Anmeldung eines Nutzers über OIDC ausgewertet. Änderungen an Zuordnungen wirken sich erst bei der nächsten Anmeldung aus.
Nur additiv. Zuordnungen fügen Rollen hinzu oder heben sie an. Sie entfernen oder senken eine Rolle nie, selbst wenn der Claim verschwindet oder die Zuordnung gelöscht wird. So lassen sich Zuordnungen neben bestehenden manuellen Mitgliedschaften einführen, ohne dass jemand den Zugriff verliert. Das Entfernen von Rollen beim Verschwinden eines Claims ist für eine spätere Version geplant.
Die höchste Rolle gewinnt. Vergeben mehrere Zuordnungen Rollen für dieselbe Ressource, erhält der Nutzer die höchste davon.
Die Anmeldung wird nie blockiert. Schlägt die Anwendung der Zuordnungen fehl oder dauert länger als 5 Sekunden, meldet sich der Nutzer trotzdem an. Nicht angewendete Rollen werden bei einer späteren Anmeldung vergeben.
Nur bestehende Ressourcen. Zuordnungen erstellen nie Organizations oder Resource Groups.
Workspace-Rollen werden nicht unterstützt. Ordne Organization- und Resource-Group-Rollen zu. Workspace-Rollen ergeben sich aus den Vererbungsregeln.
Claim-Limit. Es werden nur die ersten 512 Schlüssel/Wert-Paare eines Tokens abgeglichen.

Fehlerbehebung

Ein Nutzer meldet sich an, erhält aber keine Rollen

Prüfe, ob der Claim im ID-Token enthalten ist und nicht nur in der Userinfo-Antwort.
Vergleiche Schlüssel und Wert Zeichen für Zeichen. Der Abgleich ist case-sensitiv.
Prüfe in Keycloak, ob Full group path den Gruppennamen einen führenden / voranstellt.
Prüfe, ob eine Org-Zuordnung für einen der Claims des Nutzers existiert. Rollenzuordnungen einer Organization ohne passende Org-Zuordnung werden ignoriert.

Die Organization-Rolle funktioniert, die Resource-Group-Rolle jedoch nicht

Der Nutzer muss bereits Mitglied der Organization sein, bevor eine Resource-Group-Rolle angewendet werden kann. Füge der gleichen Zuordnung eine Organization-Rollenzeile hinzu.

Ein Nutzer behält den Zugriff, nachdem er die Gruppe verlassen hat

Das ist erwartetes Verhalten. Entferne den Nutzer manuell auf der Members-Seite.

Funktionsweise​

Claims werden zu Schlüssel/Wert-Paaren​

Claims einer Organization zuordnen​

Claims Rollen zuordnen​

Eine Rollenzuordnung erstellen​

Rollenzuordnungen auflisten​

Eine Rollenzuordnung löschen​

Identitätsanbieter konfigurieren​

Beispiel​

Verhalten und Einschränkungen​

Fehlerbehebung​