Utilizzare l'API di gestione di Logto: Una guida passo-passo

Mentre Logto fornisce una Console basata sul web per gestire le identità, l'utilizzo dell'API di gestione è un'alternativa potente quando si vuole automatizzare il flusso di lavoro o accedere a Logto a livello programmatico. Questa guida ti guiderà attraverso i passi per utilizzare l'API di gestione di Logto in diversi scenari.

Panoramica#

Potresti notare che c'è una risorsa API integrata "Logto Management API" nella Console di Logto. Sarà il ruolo chiave in questa guida.

Rispetto ad altre risorse API, attualmente l'API di gestione di Logto non consente l'accesso diretto da parte degli utenti finali perché è progettata per la comunicazione macchina-a-macchina, ed è così potente che può essere utilizzata per gestire il tuo account Logto e le risorse.

Ecco alcuni scenari tipici in cui potresti voler utilizzare l'API di gestione di Logto:

CI/CD

Comunicazione di servizio

App a pagina singola

Web server che rende HTML

Architettura#

Indipendentemente dagli scenari, ci sono due modelli che puoi utilizzare per accedere all'API di gestione di Logto.

Modello 1: Accesso diretto

In questo modello, il tuo client o servizio accederà direttamente all'API di gestione di Logto. In Logto, il client o servizio è chiamato app "macchina-a-macchina".

Un esempio di utilizzo di servizio backend:

Modello 2: Accesso indiretto

In questo modello, il tuo client o servizio accederà all'API di gestione di Logto tramite un servizio backend. Il modello 2 è costruito sopra il modello 1, che coinvolge un'altra app. La nuova app può essere un'app tradizionale web, nativa, o a pagina singola che accederà al servizio backend.

Un esempio di utilizzo di un'app a pagina singola:

Questo modello è utile quando vuoi avere una logica personalizzata per controllare l'accesso all'API di gestione di Logto. Ad esempio, potresti voler restituire tutti gli ordini per un consumatore e allegare le informazioni del venditore a ciascun ordine. In questo caso, puoi utilizzare l'app a pagina singola per richiedere al servizio backend di ottenere gli ordini, e nel servizio backend puoi utilizzare l'API di gestione di Logto per ottenere le informazioni del venditore.

Accedere all'API di gestione di Logto#

Crea un'app macchina-a-macchina#

Per prima cosa, devi creare un'app macchina-a-macchina nella Console di Logto. Vai alla scheda "Applicazioni" e clicca sul pulsante "Crea applicazione". Quindi clicca su "Inizia a costruire" nella scheda "Macchina-a-macchina".

Imposta un ruolo macchina-a-macchina#

Per accedere all'API di gestione di Logto, devi creare un ruolo macchina-a-macchina con le autorizzazioni adeguate. Nella Console di Logto, vai alla scheda "Ruoli" e clicca sul pulsante "Crea ruolo". Clicca su "Mostra più opzioni" e seleziona "Ruolo app macchina-a-macchina" nella sezione "Tipo di ruolo".

Ora puoi vedere che "API di gestione di Logto" appare nella sezione "Assegna autorizzazioni". Seleziona la risorsa API per tutte le autorizzazioni e clicca sul pulsante "Crea ruolo".

Una volta creato il ruolo, puoi assegnarlo all'app macchina-a-macchina che hai creato nel passaggio precedente.

Ottieni il token di accesso#

Puoi seguire i passaggi in questo articolo per ottenere un token di accesso tramite il grant delle credenziali del client per la tua app macchina-a-macchina. Testa il token di accesso inviando una richiesta a un endpoint nell'API di gestione di Logto.

Ora sei pronto per il modello 1. Nota che il token di accesso è valido per un breve periodo di tempo, quindi potresti volerlo aggiornare periodicamente se desideri archiviarlo nella cache.

Aggiungere un altro strato#

Anche se l'accesso all'API di gestione di Logto non è consentito per gli utenti finali, puoi aggiungere un altro strato per sfruttare la potenza dell'API di gestione di Logto e lasciare che potenzi il tuo servizio.

Ad esempio, stai costruendo una comunità online con un'app a pagina singola e un servizio backend. Potresti voler avere una funzione che consente agli utenti registrati di vedere i primi 10 utenti che hanno più follower. Un endpoint GET /api/top-users sarà creato:

Per garantire che l'endpoint sia accessibile solo dagli utenti registrati, puoi creare un'app "pagina singola" nella Console di Logto e integrare Logto SDK in quell'app. Quindi puoi utilizzare l'SDK per ottenere il token di accesso e inviare la richiesta all'endpoint:

Nel servizio backend, puoi prima interrogare i primi 10 utenti dal database, e poi utilizzare l'API di gestione di Logto per ottenere le informazioni dell'utente:

Infine, puoi restituire la risposta all'app a pagina singola:

Un diagramma di sequenza completo:

In questo flusso, sono coinvolti due tipi di token di accesso: uno per il servizio backend per accedere all'API di gestione di Logto e l'altro per l'app a pagina singola per accedere al servizio backend.

Il primo token di accesso è quello ottenuto nella sezione precedente. Il secondo token di accesso è quello che puoi ottenere da Logto SDK.

Il mio token di accesso nell'app a pagina singola non è un JSON Web Token (JWT)

Se non specifichi la risorsa quando chiami il metodo getAccessToken nei Logto SDKs, il token di accesso sarà una stringa opaca che è destinata ad essere usata per l'endpoint delle informazioni utente. Per ottenere un JWT:

1. Definisci una risorsa API nella Console di Logto, ad esempio https://api.example.com.
2. Aggiungi la risorsa API alla configurazione resources di Logto SDK, ad esempio resources: ['https://api.example.com'].
3. Chiama il metodo getAccessToken con la risorsa API, ad esempio getAccessToken('https://api.example.com').

Per convalidare il JWT nel tuo servizio backend, si prega di fare riferimento a Convalida del token di autorizzazione della richiesta API.

Cosa implica il JWT nell'app a pagina singola?

Il JWT implica solo che l'utente ha effettuato l'accesso e tenta di accedere alla risorsa API. Non implica che l'utente abbia permessi specifici della risorsa API. Sta a te decidere se concedere all'utente l'accesso alla risorsa API.

Se hai bisogno di un controllo di accesso più granulare, puoi anche applicare il controllo degli accessi basato sui ruoli (RBAC) all'utente. Vedi 🔐 Controllo degli accessi basato sui ruoli (RBAC) per i dettagli.

Note finali#

L'API di gestione di Logto è potente e flessibile per molteplici scenari. Con l'aiuto dei protocolli standard, puoi facilmente integrare l'API di gestione di Logto nella tua applicazione e costruire un sistema sicuro e scalabile. Se hai domande, non esitare a contattarci.