Zum Hauptinhalt springen

Interaktion mit der Management API

Was ist die Logto Management API?​

Die Logto Management API ist eine umfassende Sammlung von APIs, die Entwicklern die volle Kontrolle über ihre Implementierung gibt, um ihre Produktanforderungen und ihren Technologie-Stack zu erfüllen. Sie ist vorgefertigt, in der API-Ressourcenliste in der Logto-Konsole aufgeführt und kann nicht gelöscht oder geändert werden.

Ihr Bezeichner hat das Muster https://[tenant-id].logto.app/api

Logto Management API Resource Logto Management API Details

Mit der Logto Management API kannst du auf die robusten Backend-Dienste von Logto zugreifen, die hoch skalierbar sind und in einer Vielzahl von Szenarien genutzt werden können. Sie geht über das hinaus, was mit den Low-Code-Fähigkeiten der Admin-Konsole möglich ist.

Einige häufig verwendete APIs sind unten aufgeführt:

  • Benutzer
  • Anwendung
  • Protokolle
  • Rollen
  • Ressourcen
  • Connectors
  • Organisationen

Um mehr über die verfügbaren APIs zu erfahren, besuche bitte https://openapi.logto.io/.

Wie man auf die Logto Management API zugreift​

Erstelle eine M2M-App​

hinweis

Wenn du mit dem M2M (Maschine-zu-Maschine) Authentifizierungsfluss nicht vertraut bist, empfehlen wir, zuerst Verständnis des Authentifizierungsflusses zu lesen, um die grundlegenden Konzepte zu verstehen.

Gehe zu Konsole > Anwendungen, wähle den M2M-App-Typ und starte den Erstellungsprozess.

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

M2M-Rollen zuweisen Modal

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

M2M-Rollen Seite zuweisen

Im Rollenzuweisungsmodul kannst du sehen, dass alle M2M-Rollen enthalten sind, und Rollen, die durch ein Logto-Symbol angezeigt werden, bedeuten, dass diese Rollen Logto Management API-Berechtigungen enthalten.

Weise nun M2M-Rollen zu, die Logto Management API-Berechtigungen für deine M2M-App enthalten.

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:

App ID und App-Geheimnis

Zugangstoken für die Logto Management API abrufen​

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.

Logto Management API Details

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:

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 benutzerdefinierte Domain verwenden, sondern den Standard-Logto-Endpunkt https://{your_tenant_id}.logto.app/oidc/token, um Zugangstokens zu gewähren.

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

Zugriff auf die Logto Management API 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.

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:

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

Typische Szenarien für die Nutzung der Logto Management API​

Unsere Entwickler haben viele zusätzliche Funktionen mit der Logto Management API implementiert. Wir glauben, dass unsere API hoch skalierbar ist und eine breite Palette deiner Bedürfnisse unterstützen kann. Hier sind einige Beispiele für Szenarien, die mit der Logto Admin-Konsole nicht möglich sind, aber durch die Logto Management API erreicht werden können.

Benutzerprofil selbst implementieren​

Logto bietet derzeit keine vorgefertigte UI-Lösung für Benutzerprofile. Wir erkennen an, dass Benutzerprofile eng mit Geschäfts- und Produktattributen verbunden sind. Während wir daran arbeiten, den besten Ansatz zu bestimmen, empfehlen wir, unsere APIs zu verwenden, um deine eigene Lösung zu erstellen. Beispielsweise kannst du unsere Interaktions-API, Profil-API und Verifizierungscode-API nutzen, um eine benutzerdefinierte Lösung zu entwickeln, die deinen Anforderungen entspricht.

Erweiterte Benutzersuche​

Die Logto Admin-Konsole unterstützt grundlegende Such- und Filterfunktionen. Für erweiterte Suchoptionen wie unscharfe Suche, exakte Übereinstimmung und Groß-/Kleinschreibung, schaue dir unsere Erweiterte Benutzersuche Tutorials und Anleitungen an.

Organisationsverwaltung selbst implementieren​

Wenn du die Organisationen Funktion nutzt, um deine Multi-Tenant-App zu erstellen, benötigst du möglicherweise die Logto Management API für Aufgaben wie Organisationseinladungen und Mitgliederverwaltung. Für dein SaaS-Produkt, bei dem du sowohl Administratoren als auch Mitglieder im Mandanten hast, kann die Logto Management API dir helfen, ein benutzerdefiniertes Admin-Portal zu erstellen, das auf deine Geschäftsanforderungen zugeschnitten ist. Schaue dir dies für mehr Details an.

Tipps zur Nutzung der Logto Management API​

Verwaltung von paginierten API-Antworten​

Einige der API-Antworten können viele Ergebnisse enthalten, die Ergebnisse werden paginiert. Logto bietet 2 Arten von Paginierungsinformationen.

Ein paginierter Antwort-Header sieht folgendermaßen aus:

Link: <https://logto.dev/users?page=1&page_size=20>; rel="first"

Der Link-Header bietet die URL für die vorherige, nächste, erste und letzte Seite der Ergebnisse:

  • Die URL für die vorherige Seite folgt auf rel="prev".
  • Die URL für die nächste Seite folgt auf rel="next".
  • Die URL für die letzte Seite folgt auf rel="last".
  • Die URL für die erste Seite folgt auf rel="first".

Verwendung des Total-Number-Headers​

Zusätzlich zu den Standard-Link-Headern wird Logto auch einen Total-Number Header hinzufügen:

Total-Number: 216

Das wäre sehr praktisch und nützlich, um Seitennummern anzuzeigen.

Ändern der Seitennummer und Seitengröße​

Es gibt 2 optionale Abfrageparameter:

  • page: gibt die Seitennummer an, beginnt bei 1, der Standardwert ist 1.
  • page_size: gibt die Anzahl der Elemente pro Seite an, der Standardwert ist 20.

Ratenbegrenzung​

hinweis

Dies gilt nur für Logto Cloud.

Um die Zuverlässigkeit und Sicherheit unserer Dienste für alle Benutzer zu gewährleisten, setzen wir eine allgemeine Firewall ein, die den Datenverkehr zu unserer Website überwacht und verwaltet. Obwohl wir keine strikte Ratenbegrenzung durchsetzen, empfehlen wir den Benutzern, ihre Aktivität auf etwa 200 Anfragen alle 10 Sekunden zu beschränken, um unsere Schutzmaßnahmen nicht auszulösen.