Authentifizierung zu deiner Vanilla JS-Anwendung hinzufügen
Vanilla JS: Integriere @logto/browser
- Das vanilla-js SDK ist framework-unabhängig, du kannst es in jedem Frontend-Framework verwenden, indem du einen Wrapper schreibst, der es anpasst.
- Das Beispielprojekt ist in unserem SDK-Repository verfügbar.
Voraussetzungen
- Ein Logto Cloud Konto oder ein selbstgehostetes Logto.
- Eine Single-Page-Anwendung (SPA), die in der Logto-Konsole erstellt wurde.
- Ein Vanilla JS App-Projekt.
Installation
Wähle deinen bevorzugten Paketmanager oder verwende das CDN, um das Logto Browser SDK zu installieren.
- npm
- pnpm
- yarn
- CDN
npm i @logto/browser
pnpm add @logto/browser
yarn add @logto/browser
<!-- Besonderer Dank an jsdelivr -->
<script type="module">
import LogtoClient from 'https://cdn.jsdelivr.net/npm/@logto/[email protected]/+esm';
</script>
Integration
LogtoClient initialisieren
Importiere und initialisiere eine LogtoClient-Instanz, indem du die Konfiguration übergibst:
import LogtoClient from '@logto/browser';
const logtoClient = new LogtoClient({
endpoint: '<your-logto-endpoint>',
appId: '<your-application-id>',
});
Der endpoint und die appId sind auf der Anwendungsdetailseite in der Logto-Konsole zu finden.
Konfigurieren von Redirect-URIs
Bevor wir in die Details eintauchen, hier ein kurzer Überblick über die Endbenutzererfahrung. Der Anmeldeprozess kann wie folgt vereinfacht werden:
- Deine App ruft die Anmeldemethode auf.
- Der Benutzer wird zur Logto-Anmeldeseite umgeleitet. Bei nativen Apps wird der Systembrowser geöffnet.
- Der Benutzer meldet sich an und wird zurück zu deiner App umgeleitet (konfiguriert als die Redirect-URI).
Bezüglich der umleitungsbasierten Anmeldung
- Dieser Authentifizierungsprozess folgt dem OpenID Connect (OIDC) Protokoll, und Logto erzwingt strenge Sicherheitsmaßnahmen, um die Benutzeranmeldung zu schützen.
- Wenn du mehrere Apps hast, kannst du denselben Identitätsanbieter (Logto) verwenden. Sobald sich der Benutzer bei einer App anmeldet, wird Logto den Anmeldeprozess automatisch abschließen, wenn der Benutzer auf eine andere App zugreift.
Um mehr über die Gründe und Vorteile der umleitungsbasierten Anmeldung zu erfahren, siehe Logto-Anmeldeerfahrung erklärt.
In den folgenden Code-Snippets gehen wir davon aus, dass deine App unter http://localhost:3000/ läuft.
Redirect-URIs konfigurieren
Wechsle zur Anwendungsdetailseite der Logto-Konsole. Füge eine Redirect-URI http://localhost:3000/callback hinzu.
Genau wie beim Anmelden sollten Benutzer zu Logto weitergeleitet werden, um sich von der gemeinsamen Sitzung abzumelden. Sobald dies abgeschlossen ist, wäre es ideal, den Benutzer zurück zu deiner Website zu leiten. Füge zum Beispiel http://localhost:3000/ als Redirect-URI nach dem Abmelden hinzu.
Klicke dann auf "Speichern", um die Änderungen zu speichern.
Umgang mit Redirect
Es gibt noch Dinge zu tun, nachdem der Benutzer von Logto zurück zu deiner Anwendung umgeleitet wurde. Lass uns das richtig handhaben.
const callbackHandler = async (logtoClient) => {
await logtoClient.handleSignInCallback(window.location.href);
if (!logtoClient.isAuthenticated) {
// Fehlgeschlagene Anmeldung behandeln
alert('Anmeldung fehlgeschlagen');
return;
}
// Erfolgreiche Anmeldung behandeln
window.location.assign('/');
};
Implementierung von Anmeldung und Abmeldung
logtoClient bietet die Methoden signIn und signOut, um dir zu helfen, den Authentifizierungsablauf einfach zu verwalten.
Bevor du .signIn() aufrufst, stelle sicher, dass du die Redirect-URI im Admin Console korrekt konfiguriert hast.
const isAuthenticated = await logtoClient.isAuthenticated();
const onClickSignIn = () => {
logtoClient.signIn('http://localhost:3000/callback');
};
const onClickSignOut = () => {
logtoClient.signOut('http://localhost:3000');
};
const button = document.createElement('button');
button.innerHTML = isAuthenticated ? 'Abmelden' : 'Anmelden';
button.addEventListener('click', isAuthenticated ? onClickSignOut : onClickSignIn);
document.body.appendChild(button);
Das Aufrufen von .signOut() wird alle Logto-Daten im Speicher und im localStorage löschen, falls sie vorhanden sind.
Checkpoint: Teste deine Anwendung
Nun kannst du deine Anwendung testen:
- Starte deine Anwendung, du wirst den Anmeldebutton sehen.
- Klicke auf den Anmeldebutton, das SDK wird den Anmeldeprozess initiieren und dich zur Logto-Anmeldeseite weiterleiten.
- Nachdem du dich angemeldet hast, wirst du zurück zu deiner Anwendung geleitet und siehst die Benutzer-ID und den Abmeldebutton.
- Klicke auf den Abmeldebutton, um dich abzumelden.
Benutzerinformationen abrufen
Benutzerinformationen anzeigen
Um die Informationen des Benutzers anzuzeigen, kannst du die Methode logtoClient.getIdTokenClaims() verwenden. Zum Beispiel auf deiner Startseite:
const userInfo = await logtoClient.getIdTokenClaims();
// Anzeige-Tabelle für ID-Token-Ansprüche generieren
const table = document.createElement('table');
const thead = document.createElement('thead');
const tr = document.createElement('tr');
const thName = document.createElement('th');
const thValue = document.createElement('th');
thName.innerHTML = 'Name';
thValue.innerHTML = 'Wert';
tr.append(thName, thValue);
thead.append(tr);
table.append(thead);
const tbody = document.createElement('tbody');
for (const [key, value] of Object.entries(userInfo)) {
const tr = document.createElement('tr');
const tdName = document.createElement('td');
const tdValue = document.createElement('td');
tdName.innerHTML = key;
tdValue.innerHTML = typeof value === 'string' ? value : JSON.stringify(value);
tr.append(tdName, tdValue);
tbody.append(tr);
}
table.append(tbody);
Zusätzliche Ansprüche anfordern
Möglicherweise fehlen einige Benutzerinformationen im zurückgegebenen Objekt von getIdTokenClaims(). Dies liegt daran, dass OAuth 2.0 und OpenID Connect (OIDC) so konzipiert sind, dass sie dem Prinzip der minimalen Rechte (PoLP) folgen, und Logto auf diesen Standards basiert.
Standardmäßig werden begrenzte Ansprüche zurückgegeben. Wenn du mehr Informationen benötigst, kannst du zusätzliche Berechtigungen anfordern, um auf mehr Ansprüche zuzugreifen.
Ein "Anspruch (Claim)" ist eine Behauptung über ein Subjekt; eine "Berechtigung (Scope)" ist eine Gruppe von Ansprüchen. Im aktuellen Fall ist ein Anspruch ein Informationsstück über den Benutzer.
Hier ist ein nicht-normatives Beispiel für die Beziehung zwischen Berechtigung und Anspruch:
Der "sub"-Anspruch bedeutet "Subjekt", was der eindeutige Identifikator des Benutzers ist (d. h. Benutzer-ID).
Das Logto SDK wird immer drei Berechtigungen anfordern: openid, profile und offline_access.
Um zusätzliche Berechtigungen anzufordern, kannst du die Logto-Konfigurationen anpassen:
import LogtoClient, { UserScope } from '@logto/browser';
const logtoClient = new LogtoClient({
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: [UserScope.Email, UserScope.Phone],
});
Dann kannst du auf die zusätzlichen Ansprüche im Rückgabewert von logtoClient.getIdTokenClaims() zugreifen:
const claims = await getIdTokenClaims();
// Jetzt kannst du auf zusätzliche Ansprüche wie `claims.email`, `claims.phone` usw. zugreifen.
Ansprüche, die Netzwerk-Anfragen benötigen
Um das ID-Token nicht aufzublähen, erfordern einige Ansprüche Netzwerk-Anfragen, um abgerufen zu werden. Zum Beispiel ist der custom_data Anspruch nicht im Benutzerobjekt enthalten, selbst wenn er in den Berechtigungen angefordert wird. Um auf diese Ansprüche zuzugreifen, kannst du die logtoClient.fetchUserInfo() Methode verwenden:
const userInfo = await logtoClient.fetchUserInfo();
// Jetzt kannst du auf den Anspruch `userInfo.custom_data` zugreifen.
Berechtigungen und Ansprüche
Logto verwendet OIDC Berechtigungen und Ansprüche Konventionen, um die Berechtigungen und Ansprüche für das Abrufen von Benutzerinformationen aus dem ID-Token und dem OIDC userinfo endpoint zu definieren. Sowohl "Berechtigung (Scope)" als auch "Anspruch (Claim)" sind Begriffe aus den OAuth 2.0 und OpenID Connect (OIDC) Spezifikationen.
Hier ist die Liste der unterstützten Berechtigungen (Scopes) und der entsprechenden Ansprüche (Claims):
openid
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
| sub | string | Der eindeutige Identifikator des Benutzers | Nein |
profile
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
| name | string | Der vollständige Name des Benutzers | Nein |
| username | string | Der Benutzername des Benutzers | Nein |
| picture | string | URL des Profilbildes des Endbenutzers. Diese URL MUSS auf eine Bilddatei (zum Beispiel eine PNG-, JPEG- oder GIF-Bilddatei) verweisen und nicht auf eine Webseite, die ein Bild enthält. Beachte, dass diese URL speziell auf ein Profilfoto des Endbenutzers verweisen SOLLTE, das geeignet ist, den Endbenutzer zu beschreiben, und nicht auf ein beliebiges Foto, das vom Endbenutzer aufgenommen wurde. | Nein |
| created_at | number | Zeitpunkt, zu dem der Endbenutzer erstellt wurde. Die Zeit wird als Anzahl der Millisekunden seit der Unix-Epoche (1970-01-01T00:00:00Z) dargestellt. | Nein |
| updated_at | number | Zeitpunkt, zu dem die Informationen des Endbenutzers zuletzt aktualisiert wurden. Die Zeit wird als Anzahl der Millisekunden seit der Unix-Epoche (1970-01-01T00:00:00Z) dargestellt. | Nein |
Andere Standardansprüche wie family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo und locale werden ebenfalls im profile-Scope enthalten sein, ohne dass der userinfo-Endpunkt angefordert werden muss. Ein Unterschied im Vergleich zu den oben genannten Ansprüchen besteht darin, dass diese Ansprüche nur zurückgegeben werden, wenn ihre Werte nicht leer sind, während die oben genannten Ansprüche null zurückgeben, wenn die Werte leer sind.
Im Gegensatz zu den Standardansprüchen verwenden die Ansprüche created_at und updated_at Millisekunden anstelle von Sekunden.
email
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
string | Die E-Mail-Adresse des Benutzers | Nein | |
| email_verified | boolean | Ob die E-Mail-Adresse verifiziert wurde | Nein |
phone
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
| phone_number | string | Die Telefonnummer des Benutzers | Nein |
| phone_number_verified | boolean | Ob die Telefonnummer verifiziert wurde | Nein |
address
Bitte siehe OpenID Connect Core 1.0 für die Details des Adressanspruchs.
custom_data
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
| custom_data | object | Die benutzerdefinierten Daten des Benutzers | Ja |
identities
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
| identities | object | Die verknüpften Identitäten des Benutzers | Ja |
| sso_identities | array | Die verknüpften SSO-Identitäten des Benutzers | Ja |
urn:logto:scope:organizations
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
| organizations | string[] | Die Organisations-IDs, denen der Benutzer angehört | Nein |
| organization_data | object[] | Die Organisationsdaten, denen der Benutzer angehört | Ja |
urn:logto:scope:organization_roles
| Anspruchsname | Typ | Beschreibung | Benötigt userinfo? |
|---|---|---|---|
| organization_roles | string[] | Die Organisationsrollen, denen der Benutzer angehört, im Format <organization_id>:<role_name> | Nein |
In Anbetracht der Leistung und der Datengröße bedeutet "Benötigt userinfo?" "Ja", dass der Anspruch nicht im ID-Token angezeigt wird, sondern in der Antwort des userinfo-Endpunkts zurückgegeben wird.
API-Ressourcen
Wir empfehlen, zuerst 🔐 Rollenbasierte Zugangskontrolle (RBAC) zu lesen, um die grundlegenden Konzepte von Logto RBAC zu verstehen und wie man API-Ressourcen richtig einrichtet.
Logto-Client konfigurieren
Sobald du die API-Ressourcen eingerichtet hast, kannst du sie bei der Konfiguration von Logto in deiner App hinzufügen:
import LogtoClient from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // API-Ressourcen hinzufügen
});
Jede API-Ressource hat ihre eigenen Berechtigungen (Berechtigungen).
Zum Beispiel hat die Ressource https://shopping.your-app.com/api die Berechtigungen shopping:read und shopping:write, und die Ressource https://store.your-app.com/api hat die Berechtigungen store:read und store:write.
Um diese Berechtigungen anzufordern, kannst du sie bei der Konfiguration von Logto in deiner App hinzufügen:
import LogtoClient from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // API-Ressourcen hinzufügen
});
Du wirst bemerken, dass Berechtigungen separat von API-Ressourcen definiert sind. Dies liegt daran, dass Resource Indicators for OAuth 2.0 spezifiziert, dass die endgültigen Berechtigungen für die Anfrage das kartesische Produkt aller Berechtigungen bei allen Zielservices sein werden.
Somit können im obigen Fall die Berechtigungen aus der Definition in Logto vereinfacht werden, beide API-Ressourcen können read und write Berechtigungen ohne Präfix haben. Dann, in der Logto-Konfiguration:
import LogtoClient, { UserScope } from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
scopes: ['read', 'write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
});
Für jede API-Ressource wird sowohl read als auch write Berechtigungen angefordert.
Es ist in Ordnung, Berechtigungen anzufordern, die in den API-Ressourcen nicht definiert sind. Zum Beispiel kannst du die Berechtigung email anfordern, auch wenn die API-Ressourcen die Berechtigung email nicht verfügbar haben. Nicht verfügbare Berechtigungen werden sicher ignoriert.
Nach der erfolgreichen Anmeldung wird Logto die entsprechenden Berechtigungen an API-Ressourcen gemäß den Rollen des Benutzers ausstellen.
Zugangstoken für die API-Ressource abrufen
Um das Zugangstoken für eine spezifische API-Ressource abzurufen, kannst du die Methode getAccessToken verwenden:
const accessToken = await logtoClient.getAccessToken('https://store.your-app.com/api');
console.log('Zugangstoken', accessToken);
Diese Methode gibt ein JWT-Zugangstoken zurück, das verwendet werden kann, um auf die API-Ressource zuzugreifen, wenn der Benutzer die entsprechenden Berechtigungen hat. Wenn das aktuell zwischengespeicherte Zugangstoken abgelaufen ist, versucht diese Methode automatisch, ein Auffrischungstoken zu verwenden, um ein neues Zugangstoken zu erhalten.
Organisationstokens abrufen
Wenn Organisationen neu für dich sind, lies bitte 🏢 Organisationen (Multi-Tenancy), um loszulegen.
Du musst die Berechtigung UserScope.Organizations hinzufügen, wenn du den Logto-Client konfigurierst:
import LogtoClient, { UserScope } from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
scopes: [UserScope.Organizations],
});
Sobald der Benutzer angemeldet ist, kannst du das Organisationstoken für den Benutzer abrufen:
// Holen Sie sich organizationIds aus den userInfo
const claims = await logtoClient.getIdTokenClaims();
const organizationIds = claims.organizations;
/**
* Oder aus den ID-Token-Ansprüchen
*
* const claims = await logtoClient.getIdTokenClaims();
* const organizationIds = claims.organizations;
*/
// Holen Sie sich das Organisationstoken
if (organizationIds.length > 0) {
const organizationId = organizationIds[0];
const organizationAccessToken = await logtoClient.getOrganizationToken(organizationId);
console.log('Organisationstoken', organizationAccessToken);
}
./code/_scopes-and-claims-code.mdx./code/_config-organization-code.mdx
Zugangstoken an Anfrage-Header anhängen
Platziere das Token im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN), und du bist startklar.
Der Integrationsablauf des Bearer-Tokens kann je nach verwendetem Framework oder Anfrager variieren. Wähle deinen eigenen Weg, um den Anfrage-Authorization-Header anzuwenden.