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 bietet eine eingebaute Ressource „Logto Management API“, es ist eine schreibgeschützte Ressource mit der Berechtigung all, um auf die Logto Management API zuzugreifen. Du kannst sie in deiner Liste der API-Ressourcen sehen. Der Ressourcen-API-Indikator hat das Muster https://{your-tenant-id}.logto.app/api und dies wird dein Ressourcenwert sein, der im Zugangstoken-Anfragekörper verwendet wird.

Bevor du auf die Logto Management API zugreifst, stelle sicher, dass deine M2M-App mit M2M-Rollen zugewiesen wurde, die die Berechtigung all von dieser eingebauten „Logto Management API“-Ressource enthalten.

info:

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

Nun, setze alles zusammen und sende die Anfrage:

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(),
  });
};

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 tatsächlichen Werte durch deine eigenen zu ersetzen.

vorsicht:

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

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

Verwenden des angeforderten Zugangstokens mit der integrierten Logto Management API-Ressource https://[your-tenant-id].logto.app/api, um alle Anwendungen in Logto zu erhalten:

Node.js

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

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

cURL

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