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** ```mermaid graph LR CI(Job di integrazione continua) <-->|Crea un nuovo utente| L(API di gestione di Logto) ``` **Comunicazione di servizio** ```mermaid graph LR B(Servizio backend) <-->|Cerca utenti| L(API di gestione di Logto) ``` **App a pagina singola** ```mermaid graph LR F(Frontend) -->|1 Elenca ordini| B(Servizio backend) B <-->|2 Trova ordini| D(Database) B <-->|3 Cerca utenti correlati agli ordini| L(API di gestione di Logto) B -->|4 Risposta combinata| F ``` **Web server che rende HTML** ```mermaid graph LR W(Web server) <-->|Cerca utenti| L(API di gestione di Logto) ``` ## 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: ```mermaid graph LR B(Servizio backend) <-->|Usando le credenziali del client| L(API di gestione di Logto) ``` **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: ```mermaid graph LR S(App a pagina singola) -->|Richiesta con token di accesso| B(Servizio backend) <-->|Usando le credenziali del client| L(API di gestione di Logto) B -->|Risposta con dati| S ``` 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. Attualmente l'API di gestione di Logto ha solo un permesso all che consente tutte le operazioni. Stiamo lavorando per aggiungere autorizzazioni più granulari. ### Ottieni il token di accesso Puoi seguire i passaggi in [questo articolo](https://docs.logto.io/docs/recipes/integrate-logto/machine-to-machine/) 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: ```mermaid graph LR S(App a pagina singola) --> E(GET /api/top-users) subgraph Servizio backend E end ``` 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](https://docs.logto.io/docs/recipes/integrate-logto/) in quell'app. Quindi puoi utilizzare l'SDK per ottenere il token di accesso e inviare la richiesta all'endpoint: ```mermaid graph LR S(App a pagina singola) -->|1 Richiesta con token di accesso| E(GET /api/top-users) subgraph Servizio backend E end ``` 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: ```mermaid graph LR E(GET /api/top-users) <-->|2 Interroga i top 10 utenti| D(Database) E <-->|3 Ottieni informazioni utente tramite ID| L(API di gestione di Logto) subgraph Servizio backend E end ``` Infine, puoi restituire la risposta all'app a pagina singola: ```mermaid graph LR E(GET /api/top-users) -->|4. Restituisci risposta combinata| S(App a pagina singola) subgraph Servizio backend E end ``` Un diagramma di sequenza completo: ```mermaid sequenceDiagram participant S as App a pagina singola participant E as GET /api/top-users participant D as Database participant LM as API di gestione di Logto participant L as Logto OIDC S ->> L: L'utente accede L ->> S: Completa l'accesso S ->> L: Richiedi token di accesso per il servizio backend (tramite codice di autorizzazione o refresh token) L ->> S: Restituisci token di accesso S ->> E: Richiesta con token di accesso E ->> E: Valida il token di accesso E ->> D: Interroga i top 10 utenti D ->> E: Restituisci i top 10 utenti con ID E ->> L: Richiedi token di accesso per l'API di gestione di Logto (tramite credenziali del client) L ->> E: Restituisci token di accesso E ->> LM: Ottieni informazioni dei top 10 utenti LM ->> E: Restituisci informazioni degli utenti E ->> E: Combina informazioni degli utenti con i top 10 utenti E ->> S: Restituisci risposta combinata ``` 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](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). 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](https://docs.logto.io/docs/recipes/protect-your-api/#validate-the-api-requests-authorization-token). **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)](https://docs.logto.io/docs/recipes/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. Prova Logto Cloud gratuitamente