OIDC-Integration

DTZ Identity ist ein standardkonformer OpenID Connect (OIDC)-Anbieter. Jeder Dienst, der OIDC unterstützt, kann die Authentifizierung an DTZ delegieren, sodass sich Ihre Benutzer mit ihren bestehenden DTZ-Zugangsdaten anmelden können.

Voraussetzungen

  • Ein DTZ-Konto und mindestens ein Kontext (context-{id})
  • Ein Dienst oder eine Anwendung, die den OIDC-/OAuth 2.0-Authorization-Code-Flow unterstützt

Discovery endpoint

DTZ veröffentlicht ein standardmäßiges OIDC-Discovery-Dokument:

https://identity.dtz.rocks/.well-known/openid-configuration

Die meisten OIDC-Clientbibliotheken akzeptieren eine Issuer-URL und laden dieses Dokument automatisch, um sich zu konfigurieren. Setzen Sie den Issuer auf https://identity.dtz.rocks und lassen Sie die Bibliothek die Endpunkt-Erkennung übernehmen.

Client-Anmeldeinformationen

DTZ verwendet die Kontext-ID sowohl als client_id als auch als client_secret. Eine separate Anwendungsregistrierung ist nicht erforderlich.

Parameter Wert
client_id Ihre Kontext-ID, z. B. context-abc123
client_secret Dieselbe Kontext-ID
issuer https://identity.dtz.rocks

Konfigurationsreferenz

Die folgenden Umgebungsvariablen veranschaulichen eine typische Integration:

OIDC_ISSUER=https://identity.dtz.rocks
OIDC_CLIENT_ID={YOUR_CONTEXT_ID}
OIDC_CLIENT_SECRET={YOUR_CONTEXT_ID}
OIDC_REDIRECT_URI=https://yourapp.example.com/login

Die Namen der Variablen können zwischen Bibliotheken und Frameworks variieren; entscheidend sind die oben genannten Werte.

ID-Token-Claims

Nach einem erfolgreichen Token-Austausch geben das ID-Token und der Userinfo-Endpunkt die folgenden Claims zurück:

Anspruch Beispielwert Beschreibung
sub identity-12345678 Eindeutige Kennung der Identität
iss dtz.rocks Token-Aussteller — für von DTZ ausgestellte Tokens immer dtz.rocks
contexts ["abc124"] Kontext-IDs, denen der Benutzer angehört
roles ["https://dtz.rocks/context/admin/abc123"] Konkrete Rollen-URIs, die dem Benutzer zugewiesen sind

Zugriffskontrolle über Claims

Verwenden Sie Claim-Werte, um einzuschränken, wer nach einer erfolgreichen OIDC-Anmeldung auf Ihren Dienst zugreifen darf.

Auf beliebige DTZ-Benutzer beschränken — prüfen Sie, dass iss gleich dtz.rocks ist:

OIDC_ALLOWED_CLAIM=iss
OIDC_ALLOWED_VALUES=dtz.rocks

Auf Benutzer in einem bestimmten Kontext beschränken — prüfen Sie das contexts-Array:

OIDC_ALLOWED_CLAIM=scope
OIDC_ALLOWED_VALUES={YOUR_CONTEXT_ID}}

Auf Benutzer mit einer bestimmten Rolle beschränken — prüfen Sie das roles-Array auf eine konkrete Rollen-URI.

Der genaue Mechanismus zur Auswertung dieser Prüfungen hängt von Ihrer OIDC-Bibliothek oder Middleware ab.

Authorization code flow

  1. Leiten Sie den nicht authentifizierten Benutzer an den DTZ-Authorize-Endpunkt weiter (über Discovery aufgelöst).
  2. Der Benutzer authentifiziert sich bei https://identity.dtz.rocks. Bereits angemeldete Benutzer werden sofort zurückgeleitet.
  3. Tauschen Sie den zurückgegebenen Autorisierungscode am Token-Endpunkt gegen Tokens aus.
  4. Validieren Sie den iss-Claim des ID-Tokens sowie alle zusätzlichen Zugriffssteuerungs-Claims.
  5. Gewähren oder verweigern Sie den Zugriff basierend auf Ihrer Claim-Richtlinie.

Userinfo endpoint

GET https://identity.dtz.rocks/api/2021-02-21/oauth/userinfo
Authorization: Bearer <access_token>

Gibt dieselben Claims wie das ID-Token zurück. Verwenden Sie diesen Endpunkt, wenn Sie nach der anfänglichen Anmeldung aktuelle Claim-Werte erneut abrufen müssen.

Verwandt

  • OAuth 2 overview — wie DTZ den Authorization-Code-Flow implementiert
  • Roles — Verständnis für konkrete und abstrakte Rollen
  • Identity overview — Kontexte, Identitäten und Zugriffskontrolle