Maschine-zu-Maschine: Authentifizierung mit Logto

hinweis:

Diese Anleitung geht davon aus, dass du eine Anwendung des Typs "Maschine-zu-Maschine" in der Admin-Konsole erstellt hast.

Einführung

Maschine-zu-Maschine (M2M) ist eine gängige Praxis zur Authentifizierung, wenn du eine App (kein Benutzer) hast, die direkt mit Ressourcen kommunizieren muss (in der Regel benötigt eine M2M-App keine Benutzerinteraktionen und hat daher keine Benutzeroberfläche). Zum Beispiel ein API-Dienst, der benutzerdefinierte Daten von Benutzern in Logto aktualisiert, ein Statistikdienst, der tägliche Bestellungen abruft usw.

Da Logto rollenbasierte Zugangskontrolle (RBAC) als Zugriffsrichtlinie verwendet, ist es notwendig, M2M-Rollen an M2M-Apps zuzuweisen, um deine API zu schützen, die einen direkten Dienstzugriff benötigt.

info:

Um mehr über unser aktuelles RBAC und den Unterschied zwischen Benutzerrolle und M2M-Rolle zu erfahren, siehe Globale Rollen konfigurieren.

Es gibt zwei häufige Anwendungsfälle für den Einsatz von Maschine-zu-Maschine-Apps in Logto:

1. Zugriff auf die Logto Management API: In diesem Fall musst du deiner M2M-App eine M2M-Rolle zuweisen, die die all-Berechtigung aus der integrierten Logto Management API enthält.
2. Zugriff auf deine API-Ressource: In diesem Fall musst du deiner M2M-App M2M-Rollen zuweisen, die Berechtigungen aus deinen API-Ressourcen enthalten.

Während des Erstellungsprozesses einer M2M-Anwendung wirst du zu einer Seite weitergeleitet, auf der du M2M-Rollen deinen Anwendungen zuweisen kannst:

Alternativ kannst du diese Rollen auch auf der Detailseite der M2M-Anwendung zuweisen, wenn du bereits eine M2M-Anwendung erstellt hast:

Gehen wir nun den End-to-End-Prozess durch. Zur Klarheit trennen wir die Schritte für den Zugriff auf die Logto Management API und andere API-Ressourcen. Wir gehen davon aus, dass du bereits eine M2M-App in Logto erstellt hast.

Zugangstoken abrufen

Grundlagen zur Zugangstoken-Anfrage

Die M2M-Anwendung macht eine POST-Anfrage an den Token-Endpunkt, um ein Zugangstoken zu erhalten, indem sie die folgenden Parameter im Format application/x-www-form-urlencoded im HTTP-Anfrage-Entity-Body hinzufügt:

• grant_type: Muss auf client_credentials gesetzt werden
• resource: Die Ressource, auf die du zugreifen möchtest
• scope: Die Berechtigung der Zugriffsanfrage

Außerdem musst du die Anmeldeinformationen deiner M2M-Anwendung im Anforderungsheader einfügen, damit der Token-Endpunkt deine M2M-Anwendung authentifizieren kann.

Dies wird erreicht, indem die Anmeldeinformationen der Anwendung im Basic Authentication-Format im Anforderungsheader Authorization eingefügt werden, wobei der Benutzername die App-ID und das Passwort das App-Geheimnis ist.

Du findest die App-ID und das App-Geheimnis auf der Detailseite deiner M2M-Anwendung:

Ein Beispiel für eine Zugangstoken-Anfrage ist:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&resource=https://shopping.api
&scope=read:products write:products

Zugangstoken anfordern

hinweis:

Ersetze in der folgenden Demonstration https://your.logto.endpoint durch den Logto-Endpunkt, den du ansprechen möchtest. Für Logto Cloud ist dies https://{your-tenant-id}.logto.app.

Für Logto Management API

Logto stellt eine integrierte „Logto Management API“-Ressource bereit. Es handelt sich um eine schreibgeschützte Ressource mit der Berechtigung all, um auf die Logto Management API zuzugreifen. Du findest sie in deiner API-Ressourcenliste. Der Ressourcen-API-Indikator folgt dem Muster https://{your-tenant-id}.logto.app/api und dies ist der Wert, den du im Zugangstoken-Anfrage-Body als Ressource verwendest.

Bevor du auf die Logto Management API zugreifst, stelle sicher, dass deiner M2M-App M2M-Rollen zugewiesen wurden, die die Berechtigung all aus dieser integrierten „Logto Management API“-Ressource enthalten.

info:

Logto stellt außerdem eine vorkonfigurierte „Logto Management API access“-M2M-Rolle für neu erstellte Mandanten bereit, der die Berechtigung all der Logto Management API-Ressource bereits zugewiesen ist. Du kannst sie direkt verwenden, ohne Berechtigungen manuell festzulegen. Diese vorkonfigurierte Rolle kann bei Bedarf auch bearbeitet und gelöscht werden.

Jetzt fasse alles zusammen und sende die Anfrage:

info:

Seit Version v1.30.1 stellt Logto ein offizielles @logto/api Node.js SDK bereit, das dir hilft, einfach mit der Logto Management API zu interagieren.

Node.js mit `@logto/api` SDK

Logto Cloud

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// Oder du kannst sogar das Abrufen des Zugangstokens überspringen und direkt API-Aufrufe machen
const response = await apiClient.GET('/api/users');
console.log(response.data);

Self-hosted / OSS

OSS-Nutzer sollten default als Tenant-ID verwenden und zusätzlich baseUrl und apiIndicator konfigurieren.

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

Node.js

const logtoEndpoint = 'https://your.logto.endpoint'; // Ersetze durch deinen Logto-Endpunkt
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};

vorsicht:

Für Logto Cloud-Nutzer: Wenn du mit der Logto Management API interagierst, kannst du keine eigene Domain verwenden. Nutze den Standard-Logto-Endpunkt https://{your_tenant_id}.logto.app/oidc/token, um Zugangstokens zu erhalten.

Zugangstoken-Antwort (Access token response)

Ein erfolgreicher Antwort-Body für das Zugangstoken sieht wie folgt aus:

{
  "access_token": "eyJhbG...2g", // Verwende dieses Token für den Zugriff auf die Logto Management API
  "expires_in": 3600, // Token-Ablaufzeit in Sekunden
  "token_type": "Bearer", // Authentifizierungstyp für deine Anfrage bei Verwendung des Zugangstokens
  "scope": "all" // Berechtigung `all` für die Logto Management API
}

hinweis:

Logto unterstützt derzeit nicht, dass die M2M-App einen Benutzer repräsentiert. Das sub im Zugangstoken-Payload wird die App-ID sein.

cURL

curl --location \
  --request POST 'https://your.logto.endpoint' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
  --data-urlencode 'scope=all'

Denke daran, die Platzhalter durch deine eigenen Werte zu ersetzen.

vorsicht:

Für Logto Cloud-Nutzer: Wenn du mit der Logto Management API interagierst, kannst du keine eigene Domain verwenden. Nutze den Standard-Logto-Endpunkt https://{your_tenant_id}.logto.app/oidc/token, um Zugangstokens zu erhalten.

Zugangstoken-Antwort (Access token response)

Ein erfolgreicher Antwort-Body für das Zugangstoken sieht wie folgt aus:

{
  "access_token": "eyJhbG...2g", // Verwende dieses Token für den Zugriff auf die Logto Management API
  "expires_in": 3600, // Token-Ablaufzeit in Sekunden
  "token_type": "Bearer", // Authentifizierungstyp für deine Anfrage bei Verwendung des Zugangstokens
  "scope": "all" // Berechtigung `all` für die Logto Management API
}

hinweis:

Logto unterstützt derzeit nicht, dass die M2M-App einen Benutzer repräsentiert. Das sub im Zugangstoken-Payload wird die App-ID sein.

Für deine API-Ressource

In deiner API-Ressourcenliste findest du den API-Identifier, auf den die App zugreifen muss. Falls du die API-Ressource in Logto noch nicht hinzugefügt hast oder nicht weißt, was eine API-Ressource ist, siehe Autorisierung.

Angenommen, wir haben die Berechtigungen read:products und write:products unter dieser „Online Shopping“-API-Ressource.

Bevor du auf deine API-Ressource zugreifst, stelle sicher, dass deiner M2M-App M2M-Rollen zugewiesen wurden, die Berechtigungen aus deiner API-Ressource enthalten.

Jetzt fasse alles zusammen und sende die Anfrage:

Node.js

const logtoEndpoint = 'https://your.logto.endpoint';
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: 'https://shopping.api',
      scope: 'read:products write:products',
    }).toString(),
  });
};

cURL

curl --location \
  --request POST 'https://your.logto.endpoint/oidc/token' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://shopping.api' \
  --data-urlencode 'scope=read:products write:products'

Zugangstoken-Antwort

Eine erfolgreiche Antwort auf die Zugangsanfrage sieht wie folgt aus:

{
  "access_token": "eyJhbG...2g", // Verwende dieses Token für den Zugriff auf die Logto Management API
  "expires_in": 3600, // Token-Gültigkeit in Sekunden
  "token_type": "Bearer", // Authentifizierungstyp für deine Anfrage beim Verwenden des Zugangstokens
  "scope": "all" // scope `all` für Logto Management API
}

hinweis:

Logto unterstützt derzeit nicht, dass die M2M-App einen Benutzer repräsentiert. Das sub im Zugangstoken-Payload wird die App-ID sein.

Ressource mit Zugangstoken aufrufen

Du wirst bemerken, dass die Token-Antwort ein token_type-Feld hat, das auf Bearer festgelegt ist.

Daher solltest du das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) platzieren, wenn du mit deinem API-Ressourcenserver interagierst.

Interaktion mit Logto Management API

Node.js mit `@logto/api` SDK

Mit dem @logto/api SDK kannst du direkt mit jeder Management API interagieren, indem du den folgenden Codeausschnitt verwendest. Das Zugangstoken (Access token) wird intern zwischengespeichert und bei Bedarf automatisch aktualisiert.

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

Node.js

Du wirst bemerken, dass die Token-Antwort ein token_type-Feld hat, das auf Bearer festgelegt ist.

Daher solltest du das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) platzieren, wenn du mit deinem API-Ressourcenserver interagierst.

const logtoEndpoint = 'https://your.logto.endpoint'; // Ersetze durch deinen Logto-Endpunkt
const accessToken = 'eyJhb...2g'; // Zugangstoken (Access token)

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

cURL

Du wirst bemerken, dass die Token-Antwort ein token_type-Feld hat, das auf Bearer festgelegt ist.

Daher solltest du das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) platzieren, wenn du mit deinem API-Ressourcenserver interagierst.

curl --location \
  --request GET 'https://your.logto.endpoint/api/applications' \
  --header 'Authorization: Bearer eyJhbG...2g'

Denke daran, die tatsächlichen Werte durch deine eigenen zu ersetzen. Der Wert nach Bearer sollte das Zugangstoken (Access token) (JWT) sein, das du erhalten hast.

Interaktion mit deiner API-Ressource

Verwende das angeforderte Zugangstoken mit der API-Ressource https://shopping.api, um alle Produkte in der Shopping-API abzurufen:

Node.js

const apiEndpoint = 'https://your.api.endpoint';
const accessToken = 'eyJhb...2g'; // Zugangstoken

const fetchProducts = async () => {
  return await fetch(`${apiEndpoint}/products`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

cURL

curl --location \
  --request GET 'https://your.api.endpoint/products' \
  --header 'Authorization: Bearer eyJhbG...2 # Zugangstoken

Autorisierung

Wenn du eigene API-Ressourcen (außer Logto Management API) schützt, musst du die Autorisierungslogik in deinem API-Dienst implementieren, um das Zugangstoken zu überprüfen und zu prüfen, ob die M2M-App die erforderlichen Berechtigungen für den Zugriff auf die Ressource besitzt.

Für weitere Details siehe Autorisierung und Zugangstokens validieren.