Guida introduttiva: Chiamare un'API Web in un'app daemon di esempio
In questa guida introduttiva si usa un'applicazione daemon di esempio per acquisire un token di accesso e chiamare un'API Web protetta usando il Microsoft Authentication Library (MSAL).
Prima di iniziare, utilizzare il selettore Scegliere un tipo di tenant nella parte superiore di questa pagina per scegliere il tipo di tenant. Microsoft Entra ID offre due configurazioni tenant, dipendenti e esterni. Una configurazione tenant per la forza lavoro è rivolta ai dipendenti, alle app interne e ad altre risorse dell'organizzazione. Un tenant esterno è destinato alle app rivolte ai clienti.
L'app di esempio usata in questa guida introduttiva acquisisce un token di accesso per chiamare l'API Microsoft Graph.
Prerequisiti
- Un account Azure con una sottoscrizione attiva. Se non ne hai già uno, crea un account gratuitamente.
- Questo account di Azure deve disporre delle autorizzazioni per gestire le applicazioni. Uno dei seguenti ruoli di Microsoft Entra include le autorizzazioni necessarie:
- Amministratore di applicazioni
- Sviluppatore di applicazioni
- Amministratore di applicazioni cloud
- Inquilino della forza lavoro. Puoi utilizzare la directory predefinita oppure configurare un nuovo tenant.
- Registrare una nuova app nell'interfaccia di amministrazione di Microsoft Entra con la configurazione seguente. Per delle altre informazioni, vedere la sezione Registrazione di un'applicazione.
- Nome: identity-client-daemon-app
- Tipi di account supportati: Account solo in questa directory organizzativa (tenant singolo)
- Requisito minimo di .NET 6.0 SDK.
- Visual Studio 2022 o Visual Studio Code.
Creare un segreto di client
Creare un segreto client per l'applicazione registrata. L'applicazione usa il segreto client per dimostrare la propria identità quando richiede token:
- Nella pagina registrazioni dell'app selezionare l'applicazione creata ( ad esempio segreto client dell'app Web) per aprire la relativa pagina Panoramica.
- In Gestisci, selezionare Certificati & segreti>segreti di client>Nuovo segreto di client.
- Nella casella Descrizione immettere una descrizione per il segreto client, ad esempio segreto client dell'app Web).
- In Scadeselezionare una durata per cui il segreto è valido (in base alle regole di sicurezza dell'organizzazione) e quindi selezionare Aggiungi.
- Registra il valore del segreto. Questo valore viene usato per la configurazione in un passaggio successivo. Il valore del segreto non verrà più visualizzato e non sarà recuperabile in alcun modo, dopo che ti sposti dai Certificati e segreti. Assicurarsi di registrarlo.
Quando si creano le credenziali per un'applicazione client riservata:
Microsoft consiglia di usare un certificato anziché un segreto client prima di spostare l'applicazione in un ambiente di produzione. Per ulteriori informazioni su come utilizzare un certificato, consultare le istruzioni in credenziali del certificato di autenticazione dell'applicazione di Microsoft Identity Platform.
A scopo di test, è possibile creare un certificato autofirmato e configurare le app per l'autenticazione. Tuttavia, nell'ambiente di produzione, è meglio acquistare un certificato firmato da un'autorità di certificazione nota, quindi usare Azure Key Vault per gestire l'accesso e la durata dei certificati.
Concedere autorizzazioni API all'app daemon
Per consentire all'app daemon di accedere ai dati nell'API Microsoft Graph, concedere le autorizzazioni necessarie. L'app daemon richiede autorizzazioni per il tipo di applicazione. Gli utenti non possono interagire con un'applicazione daemon, quindi l'amministratore del tenant deve fornire il consenso a queste autorizzazioni. Usare la procedura seguente per concedere e fornire il consenso alle autorizzazioni:
Per l'app daemon .NET, non è necessario concedere o dare il consenso a nessuna autorizzazione. Questa app daemon legge le proprie informazioni di registrazione, in modo da poter funzionare senza concedere nessuna autorizzazione dell'applicazione.
Clonare o scaricare l'applicazione di esempio
Per ottenere l'applicazione di esempio, è possibile clonarla da GitHub o scaricarla come file .zip.
- Per clonare l'esempio, aprire un prompt dei comandi e passare alla posizione in cui si vuole creare il progetto e immettere il comando seguente:
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
- Scarica il file .zip. Estrarlo in un percorso di file in cui la lunghezza del nome è inferiore a 260 caratteri.
Configurare il progetto
Per usare i dettagli di registrazione dell'app nell'esempio di app daemon client, seguire questa procedura:
Aprire una finestra della console e quindi passare alla directory ms-identity-docs-code-dotnet/console-daemon:
cd ms-identity-docs-code-dotnet/console-daemon
Aprire Program.cs e sostituire il contenuto del file con il frammento di codice seguente;
// Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id> Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center", // 'Enter the client ID obtained from the Microsoft Entra admin center ClientId = "Enter the client ID obtained from the Microsoft Entra admin center", // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center ClientSecret = "Enter the client secret value obtained from the Mifcrosoft Entra admin center", // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
-
Authority
: l'autorità è un URL che indica una directory dalla quale MSAL può richiedere token. Sostituire Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center con il valore dell'ID directory (tenant) registrato in precedenza. -
ClientId
: identificatore dell'applicazione, detto anche client. Sostituire il testo tra virgolette con il valoreApplication (client) ID
registrato in precedenza dalla pagina di panoramica dell'applicazione registrata. -
ClientSecret
- Il segreto del client creato per l'applicazione nel centro di amministrazione di Microsoft Entra. Immettere il valore del segreto client. -
ClientObjectId
: ID oggetto dell'applicazione client. Sostituire il testo tra virgolette con il valoreObject ID
registrato in precedenza dalla pagina di panoramica dell'applicazione registrata.
-
Eseguire e testare l'applicazione
Hai configurato la tua app di esempio. È possibile procedere con l'esecuzione e testarla.
Dalla finestra della console eseguire il comando seguente per compilare ed eseguire l'applicazione:
dotnet run
Al termine dell'esecuzione dell'applicazione, viene visualizzata una risposta simile al frammento di codice seguente (abbreviato per brevità):
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}
Come funziona
Un'applicazione daemon acquisisce un token per conto di se 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 presentando l'ID applicazione, le credenziali (segreto o certificato) e un URI ID applicazione. L'applicazione daemon utilizza il flusso di concessione delle credenziali client standard OAuth 2.0 per acquisire un token di accesso.
L'app acquisisce un token di accesso da Microsoft Identity Platform. Il token di accesso ha come ambito l'API Microsoft Graph. L'app usa quindi il token di accesso per richiedere i dettagli di registrazione dell'applicazione dall'API Microsoft Graph. L'app può richiedere qualsiasi risorsa dall'API Microsoft Graph purché il token di accesso disponga delle autorizzazioni appropriate.
L'esempio illustra come un processo automatico o un servizio Windows può essere eseguito con un'identità dell'applicazione, anziché con l'identità di un utente.
Contenuto correlato
Impara costruendo questa app Web ASP.NET seguendo la serie della guida: Registrare un'applicazione con Microsoft Identity Platform.
Avvio rapido: Distribuire un'app web ASP.NET su Azure App Service
Prerequisiti
- Un account Azure con una sottoscrizione attiva. Se non ne hai già uno, crea un account gratuitamente.
- Questo account di Azure deve disporre delle autorizzazioni per gestire le applicazioni. Uno dei seguenti ruoli di Microsoft Entra include le autorizzazioni necessarie:
- Amministratore di applicazioni
- Sviluppatore di applicazioni
- Amministratore di applicazioni cloud
- Un tenant esterno. Per crearne uno, scegliere tra i metodi seguenti:
- (Scelta consigliata) Usare l'estensione MICROSOFT Entra External ID per configurare un tenant esterno direttamente in Visual Studio Code.
- Creare un nuovo locatario esterno nel centro di amministrazione di Microsoft Entra.
- Registrare una nuova app nell'interfaccia di amministrazione di Microsoft Entra con la configurazione seguente. Per delle altre informazioni, vedere la sezione Registrazione di un'applicazione.
- Nome: ciam-daemon-app
- Tipi di account supportati: Account solo in questa directory organizzativa (tenant singolo)
- Visual Studio Code o un altro editor di codice.
- .NET 7.0 o versione successiva.
- Node.js (solo per l'implementazione di Node)
Creare un segreto di client
Creare un segreto client per l'applicazione registrata. L'applicazione usa il segreto client per dimostrare la propria identità quando richiede token:
- Nella pagina registrazioni dell'app selezionare l'applicazione creata ( ad esempio segreto client dell'app Web) per aprire la relativa pagina Panoramica.
- In Gestisci, selezionare Certificati & segreti>segreti di client>Nuovo segreto di client.
- Nella casella Descrizione immettere una descrizione per il segreto client, ad esempio segreto client dell'app Web).
- In Scadeselezionare una durata per cui il segreto è valido (in base alle regole di sicurezza dell'organizzazione) e quindi selezionare Aggiungi.
- Registra il valore del segreto. Questo valore viene usato per la configurazione in un passaggio successivo. Il valore del segreto non verrà più visualizzato e non sarà recuperabile in alcun modo, dopo che ti sposti dai Certificati e segreti. Assicurarsi di registrarlo.
Quando si creano le credenziali per un'applicazione client riservata:
Microsoft consiglia di usare un certificato anziché un segreto client prima di spostare l'applicazione in un ambiente di produzione. Per ulteriori informazioni su come utilizzare un certificato, consultare le istruzioni in credenziali del certificato di autenticazione dell'applicazione di Microsoft Identity Platform.
A scopo di test, è possibile creare un certificato autofirmato e configurare le app per l'autenticazione. Tuttavia, nell'ambiente di produzione, è meglio acquistare un certificato firmato da un'autorità di certificazione nota, quindi usare Azure Key Vault per gestire l'accesso e la durata dei certificati.
Concedere autorizzazioni API all'app daemon
Nella pagina registrazioni dell'app selezionare l'applicazione creata, ad esempio ciam-client-app.
In Gestisci, selezionare autorizzazioni API .
In Autorizzazioni configurate, selezionare Aggiungi un'autorizzazione.
Selezionare la scheda delle API utilizzate dalla mia organizzazione.
Nell'elenco delle API selezionare l'API, ad esempio ciam-ToDoList-api.
Seleziona l'opzione Autorizzazioni applicazione. Selezioniamo questa opzione poiché l'app esegue l'accesso in proprio nome, ma non per conto di un utente.
Nell'elenco delle autorizzazioni selezionare TodoList.Read.All, ToDoList.ReadWrite.All (usare la casella di ricerca, se necessario).
Selezionare il pulsante Aggiungi autorizzazioni.
A questo punto, le autorizzazioni sono state assegnate correttamente. Tuttavia, poiché l'app daemon non consente agli utenti di interagire con essa, 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 nel tenant:
- Selezionare Concedi consenso amministratore per <nome del locatario>e quindi selezionare Sì.
- Selezionare Aggiorna, quindi verificare che Concesso per <il nome del tenant> appaia sotto Stato per entrambe le autorizzazioni.
Configurare i ruoli dell'app
Un'API deve pubblicare almeno un ruolo dell'applicazione, chiamato anche autorizzazione dell'applicazione , affinché le app client ottengano un token di accesso come tali. Le autorizzazioni dell'applicazione sono il tipo di autorizzazioni che le API devono pubblicare quando vogliono permettere alle applicazioni client di autenticarsi correttamente come entità indipendenti, senza che sia necessario l'accesso ai singoli utenti. Per pubblicare un'autorizzazione dell'applicazione, seguire questa procedura:
Nella pagina registrazioni dell'app, selezionare l'applicazione che hai creato (ad esempio ciam-ToDoList-api) per aprire la relativa pagina Panoramica.
In Gestisci, seleziona Ruoli dell'app.
Selezionare Crea ruolo app, quindi immettere i valori seguenti e quindi selezionare Applica per salvare le modifiche:
Proprietà Valore Nome visualizzato ToDoList.Leggi.Tutto Tipi di membri consentiti Applicazioni Valore ToDoList.Leggi.Tutto Descrizione Consentire all'app di leggere l'elenco ToDo di ogni utente utilizzando "la TodoListApi" Vuoi abilitare questo ruolo dell'app? Mantieni selezionato 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 la lista delle cose da fare di ogni utente usando il "ToDoListApi" Vuoi abilitare questo ruolo dell'app? Mantieni selezionato
Configurare dichiarazioni facoltative
È possibile aggiungere la richiesta facoltativa idtyp per aiutare l'API web a determinare se un token è un token app o un token app + utente. Sebbene sia possibile usare una combinazione di scp e ruoli e attestazioni per lo stesso scopo, l'uso dell'attestazione idtyp rappresenta il modo più semplice per distinguere tra un token dell'app e un token app + utente. Ad esempio, il valore di questa attestazione è app quando il token è un token solo per app.
Clonare o scaricare l'applicazione demone di esempio e l'API web
Per ottenere l'applicazione di esempio, è possibile clonarla da GitHub o scaricarla come file .zip.
Per clonare l'esempio, aprire un prompt dei comandi e passare alla posizione in cui si vuole creare il progetto e immettere il comando seguente:
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
In alternativa, scaricare gli esempi di file .zip, quindi estrarlo in un percorso del file in cui la lunghezza del nome è inferiore a 260 caratteri.
Installare le dipendenze del progetto
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
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 i dettagli di registrazione dell'app nell'esempio di app Web client, seguire questa procedura:
Nell'editor di codice aprire
App\authConfig.js
file.Trova 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
, usarecontoso
. Se non hai il nome del tenant, scopri come leggere i dettagli del tenant.Enter_the_Client_Secret_Here
e sostituiscilo con il valore del segreto dell'applicazione 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:
Nell'editor di codice aprire
API\ToDoListAPI\appsettings.json
file.Trova 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 di 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
, usarecontoso
. Se non hai il nome del tenant, scopri come leggere i dettagli del tenant.
Eseguire e testare l'app daemon di esempio e l'API
Hai configurato la tua app di esempio. È possibile procedere con l'esecuzione e testarla.
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
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 eseguite correttamente, nella finestra della console dovrebbe essere visualizzato un aspetto 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"
}
Come funziona
L'app Node.js usa il flusso di concessione delle credenziali client OAuth 2.0 per acquisire un token di accesso per se stesso e non per l'utente. Il token di accesso che l'app richiede 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. Hai esposto queste autorizzazioni dell'applicazione nell'API web in precedenza, poi le hai concesse all'applicazione daemon.
Sul lato API, un'API Web .NET di esempio, l'API 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 effettuata da un utente tramite autorizzazioni delegate/ambiti riceve l'elenco dei dati to-do dell'utente. D'altra parte, una chiamata da un'applicazione tramite autorizzazioni/ruoli dell'applicazione può ricevere l'intero elenco di to-do. Tuttavia, in questo articolo viene eseguita solo una chiamata all'applicazione, quindi non è necessario configurare autorizzazioni/ambiti delegati.