Authentifizierungs-Client-API

Als Entwickler können Sie die Authentifizierung unter Verwendung der folgenden Komponenten, Hooks und Funktionen in Ihrer Anwendung implementieren.

AuthProvider-Kontextanbieter

AuthProvider ist der Kontextanbieter, den Sie zum Wrapping Ihrer Anwendung verwenden können. Ermöglicht den Zugriff auf den useAuth-Hook.

AuthProvider umfasst die folgenden Eigenschaften.

children

Typ

React.ReactNode

Beschreibung

Nodes wrapped by the AuthProvider component.

location

Typ

{ pathname: string }

Beschreibung

Current window location. If you use react-router-dom, pass the result of useLocation().

onLocationChange

Typ

(location: string | Record<string, unknown>) => void

Beschreibung

Callback to change window location. If you use react-router-dom, pass path => history.replace(path).

Bei einer Anwendung, die mit der Jutro-Startanwendung erstellt wurde, müssen Sie AuthProvider nicht selbst hinzufügen. Er wird automatisch in der Funktion start() hinzugefügt.

Weitere Informationen und Anleitungen zur Verwendung finden Sie auf der Seite Implementieren einer benutzerdefinierten Authentifizierungslogik.

useAuth-Hook

Der useAuth-Hook bietet Zugriff auf den Authentifizierungsstatus. Er gibt ein AuthContext-Objekt mit den folgenden Variablen zurück:

import { useAuth } from '@jutro/auth';

const {
  isPending,
  error,
  login,
  logout,
  renewTokens,
  isAuthenticated,
  accessToken,
  idToken,
  userInfo,
  getIsAuthenticated,
  getAccessToken,
  getIdToken,
  getUserInfo,
} = useAuth();

Variablen für Authentifizierungskontext

Gemeinsame Variablen

Die folgenden Variablen sind unabhängig von der verwendeten Methode zur Token-Aktualisierung gleich.

isPending

Typ

boolean

Beschreibung

If set to true, indicates that authentication is still pending.

error

Typ

AuthError

Beschreibung

This property is present only if an error occurs. It contains an AuthError object with details about the error.

login

Typ

AuthLogin

Beschreibung

The function called to initiate a log in. For more details, see the login and logout section.

logout

Typ

AuthLogout

Beschreibung

The function called to initiate a log out. For more details, see the login and logout section.

renewTokens

Typ

(extraParams?: Record<string, string>) => Promise<void>

Beschreibung

The function called to refresh a user's authentication tokens. This gives you more control over when the token refresh flow is triggered. For more details, see the renewToken function section.

Variablen für aktive Token-Aktualisierung

Die folgenden Variablen werden bei der aktiven Token-Aktualisierung verwendet. Bei Verwendung der passiven Token-Aktualisierung sind alle auf null festgelegt.

isAuthenticated

Typ

boolean | null

Beschreibung

If set to true, the user is currently authenticated.

accessToken

Typ

string | null

Beschreibung

This string is the user's encoded access token. For further details, see the accessToken and idToken section.

idToken

Typ

string | null

Beschreibung

This string is the user's encoded ID token. For further details, see the accessToken and idToken section.

userInfo

Typ

OidcUserInfo | null

Beschreibung

This is the user's OIDC user info. For more details, see the OIDC documentation.

Variablen für passive Token-Aktualisierung

Die folgenden Variablen werden bei der passiven Token-Aktualisierung verwendet. Diese Variablen funktionieren wie die Variablen für die aktive Token-Aktualisierung, sind jedoch asynchron, erneuern die Token bei Bedarf und geben die erwarteten Daten zurück. Wenn die aktive Token-Aktualisierung verwendet wird oder bei der Token-Erneuerung Fehler auftreten, wird eine Zusage zurückgegeben, die in nullaufgelöst wird.

getIsAuthenticated

Typ

() => Promise<boolean | null>

Beschreibung

This function returns a promise that resolves to the user's current authentication status. If it resolves to true, the user is currently authenticated.

getAccessToken

Typ

() => Promise<string | null>

Beschreibung

This function returns a promise that resolves to the user's encoded access token. For further details, see the accessToken and idToken section.

getIdToken

Typ

() => Promise<string | null>

Beschreibung

This function returns a promise that resolves to the user's encoded ID token. For further details, see the accessToken and idToken section.

getUserInfo

Typ

() => Promise<OidcUserInfo | null>

Beschreibung

This function returns a promise that resolves to user's OIDC user info. For more details, see the OIDC documentation.

Weitere Informationen zur Token-Aktualisierung finden Sie auf der Seite zur Token-Aktualisierung.

Anmeldung und Abmeldung

Diese beiden Funktionen werden vom useAuth-Hook zurückgegeben. Mit ihnen können Sie den Anmelde- bzw. Abmeldevorgang auslösen. Sie können die folgenden Argumente an beide Funktionen übergeben:

Umleitungspfad

Der Umleitungspfad bezeichnet den Pfad, zu dem die Umleitung nach dem Anmelde- oder Abmeldevorgang erfolgen soll.

Sie können den Umleitungspfad nach der Anmeldung oder Abmeldung auf verschiedene Weise konfigurieren. Standardmäßig werden in Jutro integrierte Pfade verwendet: /callback für die Anmeldung und /logout für die Abmeldung. Sie können auch benutzerdefinierte Pfade mithilfe der Konfigurationsvariablen festlegen: JUTRO_AUTH_REDIRECT_PATH für die Anmeldung und JUTRO_AUTH_LOGOUT_REDIRECT_PATH für die Abmeldung. Außerdem können Sie den Umleitungspfad festlegen, indem Sie ihn als erstes Argument an die Funktionen login() und logout() übergeben. Diese Parameter lauten callbackPath für login() und fromPath für logout().

In der folgenden Tabelle sind diese Informationen zusammengefasst:

Funktion	Parametername	Aus Konfigurationsdatei übernommener Wert	Integrierter Standardpfad
login()	callbackPath	JUTRO_AUTH_REDIRECT_PATH	/callback
logout()	fromPath	JUTRO_AUTH_LOGOUT_REDIRECT_PATH	/logout

Die Umgebungsvariable JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL muss auf true festgelegt werden, damit der Wert routerBasename der als Parameter eingegebenen Zeichenfolge den Funktionen login() oder logout() vorangestellt wird.

Note: Die Umgebungsvariable JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL wurde in Jutro Version 10.10 eingeführt. Die Einstellung JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=false gilt als abgekündigt. Anweisungen zur Verwendung der Funktionen login() und logout() ohne automatisches Voranstellen von routerBasename finden Sie in einer Version der Dokumentation, die älter als 10.10 ist.

Note: Beschränkung der Werte für JUTRO_AUTH_LOGOUT_REDIRECT_PATH

Die Umgebungsvariable JUTRO_AUTH_LOGOUT_REDIRECT_PATH kann entweder der Endpfad der Abmeldungs-URL oder die vollständige URL sein.

Angenommen, die Anwendung wird unter der gefälschten URL guidewire.com/my-best-app bereitgestellt und Ihr gewünschter Umleitungspfad für die Abmeldung lautet guidewire.com/my-best-app/logout:

JUTRO_AUTH_LOGOUT_REDIRECT_PATH=/my-best-app/logout                         // correct - will render as https://guidewire.com/my-best-app/logout
JUTRO_AUTH_LOGOUT_REDIRECT_PATH=/logout                                     // correct - will render as https://guidewire.com/my-best-app/logout
JUTRO_AUTH_LOGOUT_REDIRECT_PATH=https://guidewire.com/my-best-app/logout    // correct - will render as https://guidewire.com/my-best-app/logout
JUTRO_AUTH_LOGOUT_REDIRECT_PATH=guidewire.com/my-best-app/logout            // incorrect - will render as https://guidewire.com/my-best-app/guidewire.com/my-best-app/logout

additionalParams

Das Vorhandensein dieses Parameters hängt davon ab, welche Funktion und welchen Client Sie verwenden. Für die login-Funktion ist er in beiden Clients vorhanden. Für die logout-Funktion ist er für den generischen Okta-Client nicht vorhanden.

login() additionalParams

In beiden Clients hat die login()-Funktion ein optionales additionalParams-Argument. Dieses Argument verwendet ein Objekt mit zusätzlichen Abfrageparametern, die Sie der Anmeldeanforderung hinzufügen möchten.

Sie können sie global mit der Laufzeit-Umgebungsvariablen JUTRO_AUTH_LOGIN_QUERY_EXTRAS festlegen.

login('/my-account', { idp: 'some-idp' });

Um diese Werte basierend auf Umgebungsvariablen dynamisch festzulegen, fügen Sie folgenden Code in der .env-Datei oder als Bereitstellungsvariable ein:

JUTRO_AUTH_LOGIN_QUERY_EXTRAS = {"idp":"${YOUR_IDP_ID}"}

Verwenden Sie den folgenden Code lokal, um die ordnungsgemäße Ausführung zu überprüfen. Bei ordnungsgemäßer Ausführung wird er in ein Objekt mit einer leeren Zeichenfolge im idp-Schlüssel aufgelöst, wenn YOUR_IDP_ID nicht angegeben ist. Wenn YOUR_IDP_ID angegeben ist, wird der Wert entsprechend festgelegt.

import { getConfigValue } from '@jutro/config';
...
console.log(JSON.parse(getConfigValue('JUTRO_AUTH_LOGIN_QUERY_EXTRAS')));

logout() additionalParams

Wenn Sie den generischen OIDC-Client verwenden, hat die Funktion logout() auch ein optionales additionalParams-Argument.

Sie können sie global mit der Laufzeit-Umgebungsvariablen JUTRO_AUTH_LOGOUT_QUERY_EXTRAS festlegen.

Um diese Werte basierend auf Umgebungsvariablen dynamisch festzulegen, fügen Sie folgenden Code in der .env-Datei oder als Bereitstellungsvariable ein:

JUTRO_AUTH_LOGOUT_QUERY_EXTRAS = {"idp":"${YOUR_IDP_ID}"}

Verwenden Sie den folgenden Code lokal, um die ordnungsgemäße Ausführung zu überprüfen. Bei ordnungsgemäßer Ausführung wird er in ein Objekt mit einer leeren Zeichenfolge im idp-Schlüssel aufgelöst, wenn YOUR_IDP_ID nicht angegeben ist. Wenn YOUR_IDP_ID angegeben ist, wird der Wert entsprechend festgelegt.

import { getConfigValue } from '@jutro/config';
...
console.log(JSON.parse(getConfigValue('JUTRO_AUTH_LOGOUT_QUERY_EXTRAS')));

renewTokens-Funktion

Standardmäßig wird eine Token-Aktualisierung 40 Sekunden vor der Ablaufzeit ausgeführt (dieses Verhalten kann abweichen, wenn ein anderer Ansatz zur Token-Aktualisierung verwendet wird). Wenn Sie mehr Kontrolle über den Ablauf der Token-Aktualisierung haben möchten, können Sie die renewTokens-Funktion aus dem useAuth-Hook verwenden. Diese ermöglicht die Initialisierung des Ablaufs der Token-Aktualisierung zu einem beliebigen Zeitpunkt.

Damit beispielsweise beim Klicken auf eine Schaltfläche eine Token-Aktualisierung ausgelöst wird, kann folgender Code verwendet werden:

import React from 'react';
import { useAuth } from '@jutro/auth';
// ...
const { renewTokens } = useAuth();
// ...
<button onClick={() => renewTokens()}>Force tokens renewal</button>;

Bei mehreren Aufrufen von renewTokens werden nicht mehrere Abläufe initiiert – nur der erste Aufruf wird ausgeführt. Alle nachfolgenden Aufrufe geben die gleiche Zusage zurück. Ein neuer Erneuerungsablauf kann erst initiiert werden, nachdem der vorherige abgeschlossen ist.

Note: renewTokens gibt Promise<void> zurück. Aber es ist nicht sicher, einen neuen Token-Wert direkt dort auszulesen, da möglicherweise noch der alte Wert angezeigt wird. Die korrekte Art des Zugriffs auf ein neues Token lautet:

const { accessToken, renewTokens } = useAuth();
// ...
useEffect(() => {
  console.log('new token', accessToken);
}, [accessToken]);
// ...
<button onClick={() => renewTokens()}>Force tokens renewal</button>;

accessToken und idToken

Mit der Eigenschaft accessToken oder idToken können Sie das Authentifizierungstoken eines Benutzers abrufen. Die Eigenschaft wird mit den Funktionen decodeToken und decodeJWTTokenPayload aus dem @jutro/auth-Paket verwendet.

decodeToken

Die Funktion decodeToken decodiert das Authentifizierungstoken eines Benutzers.

import { useAuth, decodeToken } from '@jutro/auth';

const { accessToken } = useAuth();
const decodedToken = decodeToken(accessToken);

decodeJWTTokenPayload

Die Funktion decodeJWTTokenPayload decodiert die Token-Nutzdaten ohne Kopfzeile, Signatur oder andere Felder, die das Token enthalten kann.

import { useAuth, decodeJWTTokenPayload } from '@jutro/auth';

const { accessToken } = useAuth();
const decodedJWTTokenPayload = decodeJWTTokenPayload(accessToken);