Migration zum neuen Authentifizierungs-Client

In Version 8.13.0 haben wir einen neuen Authentifizierungs-Client eingeführt. Dieser neue Client bietet die Wahl zwischen einem generischen Authentifizierungs-Client, der nicht an einen bestimmten Identitätsanbieter (IdP) gebunden ist, und einem Okta-basierten Client. Diese neuen Authentifizierungs-Clients sind mit dem älteren Authentifizierungs-Client nicht abwärtskompatibel. Bei Verwendung des älteren Authentifizierungs-Clients müssen Sie zum neuen Authentifizierungs-Client migrieren.

Konfiguration

Die Umgebungsvariablen müssen wie folgt aussehen:

• 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.

Weitere Informationen zum Konfigurieren des neuen Authentifizierungs-Clients finden Sie in unserer Dokumentation zum Authentifizierungs-Client.

Nicht unterstützte Umgebungsvariablen

Die folgenden Umgebungsvariablen aus dem älteren Authentifizierungs-Client werden im neuen Authentifizierungs-Client nicht unterstützt:

• REACT_APP_JUTRO_AUTH_PKCE_ENABLED: PKCE ist im neuen Authentifizierungs-Client immer aktiviert.
• REACT_APP_JUTRO_AUTH_IDP: Diese Variable bezieht sich direkt auf Okta und ist nicht im neuen Authentifizierungs-Client enthalten, der generisch und nicht IdP-spezifisch ist. Sie können jedoch weiterhin benutzerdefinierte Abfrageparameter für die An- und Abmeldung verwenden. Weitere Informationen finden Sie in der Dokumentation zur An- und Abmeldung.
• REACT_APP_JUTRO_AUTH_AUTO_RENEW: Die automatische Erneuerung ist im neuen Authentifizierungs-Client standardmäßig aktiviert.
• REACT_APP_JUTRO_AUTH_STORAGE: Legt die Art des Speichermechanismus fest, der im Jutro-Authentifizierungssystem verwendet wird.

Außerdem wurde die Variable REACT_APP_JUTRO_AUTH_GENERIC_CLIENT entfernt, da sie nicht mehr verwendet wird. Wenn sie noch in Ihrem Projekt enthalten ist, können Sie sie entfernen.

Alle anderen Umgebungsvariablen werden im neuen Authentifizierungs-Client unterstützt. Es ist keine weitere Aktion erforderlich.

Handhabung der automatischen Erneuerung

Die automatische Erneuerung ist im neuen Authentifizierungs-Client standardmäßig aktiviert. REACT_APP_JUTRO_AUTH_AUTO_RENEW wird nicht unterstützt. Wenn Sie den Status des Tokens überwachen und prüfen möchten, wann es abläuft, können Sie diese Informationen mit der Funktion decodeJWTTokenPayload aus dem JWT-Token abrufen.

Sie können einen benutzerdefinierten Hook zum Überwachen des Token-Status implementieren. Im Folgenden finden Sie ein Beispiel dafür, wie Sie Benutzer warnen können, dass ihr Token bald abläuft:

import React, { useEffect, useState } from 'react';
import { useAuth, decodeJWTTokenPayload } from '@jutro/auth';
import { showLogoutAlert } from '@site/components/Alerts'; // your custom alert component

export const useTokenStatus = () => {
  const { idToken } = useAuth();
  const TIME_BEFORE_EXPIRED = 30 * 1000; // 30 seconds

  useEffect(() => {
    const { exp: expiresAt } = decodeJWTTokenPayload(idToken);

    const expireEventWait = Math.max(
      parseInt(expiresAt.toString()) * 1000 - Date.now() - TIME_BEFORE_EXPIRED,
      0
    );

    const expireTimeout = setTimeout(() => {
      showLogoutAlert(TIME_BEFORE_EXPIRED); // logic you handle to warn the user
    }, expireEventWait);

    return () => {
      clearInterval(expireTimeout);
    };
  }, [idToken]);
};

Das folgende Beispiel zeigt, wie andere Ereignisse verarbeitet werden, z. B. wenn das Token abgerufen oder entfernt wird:

import React, { useEffect, useRef } from 'react';
import { useAuth, decodeJWTTokenPayload } from '@jutro/auth';

export const useLogTokenStatus = () => {
  const { idToken, error } = useAuth();
  const tokenRef = useRef('');

  useEffect(() => {
    if (idToken && !tokenRef.current) {
      console.log('EVENT: ', 'TOKEN_ACQUIRED');
    }
    if (idToken && tokenRef.current) {
      console.log('EVENT: ', 'TOKEN_RENEWED');
    }
    tokenRef.current = idToken;
  }, [idToken]);
};

Aus useAuth entfernt

Mehrere Werte und Funktionen werden von useAuth nicht mehr zurückgegeben. Wenn Sie eines der folgenden Elemente verwenden, müssen Sie Ihren Code aktualisieren:

• authenticated: Verwenden Sie stattdessen isAuthenticated.
• tokenManager: nicht unterstützt
• getAccessToken: Verwenden Sie stattdessen accessToken.
• getIdToken: Verwenden Sie stattdessen idToken.
• getDefaultScopes: Verwenden Sie stattdessen decodedToken oder decodedJWTTokenPayload.
• getTransientTokens: nicht unterstützt
• allocateToken: nicht unterstützt
• decodeToken: Wurde aus useAuth entfernt und ist nun ein Export von @jutro/auth.
• getDecodedIdToken: Verwenden Sie stattdessen decodeToken und achten Sie dabei darauf, dass idToken als Argument übergeben wird.
• getDecodedAccessToken: Verwenden Sie stattdessen decodeToken und achten Sie dabei darauf, dass accessToken als Argument übergeben wird.

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

// ...

const { accessToken, idToken } = useAuth();
const decodedAccessToken = decodeToken(accessToken);
const decodedIdToken = decodeToken(idToken);

Aktualisierte Funktionen

login und logout, die von useAuth zurückgegeben werden, unterstützen andere Parameter:

Weitere Informationen finden Sie in der Dokumentation zur An- und Abmeldung.

Weitere Änderungen

Passive Token-Erneuerung

Die passive Token-Erneuerung wurde in Version 10.10 eingeführt. Die aktive Erneuerung wird nicht abgekündigt, es wird jedoch empfohlen, zur passiven Erneuerung zu wechseln. Um diese Funktion zu aktivieren, müssen Sie die folgenden Schritte ausführen:

1. Entfernen Sie die Variablen JUTRO_AUTH_SILENT_REDIRECT_PATH und JUTRO_AUTH_SILENT_LOGIN_PATH (falls vorhanden). Diese Variablen sind spezifisch für den aktiven Ansatz mit unbeaufsichtigter Anmeldung und werden für den passiven Ansatz nicht benötigt.
2. Fügen Sie offline_access zur Variable JUTRO_AUTH_SCOPE hinzu.
3. Stellen Sie sicher, dass die Guidewire Hub-Anwendungskonfiguration die Berechtigung REFRESH_TOKEN im authSettings.grantTypes-Array enthält.
4. Variable JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true hinzufügen.
5. Ersetzen Sie die folgenden Verwendungen von Eigenschaften aus dem useAuth-Hook:

Aktive Erneuerung	Passive Erneuerung
isAuthenticated: boolean | null	getIsAuthenticated: () => Promise<boolean | null>
accessToken: string | null	getAccessToken: () => Promise<string | null>
idToken: string | null	getIdToken: () => Promise<string | null>
userInfo: OidcUserInfo | null	getUserInfo: () => Promise<OidcUserInfo | null>

Weitere Informationen zur passiven Erneuerung finden Sie in der Dokumentation zum Authentifizierungs-Client.

Umgebungsvariable JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL

Die Umgebungsvariable JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL wurde in Version 10.10 eingeführt.

Wenn Sie den Wert dieser Umgebungsvariablen auf true festlegen, wird der routerBasename-Wert automatisch vorangestellt, um Pfade umzuleiten, die als Argumente an die Funktionen login() und logout() des Authentifizierungs-Clients übergeben werden. Bei der Übergabe von Umleitungspfaden zu login() und logout() mit JUTRO_AUTH_PREPEND_AUTH_CALLBACKS_WITH_BASEURL=false wird eine Abkündigungswarnung angezeigt.

Weitere Informationen finden Sie in der Dokumentation zum Authentifizierungs-Client.

AuthContext aus Jutro-Authentifizierungspaket entfernt

AuthContext ist nicht mehr im @jutro/auth-Paket enthalten. Sie müssen die Verwendung je nach dem spezifischen Anwendungsfall aktualisieren:

• Ändern von const auth = useContext(AuthContext) in const auth = useAuth()

• <AuthContext.Provider ... /> : Je nach Verwendung haben Sie folgende Möglichkeiten:

  • Ersetzen durch AuthProviderStatic:

    <AuthContext.Provider value={...}>
    ...
    </AuthContext.Provider>
  
    // changed to
  
  import { AuthProviderStatic } from `@jutro/auth`;
  
  <AuthProviderStatic
    userInfo={{ name: 'Authenticated User', sub: '' }}
    accessToken="accessToken"
    idToken="idToken"
    >
  ...
  </AuthProviderStatic>
  

  • Bei Verwendung von <AuthContext.Provider ... /> in Unit-Tests zum Bereitstellen von Testdaten, besteht die Möglichkeit des Ersetzens durch einen simulierten useAuth:

  jest.mock('@jutro/auth', () => ({
    useAuth: jest.fn(() => ({
      logout: jest.fn(),
      userInfo: {
        name: 'John Doe',
        email: 'john@doe.com',
        picture: './styles/images/avatar/avatar.png',
      },
      isAuthenticated: true,
    })),
  }));

Entfernte Lebenszyklusereignisse

Da Lebenszyklusereignisse aus der Okta-Client-Bibliothek entfernt wurden, werden die folgenden Elemente nicht mehr aus @jutro/auth exportiert:

• EVENT_ADDED
• EVENT_EXPIRED
• EVENT_RENEWED
• EVENT_ERROR
• EVENT_REMOVED

Im Abschnitt Handhabung der automatischen Erneuerung finden Sie Informationen dazu, wie das gleiche Verhalten mit idToken und decodeJWTTokenPayload generiert werden kann.

Verwenden der Homepage in package.json

Wenn Sie bei Verwendung des neuen Authentifizierungs-Clients die Homepage in package.json angeben und einen lokalen Entwicklungsserver ausführen, hängt die Anwendung möglicherweise auf unbestimmte Zeit oder löst Fehler aus. Zum Beheben des Problems müssen Sie eine der folgenden Aktionen ausführen:

• Öffnen Sie die Anwendung mit http://localhost:3000/<your "homepage" value>/ (der Schrägstrich am Ende ist wichtig). Wenn die Homepage z. B. /storage lautet, müssen Sie die Anwendung mit http://localhost:3000/storage/ öffnen.
• Entfernen Sie die Homepage aus der Datei package.json (nach dieser Änderung müssen Sie node_modules/.cache entfernen). Wenn Ihre Bereitstellungen nach dieser Änderung nicht mehr funktionieren, haben Sie wahrscheinlich die Variable PUBLIC_URL in Ihren Konfigurationen übersehen. Nähere Informationen finden Sie in der Dokumentation zum Routing.

Bereitstellen einer Anwendung in einer Unterroute

Wenn Sie Ihre Anwendung in einer Unterroute bereitstellen, z. B. company.com/claims-manager, müssen Sie in index.html der Anwendung das folgende Element hinzufügen, damit sie ordnungsgemäß funktioniert: <base href="%PUBLIC_URL%/" />. Weitere Informationen finden Sie im Abschnitt Basisname in der Dokumentation zum Routing.

AuthContext

Die Komponente AuthContext aus @jutro/auth ist nicht mit dem OIDC-Authentifizierungs-Client kompatibel. Als neue Methode wird AuthProviderStatic verwendet.

Alte Methode:

<AuthContext.Provider value={{ authenticated: true }}>
  <NavigateStorage navigation={navigation} /> // this calls useAuth inside
</AuthContext.Provider>

Neue Methode:

<AuthProviderStatic
  userInfo={{ name: 'Authenticated User', sub: '' }}
  accessToken="accessToken"
  idToken="idToken">
  <NavigateStorage navigation={navigation} /> // this calls useAuth inside
</AuthProviderStatic>

Alternativ können Sie für Unit-Tests den Hook useAuth simulieren:

jest.mock('@jutro/auth', () => ({
  useAuth: jest.fn(() => ({
    logout: jest.fn(),
    accessToken: 'accessToken',
    idToken: 'idToken',
    userInfo: { name: 'Authenticated User', sub: '' },
    isAuthenticated: true,
  })),
}));

Siehe auch

• Weitere Informationen zum Verwalten des Routings mit dem neuen Authentifizierungs-Client finden Sie in der Dokumentation zum Routing.