Chiamare un'API in un'applicazione daemon di esempio Node.js

  • Articolo

Questo articolo usa un'applicazione daemon di esempio Node.js per illustrare come un'app daemon acquisisce un token per chiamare un'API Web. Microsoft Entra ID per i clienti protegge l'API Web.

Un'applicazione daemon acquisisce un token per conto stesso (non per conto di un utente). Gli utenti non possono interagire con un'applicazione daemon perché richiede la propria identità. Questo tipo di applicazione richiede un token di accesso usando l'identità dell'applicazione e presentandone l'ID applicazione, le credenziali (password o certificato) e l'URI ID applicazione all'ID esterno.

Un'app daemon usa la concessione di credenziali client OAuth 2.0 standard. Per semplificare il processo di acquisizione del token, l'esempio usato in questo articolo usa Microsoft Authentication Library for Node (nodo MSAL).

Prerequisiti

Registrare un'applicazione daemon e un'API Web

In questo passaggio si crea il daemon e le registrazioni dell'applicazione API Web e si specificano gli ambiti dell'API Web.

Registrare un'applicazione API Web

  1. Accedere all'interfaccia di amministrazione Microsoft Entra almeno uno sviluppatore di applicazioni.

  2. Se si ha accesso a più tenant, usare il filtro Directory e sottoscrizioni nel menu superiore per passare al tenant del cliente.

  3. Passare aApplicazioni>di identità>Registrazioni app.

  4. Selezionare + Nuova registrazione.

  5. Nella pagina Registra un'applicazione visualizzata immettere le informazioni di registrazione dell'applicazione:

    1. Nella sezione Nome immettere un nome di applicazione significativo che verrà visualizzato agli utenti dell'app, ad esempio ciam-ToDoList-api.

    2. In Tipi di account supportati selezionare Account solo in questa directory organizzativa.

  6. Selezionare Registra per creare l'applicazione.

  7. Il riquadro Panoramica dell'applicazione viene visualizzato al termine della registrazione. Registrare l'ID directory (tenant) e l'ID applicazione (client) da usare nel codice sorgente dell'applicazione.

Configurare i ruoli dell'app

Un'API deve pubblicare un minimo di un ruolo app per le applicazioni, detta anche Autorizzazione applicazione, per ottenere un token di accesso come se stesso. Le autorizzazioni dell'applicazione sono il tipo di autorizzazioni che le API devono pubblicare quando vogliono consentire alle applicazioni client di eseguire correttamente l'autenticazione come se stessi e non devono accedere agli utenti. Per pubblicare un'autorizzazione dell'applicazione, seguire questa procedura:

  1. Nella pagina Registrazioni app selezionare l'applicazione creata (ad esempio ciam-ToDoList-api) per aprire la relativa pagina Panoramica.

  2. In Gestisci selezionare Ruoli app.

  3. Selezionare Crea ruolo app, quindi immettere i valori seguenti, quindi selezionare Applica per salvare le modifiche:

    Proprietà valore
    Nome visualizzato ToDoList.Read.All
    Tipi di membri consentiti Applicazioni
    Valore ToDoList.Read.All
    Descrizione Consenti all'app di leggere l'elenco ToDo di ogni utente usando "TodoListApi"

  4. Selezionare Di nuovo Crea ruolo app, quindi immettere i valori seguenti per il secondo ruolo dell'app , quindi selezionare Applica per salvare le modifiche:

    Proprietà valore
    Nome visualizzato ToDoList.ReadWrite.All
    Tipi di membri consentiti Applicazioni
    Valore ToDoList.ReadWrite.All
    Descrizione Consentire all'app di leggere e scrivere l'elenco ToDo di ogni utente usando "ToDoListApi"

Configurare le attestazioni facoltative

I token restituiti da Microsoft Identity vengono mantenuti più piccoli per garantire prestazioni ottimali dai client che li richiedono. Di conseguenza, diverse attestazioni non sono più presenti nel token per impostazione predefinita e devono essere richieste in modo specifico per ogni applicazione. Per questa app, si include l'attestazione facoltativa idtyp per aiutare l'API Web a determinare se un token è un token dell'app o un token app+utente. Anche se una combinazione di attestazioni di scp e ruoli può essere usata per lo stesso scopo, l'uso dell'attestazione idtyp è il modo più semplice per indicare un token dell'app e un token utente+app a parte. Ad esempio, il valore di questa attestazione è app quando il token è un token solo app.

Seguire questa procedura per configurare l'attestazione facoltativa idtyp :

  1. In Gestisci selezionare Configurazione token.

  2. Selezionare Aggiungi un'attestazione facoltativa.

  3. In Tipo di token scegliere Accesso.

  4. Selezionare l'idtyp di attestazione facoltativo.

  5. Selezionare Aggiungi per salvare le modifiche.

Registrare l'app daemon

Per consentire all'applicazione di accedere agli utenti con Microsoft Entra, Microsoft Entra ID per i clienti devono essere consapevoli dell'applicazione creata. La registrazione dell'app stabilisce una relazione di trust tra l'app e Microsoft Entra. Quando si registra un'applicazione, l'ID esterno genera un identificatore univoco noto come ID applicazione (client), un valore usato per identificare l'app durante la creazione di richieste di autenticazione.

La procedura seguente illustra come registrare l'app nell'interfaccia di amministrazione Microsoft Entra:

  1. Accedere all'interfaccia di amministrazione Microsoft Entra almeno uno sviluppatore di applicazioni.

  2. Se si ha accesso a più tenant, usare il filtro Directory e sottoscrizioni nel menu superiore per passare al tenant del cliente.

  3. Passare aApplicazioni>di identità>Registrazioni app.

  4. Selezionare + Nuova registrazione.

  5. Nella pagina Registra un'applicazione visualizzata;

    1. Immettere un nome di applicazione significativo visualizzato agli utenti dell'app, ad esempio ciam-client-app.
    2. In Tipi di account supportati selezionare Account solo in questa directory organizzativa.

  6. Selezionare Registra.

  7. Il riquadro Panoramica dell'applicazione viene visualizzato al termine della registrazione. Registrare l'ID applicazione (client) da usare nel codice sorgente dell'applicazione.

Creare un segreto client

Creare un segreto client per l'applicazione registrata. L'applicazione usa il segreto client per dimostrare la propria identità quando richiede token.

  1. Nella pagina Registrazioni app selezionare l'applicazione creata (ad esempio ciam-client-app) per aprire la relativa pagina Panoramica.
  2. In Gestisci selezionare Certificati e segreti.
  3. Selezionare Nuovo segreto client.
  4. Nella casella Descrizione immettere una descrizione per il segreto client, ad esempio il segreto client dell'app ciam.
  5. In Scade selezionare una durata per cui il segreto è valido (per le regole di sicurezza delle organizzazioni) e quindi selezionare Aggiungi.
  6. Registrare il Valore del segreto. Questo valore verrà usato per la configurazione in un passaggio successivo.

Nota

Il valore segreto non verrà visualizzato di nuovo e non sarà recuperabile in alcun modo, dopo aver spostato dalla pagina Certificati e segreti , quindi assicurarsi di registrarlo.
Per la sicurezza avanzata, è consigliabile usare i certificati anziché i segreti client.

Concedere autorizzazioni API all'app daemon

  1. Nella pagina Registrazioni app selezionare l'applicazione creata, ad esempio ciam-client-app.

  2. In Gestisci selezionare Autorizzazioni API.

  3. In Autorizzazioni configurate selezionare Aggiungi un'autorizzazione.

  4. Selezionare la scheda Le mie API.

  5. Nell'elenco delle API selezionare l'API, ad esempio ciam-ToDoList-api.

  6. Selezionare l'opzione Autorizzazioni applicazione . Questa opzione viene selezionata come l'app esegue l'accesso come se stesso, non come utenti.

  7. Nell'elenco delle autorizzazioni selezionare TodoList.Read.All, ToDoList.ReadWrite.All (usare la casella di ricerca, se necessario).

  8. Selezionare il pulsante Aggiungi autorizzazioni.

  9. A questo punto, le autorizzazioni sono state assegnate correttamente. Tuttavia, poiché l'app daemon non consente agli utenti di interagire con esso, gli utenti stessi non possono fornire il consenso a queste autorizzazioni. Per risolvere questo problema, l'amministratore deve fornire il consenso a queste autorizzazioni per conto di tutti gli utenti del tenant:

    1. Selezionare Concedi consenso amministratore per <il nome> del tenant e quindi selezionare Sì.
    2. Selezionare Aggiorna, quindi verificare che Concesso per <il nome> del tenant sia visualizzato in Stato per entrambe le autorizzazioni.

Clonare o scaricare l'applicazione daemon di esempio e l'API Web

Per ottenere il codice di esempio dell'app Web, è possibile eseguire una delle attività seguenti:

  • Scaricare il file .zip o clonare l'applicazione Web di esempio da GitHub eseguendo il comando seguente:

        git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git

Se si sceglie di scaricare il file di.zip , estrarre il file dell'app di esempio in una cartella in cui la lunghezza totale del percorso è di 260 o meno caratteri.

Installare le dipendenze del progetto

  1. Aprire una finestra della console e passare alla directory che contiene l'app di esempio Node.js:

        cd 2-Authorization\3-call-api-node-daemon\App

  2. Eseguire i comandi seguenti per installare le dipendenze dell'app:

        npm install && npm update

Configurare l'app e l'API del daemon di esempio

Per usare la registrazione dell'app nell'esempio di app Web client:

  1. Nell'editor di codice aprire App\authConfig.js il file.

  2. Trovare il segnaposto:

    • Enter_the_Application_Id_Here e sostituirlo con l'ID applicazione (client) dell'app daemon registrata in precedenza.

    • Enter_the_Tenant_Subdomain_Here e sostituirlo con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se non si ha il nome del tenant, vedere come leggere i dettagli del tenant.

    • Enter_the_Client_Secret_Here e sostituirlo con il valore del segreto dell'app daemon copiato in precedenza.

    • Enter_the_Web_Api_Application_Id_Here e sostituirlo con l'ID applicazione (client) dell'API Web copiata in precedenza.

Per usare la registrazione dell'app nell'esempio di API Web:

  1. Nell'editor di codice aprire API\ToDoListAPI\appsettings.json il file.

  2. Trovare il segnaposto:

    • Enter_the_Application_Id_Here e sostituirlo con l'ID applicazione (client) dell'API Web copiata.

    • Enter_the_Tenant_Id_Here e sostituirlo con l'ID directory (tenant) copiato in precedenza.

    • Enter_the_Tenant_Subdomain_Here e sostituirlo con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se non si ha il nome del tenant, vedere come leggere i dettagli del tenant.

Eseguire e testare l'app e l'API del daemon di esempio

  1. Aprire una finestra della console, quindi eseguire l'API Web usando i comandi seguenti:

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

  2. Eseguire il client dell'app Web usando i comandi seguenti:

        2-Authorization\3-call-api-node-daemon\App
     node . --op getToDos

Se l'app daemon e l'API Web vengono eseguiti correttamente, nella finestra della console dovrebbe essere visualizzato un risultato simile alla matrice JSON seguente

{
    id: 1,
    owner: '3e8....-db63-43a2-a767-5d7db...',
    description: 'Pick up grocery'
},
{
    id: 2,
    owner: 'c3cc....-c4ec-4531-a197-cb919ed.....',
    description: 'Finish invoice report'
},
{
    id: 3,
    owner: 'a35e....-3b8a-4632-8c4f-ffb840d.....',
    description: 'Water plants'
}

Funzionamento

L'app Node.js usa le credenziali client OAuth 2.0 per acquisire un token di accesso per se stesso e non per l'utente. Il token di accesso richiesto dall'app contiene le autorizzazioni rappresentate come ruoli. Il flusso delle credenziali client usa questo set di autorizzazioni al posto degli ambiti utente per i token dell'applicazione. Queste autorizzazioni dell'applicazione sono state esposte in precedenza nell'API Web, quindi concesse all'app daemon.

Sul lato API l'API Web deve verificare che il token di accesso disponga delle autorizzazioni necessarie (autorizzazioni dell'applicazione). L'API Web non può accettare un token di accesso che non dispone delle autorizzazioni necessarie.

Accesso ai dati

Un endpoint API Web deve essere preparato per accettare chiamate da utenti e applicazioni. Pertanto, deve avere un modo per rispondere a ogni richiesta di conseguenza. Ad esempio, una chiamata da un utente tramite autorizzazioni/ambiti delegati riceve l'elenco attività dei dati dell'utente. D'altra parte, una chiamata da un'applicazione tramite autorizzazioni/ruoli dell'applicazione può ricevere l'intero elenco attività. Tuttavia, in questo articolo viene eseguita solo una chiamata all'applicazione, quindi non è necessario configurare autorizzazioni/ambiti delegati.

Passaggi successivi