Zum Hauptinhalt springen

Authentifizierungs-Clients

Jutro bietet zwei Authentifizierungs-Clients: einen nativen Okta-Client und einen generischen OpenID Connect (OIDC)-Authentifizierungs-Client.

Okta ist ein Identitätsanbieter (IdP), der dem OIDC-Standard entspricht. Der native Okta-Client wurde speziell entwickelt, um ihn zu unterstützen. Sie können den generischen OIDC-Client für die Authentifizierung bei allen anderen Identitätsanbietern verwenden, die den OIDC-Standard unterstützen.

Client-Funktionen​

Die im @jutro/auth-Paket enthaltenen Jutro Authentifizierungs-Clients bieten die folgenden Funktionen:

  • Anmelden bei der Anwendung.
  • Abmelden von der Anwendung.
  • Wenn eine neue Registerkarte mit der Anwendung geöffnet wird, werden Token freigegeben.
  • Wenn sich der Benutzer in einer Registerkarte abmeldet, wird die Abmeldung auch in allen anderen Registerkarten durchgeführt.
  • Der Client aktualisiert das Token eine vorgegebene Anzahl von Sekunden vor Ablauf der Gültigkeit.
  • Der Client stimmt die Aktualisierung der Token zwischen Registerkarten ab.

Aus Entwicklersicht sind noch einige weitere spezifische Funktionen verfügbar:

  • Unterstützung für OIDC Authorization Code Flow mit PKCE-Erweiterung
  • Token-Verwaltung beispielsweise für Speicherung, Abruf und Validierung
  • Möglichkeit zum Definieren von Geltungsbereichen
  • Sicherheitsgewährleistung
  • Fehlerbehandlung
  • Zugriff auf Benutzerinformationen

Optionale Auth-Abhängigkeit​

Die Abhängigkeit @jutro/auth ist jetzt für Pakete @jutro/router und @jutro/components optional. Bestimmte Komponenten erfordern jedoch, dass sie zu den Abhängigkeiten Ihrer App hinzugefügt werden, um verwendet werden zu können. Die folgende Liste zeigt die Komponenten, bei denen @jutro/auth hinzugefügt werden muss:

KomponenteImportieren aus
ApplicationRoot@jutro/app
Avatar@jutro/components
DropdownMenuAvatar@jutro/components
DropdownMenuAvatarContent@jutro/components
AppFloorPlan@jutro/floorplan
MicroFrontend@jutro/micro-frontends
SecureRoute@jutro/router

Konfiguration​

Die gesamte Konfiguration erfolgt über Laufzeit-Umgebungsvariablen. Die folgenden Variablen sind erforderlich:

  • Enable Jutro authorization client usage: REACT_APP_JUTRO_AUTH_ENABLED=true
  • Select the client to use:
    • Okta client: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT=true
    • Generic OIDC client: JUTRO_AUTH_USE_NATIVE_OKTA_CLIENT=false
  • Add IDP configuration variables:
    • REACT_APP_JUTRO_AUTH_ISSUER=https://{your-provider}.com/oauth2/{key}
    • REACT_APP_JUTRO_AUTH_CLIENT_ID={your client ID goes here}
    • REACT_APP_JUTRO_AUTH_REDIRECT_PATH=/auth/callback
    • REACT_APP_JUTRO_AUTH_SCOPE=openid,tenant_id,email,profile,offline_access
    • JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true
    • JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=true
  • The native Okta client handles silent logins, but if you are using the Generic OIDC client and you are using this feature you will need to add two additional configuration variables:
    • REACT_APP_JUTRO_AUTH_SILENT_REDIRECT_PATH=/auth/silent/callback
    • REACT_APP_JUTRO_AUTH_SILENT_LOGIN_PATH=/auth/silent/login

    • Weitere Informationen zu automatischen Anmeldungen finden Sie in der Dokumentation zur automatischen Anmeldung.

Bei Verwendung einer Jutro-Startanwendung benötigen Sie zum Aktivieren der Authentifizierung nur diese Variablen. Die Logik wird in der Jutro-Funktion start() verarbeitet.

Tip: Einige Routen offen

Wenn Sie AppFloorPlan mit aktivierter Authentifizierung verwenden, sind alle Ihre Routen sicher. Wenn Sie möchten, dass bestimmte Routen offen und andere sicher sind, müssen Sie Ihren eigenen Router implementieren. Weitere Informationen finden Sie in unserer Dokumentation zur benutzerdefinierten Authentifizierung.

OIDC-Erkennung (Konfiguration der autoritativen Stelle)​

OpenID Connect (OIDC) definiert einen Erkennungsmechanismus, mit dem Sie Ihre Anwendung konfigurieren können, ohne die genauen Endpunkte des Identitätsanbieters kennen zu müssen. Der Erkennungsmechanismus basiert auf dem Endpunkt /.well-known/openid-configuration, der ein JSON-Dokument mit allen notwendigen Informationen zurückgibt.

Weitere Informationen finden Sie in diesem Artikel zu OpenID Connect Discovery.

In Fällen, in denen der Endpunkt für die automatische Erkennung nicht wie erwartet funktioniert, benötigen Sie die folgenden Laufzeit-Umgebungsvariablen zur manuellen Konfiguration der autoritativen Stelle.

  • REACT_APP_JUTRO_AUTH_AUTHORIZATION_ENDPOINT
  • REACT_APP_JUTRO_AUTH_TOKEN_ENDPOINT
  • REACT_APP_JUTRO_AUTH_REVOCATION_ENDPOINT
  • REACT_APP_JUTRO_AUTH_END_SESSION_ENDPOINT
  • REACT_APP_JUTRO_AUTH_USERINFO_ENDPOINT

Beispielsweise müssen Sie möglicherweise folgende Variablen festlegen:

REACT_APP_JUTRO_AUTH_AUTHORIZATION_ENDPOINT=https://YOUR_DOMAIN/authorize
REACT_APP_JUTRO_AUTH_TOKEN_ENDPOINT=https://YOUR_DOMAIN/oauth/token
REACT_APP_JUTRO_AUTH_REVOCATION_ENDPOINT=https://YOUR_DOMAIN/oauth/revoke
REACT_APP_JUTRO_AUTH_END_SESSION_ENDPOINT=https://YOUR_DOMAIN/oidc/logout
REACT_APP_JUTRO_AUTH_USERINFO_ENDPOINT=https://YOUR_DOMAIN/userinfo
Warning: Wenn Sie eine dieser Variablen festlegen, müssen Sie sie alle festlegen.

Konfigurieren des Ansatzes zur Token-Aktualisierung​

Jutro bietet zwei Ansätze zur Token-Aktualisierung: passive Token-Erneuerung und automatische Anmeldung (auch als aktive Token-Erneuerung bezeichnet). Mit den folgenden Konfigurationsoptionen können Sie einen Ansatz zur Token-Erneuerung festlegen:

Für die passive Token-Erneuerung müssen Sie die Eigenschaft JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS auf true festlegen.

JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true

Für die automatische Anmeldung müssen Sie einen Umleitungspfad und einen Anmeldepfad festlegen.

REACT_APP_JUTRO_AUTH_SILENT_REDIRECT_PATH=/auth/silent/callback
REACT_APP_JUTRO_AUTH_SILENT_LOGIN_PATH=/auth/silent/login

Weitere Informationen zu Ansätzen zur Token-Erneuerung und ihrer Einrichtung finden Sie im Abschnitt Optionen für die Token-Aktualisierung.

Warning: Sie können nicht beide Ansätze gleichzeitig verwenden. Sie müssen die Konfigurationsoption JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS entfernen, wenn Sie die automatische Anmeldung verwenden möchten.

Benutzerdefinierte Abfrageparameter​

Mit der Umgebungsvariablen REACT_APP_JUTRO_AUTH_LOGIN_QUERY_EXTRAS können Sie benutzerdefinierte Abfrageparameter festlegen, die für alle Anmeldeanforderungen gelten sollen:

Note: Der generische OIDC-Client fügt den Abmeldeanforderungen Unterstützung für benutzerdefinierte Abfrageparameter hinzu. Sie können sie mithilfe der Umgebungsvariablen REACT_APP_JUTRO_AUTH_LOGOUT_QUERY_EXTRAS definieren.

Sie müssen gültige JSON-Werte angeben. Sie werden analysiert und in der Abfragezeichenfolge der Anmelde- oder Abmeldeanforderung hinzugefügt.

Sie können z. B. einen prompt-Parameter in der Autorisierungsanforderung einfügen, um so eine erneute Anmeldung des Benutzers zu erzwingen.

REACT_APP_JUTRO_AUTH_LOGIN_QUERY_EXTRAS={"prompt":"login"}

Beachten Sie, dass es sich hierbei um Laufzeit-Umgebungsvariablen handelt. Sie gelten also für alle Anmelde- und (bei Verwendung des generischen OIDC-Clients) Abmeldeanforderungen in Ihrer Anwendung. Informationen zum Hinzufügen benutzerdefinierter Abfrageparameter zu einer spezifischen Anmeldeanforderung finden Sie im Abschnitt An- und Abmeldung.

Ungültig zu machende Token bei der Abmeldung​

Manchmal müssen Sie beim Abmelden nur einige Token ungültig machen. Beispielsweise kann Ihr OIDC-Anbieter automatisch alle Token ungültig machen, die sich auf ein bestimmtes Aktualisierungstoken beziehen. Wenn Sie sich von der Anwendung abmelden, möchten Sie nur das Aktualisierungstoken ungültig machen, da das Zugriffstoken automatisch ungültig gemacht wird. In diesem Fall müssen Sie Folgendes festlegen:

REACT_APP_JUTRO_AUTH_LOGOUT_TOKENS_TO_INVALIDATE=refresh_token

In diesem Fall macht die Funktion logout nur das Aktualisierungstoken ungültig. Wenn Sie JUTRO_AUTH_LOGOUT_TOKENS_TO_INVALIDATE nicht explizit festlegen, macht die Funktion logout alle Token ungültig, da der Standardwert access_token,refresh_token ist.

AuthProvider-Kontextanbieter​

AuthProvider ist der Kontextanbieter, den Sie zum Wrapping Ihrer Anwendung verwenden können. Weitere Informationen finden Sie auf der Seite Authentifizierungs-Client-API.

Wenn Ihre gesamte Anwendung hinter der Anmeldung gesichert werden soll, müssen Sie sich nicht um AuthProvider kümmern, da dies standardmäßig in der Jutro-Funktion start() implementiert ist.

useAuth-Hook​

Der useAuth-Hook bietet Zugriff auf den Authentifizierungsstatus. Weitere Informationen finden Sie auf der Seite Authentifizierungs-Client-API.

Authentifizierungsfehler​

Die Jutro-Authentifizierungsfehlercodes werden über öffentliche Einstiegspunkte als AuthErrorCodes verfügbar gemacht.

Es gibt sechs Jutro-Authentifizierungsfehlercodes:

FehlerUrsache
JUTRO_AUTH_LOGIN_ERRORDie Anwendung konnte keine Authentifizierungstoken abrufen.
JUTRO_AUTH_REFRESH_ERRORDie Anwendung konnte die Authentifizierungstoken nicht erneuern.
JUTRO_AUTH_USER_INFO_ERRORDie Anwendung konnte keine Benutzerinformationen abrufen.
JUTRO_AUTH_UNKNOWN_ERROREin unbekannter Fehler ist aufgetreten.
JUTRO_AUTH_ACCESS_DENIED_ERRORDer Benutzer ist der Anwendung nicht zugewiesen.
JUTRO_AUTH_LOGIN_REQUIRED_ERRORDie Anwendung konnte Token nicht mit der automatischen Anmeldung erneuern, da Cookies von Drittanbietern im Browser blockiert werden.

Wenn Sie benutzerdefinierte Authentifizierungslogik implementieren, müssen Sie möglicherweise für einige dieser Fehler eine benutzerdefinierte Fehlerbehandlung hinzufügen. Weitere Informationen finden Sie im Abschnitt Benutzerdefinierte Verarbeitung von Authentifizierungsfehlern auf der Seite „Implementieren einer benutzerdefinierten Authentifizierungslogik“.

Umgang mit Sitzungs-Cookies von Drittanbietern​

Sitzungs-Cookies von Drittanbietern können in einigen Webbrowsern eingeschränkt sein, was zu Problemen bei der Verarbeitung von Sitzungen mit einigen OIDC-Clients führen kann. Darüber hinaus funktioniert die automatische Anmeldung als Ansatz zur Token-Aktualisierung nicht, wenn Cookies von Drittanbietern eingeschränkt sind. Daher wird in diesem Szenario JUTRO_AUTH_LOGIN_REQUIRED_ERROR ausgelöst.

Um sicherzustellen, dass die Sitzungen Ihrer Benutzer korrekt verarbeitet werden, müssen Sie die folgenden Änderungen vornehmen:

  • Wenn Sie den generischen OIDC-Client ohne automatische Anmeldung verwenden, entfernen Sie die Variablen JUTRO_AUTH_SILENT_LOGIN_PATH und JUTRO_AUTH_SILENT_REDIRECT_PATH.

  • Wenn Sie den generischen OIDC-Client mit automatischer Anmeldung verwenden, migrieren Sie zur passiven Token-Erneuerung.

  • Erweitern Sie die Konfigurationsvariable REACT_APP_JUTRO_AUTH_SCOPE durch Hinzufügen von offline_access. Beispiel: REACT_APP_JUTRO_AUTH_SCOPE=openid,tenant_id,email,profile,offline_access

  • Aktualisieren Sie Ihre Keti-Anwendungskonfiguration so, dass die Zusage REFRESH_TOKEN im Array authSettings.grantTypes eingefügt wird. Dazu sind folgende Schritte erforderlich:
    1. Führen Sie einen GET-API-Aufruf GET /applications/{appId} aus, um die aktuellen Konfigurationseinstellungen Ihrer Anwendung abzurufen.
    2. Kopieren Sie die zurückgegebenen Anwendungsnutzdaten.
    3. Fügen Sie REFRESH_TOKEN zum Abschnitt grantTypes der kopierten Nutzdaten hinzu.
    4. Führen Sie einen PUT-API-Aufruf PUT /applications/{appId} mit den neuen Nutzdaten aus, um Ihre Anwendungskonfiguration zu aktualisieren.

Benutzerdefinierte Authentifizierung​

Wenn Ihre gesamte Anwendung hinter der Anmeldung gesichert werden soll, sind keine weiteren Anpassungen erforderlich. Die Authentifizierungslogik wird in der Jutro-Funktion start() verarbeitet.

Wenn Sie festlegen möchten, wie die Anmeldung in Ihrer Anwendung erfolgen soll, z. B. Anmeldung nur für bestimmte Seiten erforderlich, müssen Sie eine benutzerdefinierte Authentifizierungslogik implementieren. Weitere Informationen finden Sie auf der Seite Implementieren einer benutzerdefinierten Authentifizierungslogik.