Maschine-zu-Maschine: Auth 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 hast (nicht Benutzer), die direkt mit Ressourcen kommunizieren muss (normalerweise benötigt die M2M-App keine Benutzerinteraktionen, daher hat sie keine Benutzeroberfläche). Zum Beispiel ein API-Dienst, der benutzerdefinierte Daten in Logto aktualisiert, ein Statistikdienst, der tägliche Bestellungen abruft, usw.

Da Logto RBAC als Zugangskontrollrichtlinie verwendet, ist es notwendig, M2M-Rollen an M2M-Apps zuzuweisen, um deine API zu schützen, die direkte Dienstkommunikation benötigt.

info

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

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

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

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

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

Nun gehen wir 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.

Ein 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 die 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

Ein Zugangstoken anfordern

hinweis

Ersetze in der folgenden Demonstration https://your.logto.endpoint durch den Logto-Endpunkt, den du anvisierst. Für Logto Cloud wird es https://{your-tenant-id}.logto.app sein.

Für Logto Management API
Für deine API-Ressource

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
cURL

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

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

Angenommen, wir haben read:products und write:products Berechtigungen 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 von deiner API-Ressource enthalten.

Nun, setze alles zusammen und sende die Anfrage:

Node.js
cURL

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

Ein erfolgreicher Antwortkörper für den Zugang wäre wie folgt:

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

Ressourcenzugriff mit Zugangstoken

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
Interaktion mit deiner API-Ressource

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
cURL

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

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

Node.js
cURL

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 --location \
  --request GET 'https://your.api.endpoint/products' \
  --header 'Authorization: Bearer eyJhbG...2 # Zugangstoken

Authentifizierung

Wenn du deine eigenen API-Ressourcen außer der Logto Management API schützt, denke daran, die Authentifizierung für deine Ressource zu implementieren. Siehe Schütze deine API für Details.

Einführung​

Ein Zugangstoken abrufen​

Grundlagen zur Zugangstoken-Anfrage​

Ein Zugangstoken anfordern​

Zugangstoken-Antwort​

Ressourcenzugriff mit Zugangstoken​

Authentifizierung​

Einführung

Ein Zugangstoken abrufen

Grundlagen zur Zugangstoken-Anfrage

Ein Zugangstoken anfordern

Zugangstoken-Antwort

Ressourcenzugriff mit Zugangstoken

Authentifizierung