Condividi tramite

Microsoft Identity Platform e il flusso delle credenziali client OAuth 2.0

Il flusso di concessione delle credenziali client OAuth 2.0 consente a un servizio Web (client riservato) di usare le proprie credenziali, anziché rappresentare un utente, per l'autenticazione quando si chiama un altro servizio Web. La concessione specificata in RFC 6749, talvolta denominata OAuth a due zampe, può essere usata per accedere alle risorse ospitate sul Web usando l'identità di un'applicazione. Questo tipo viene comunemente usato per le interazioni da server a server che devono essere eseguite in background, senza interazione immediata con un utente e viene spesso definito daemon o account di servizio.

Nel flusso delle credenziali client, le autorizzazioni vengono concesse direttamente all'applicazione stessa da un amministratore. Quando l'app presenta un token a una risorsa, la risorsa impone che l'app stessa abbia l'autorizzazione per eseguire un'azione poiché non è presente alcun utente coinvolto nell'autenticazione. Questo articolo illustra entrambi i passaggi necessari per:

Questo articolo descrive come programmare direttamente con il protocollo nella tua applicazione. Quando possibile, è consigliabile usare le librerie di autenticazione Microsoft supportate (MSAL) per acquisire i token e chiamare api Web protette. È anche possibile fare riferimento alle app di esempio che usano MSAL. Come nota laterale, i token di aggiornamento non verranno mai concessi con questo flusso come client_id e client_secret (che sarebbe necessario per ottenere un token di aggiornamento) possono essere usati per ottenere invece un token di accesso.

Per un livello di garanzia superiore, Microsoft Identity Platform consente anche al servizio chiamante di eseguire l'autenticazione usando un certificato o credenziali federate anziché un segreto condiviso. Poiché vengono usate le credenziali proprie dell'applicazione, queste credenziali devono essere mantenute al sicuro. Non pubblicare mai tali credenziali nel codice sorgente, incorporarlo in pagine Web o usarlo in un'applicazione nativa ampiamente distribuita.

Diagramma del protocollo

L'intero flusso delle credenziali client è simile al diagramma seguente. Descriviamo ciascuno dei passaggi più avanti in questo articolo.

Diagramma che mostra il flusso delle credenziali client

Ottenere l'autorizzazione diretta

Un'app riceve in genere l'autorizzazione diretta per accedere a una risorsa in uno dei due modi seguenti:

Questi due metodi sono i più comuni in Microsoft Entra ID ed è consigliabile per i client e le risorse che eseguono il flusso delle credenziali client. Una risorsa può anche scegliere di autorizzare i client in altri modi. Ogni server di risorse può scegliere il metodo più appropriato per l'applicazione.

Elenchi di controllo di accesso

Un provider di risorse potrebbe applicare un controllo di autorizzazione in base a un elenco di ID applicazione (client) a cui riconosce e concede un livello di accesso specifico. Quando la risorsa riceve un token dalla piattaforma di identità di Microsoft, può decodificare il token ed estrarre l'ID applicazione del client dalle appid e dalle iss attestazioni. Confronta quindi l'applicazione con un elenco di controllo di accesso (ACL) gestito. La granularità e il metodo dell'ACL possono variare notevolmente tra le risorse.

Un caso d'uso comune consiste nell'usare un elenco di controllo di accesso per eseguire test per un'applicazione Web o per un'API Web. L'API Web potrebbe concedere solo un subset di autorizzazioni complete a un client specifico. Per eseguire test end-to-end sull'API, è possibile creare un client di test che acquisisce token da Microsoft Identity Platform e quindi li invia all'API. L'API controlla quindi l'ACL per l'ID applicazione del client di test per l'accesso completo all'intera funzionalità dell'API. Se usi questo tipo di ACL, è importante convalidare non solo il valore del appid chiamante, ma anche assicurarsi che il valore del token iss sia attendibile.

Questo tipo di autorizzazione è comune per i daemon e gli account di servizio che devono accedere ai dati di proprietà degli utenti consumer che dispongono di account Microsoft personali. Per i dati di proprietà delle organizzazioni, è consigliabile ottenere l'autorizzazione necessaria tramite le autorizzazioni dell'applicazione.

Controllo dei token senza l'attestazione roles

Per abilitare questo modello di autorizzazione basato su ACL, Microsoft Entra ID non richiede che le applicazioni siano autorizzate a ottenere token per un'altra applicazione. Di conseguenza, i token esclusivi per app possono essere emessi senza un'attestazione roles. Le applicazioni che espongono le API devono implementare i controlli delle autorizzazioni per accettare i token.

Se vuoi impedire alle applicazioni di ottenere token di accesso esclusivamente app senza ruolo per la tua applicazione, assicurati che i requisiti di assegnazione siano abilitati per l'app. In questo modo gli utenti e le applicazioni senza ruoli assegnati non potranno ottenere un token per questa applicazione.

Autorizzazioni dell’applicazione

Anziché usare elenchi di controllo di accesso, è possibile usare le API per esporre un set di autorizzazioni dell'applicazione. Questi vengono concessi a un'applicazione dall'amministratore di un'organizzazione e possono essere usati solo per accedere ai dati di proprietà di tale organizzazione e dei relativi dipendenti. Ad esempio, Microsoft Graph espone diverse autorizzazioni dell'applicazione per eseguire le operazioni seguenti:

  • Leggi la posta in tutte le cassette postali
  • Leggere e scrivere posta in tutte le cassette postali
  • Inviare messaggi di posta elettronica come qualsiasi utente
  • Leggere i dati della directory

Per usare i ruoli dell'app (autorizzazioni dell'applicazione) con la propria API (anziché Microsoft Graph), è prima necessario esporre i ruoli dell'app nella registrazione dell'app dell'API nell'interfaccia di amministrazione di Microsoft Entra. Quindi, configurare i ruoli dell'app necessari selezionando tali autorizzazioni nella registrazione dell'applicazione client. Se non sono stati esposti ruoli delle app nella registrazione dell'app dell'API, non sarà possibile specificare le autorizzazioni dell'applicazione per tale API nella registrazione dell'app dell'applicazione client nel centro amministrativo di Microsoft Entra.

Quando si esegue l'autenticazione come applicazione (anziché con un utente), non è possibile usare le autorizzazioni delegate perché non esiste alcun utente per l'app per agire per conto dell'utente. È necessario usare le autorizzazioni dell'applicazione, note anche come ruoli dell'app, concesse da un amministratore o dal proprietario dell'API.

Per altre informazioni sulle autorizzazioni dell'applicazione, vedere Autorizzazioni e consenso.

In genere, quando si compila un'applicazione che usa le autorizzazioni dell'applicazione, l'app richiede una pagina o una visualizzazione in cui l'amministratore approva le autorizzazioni dell'app. Questa pagina può far parte del flusso di accesso dell'app, parte delle impostazioni dell'app o di un flusso di connessione dedicato. Spesso è opportuno che l'app mostri questa visualizzazione di connessione solo dopo che un utente ha eseguito l'accesso con un account Microsoft aziendale o dell'istituto di istruzione.

Se si accede all'utente nell'app, è possibile identificare l'organizzazione a cui appartiene l'utente prima di chiedere all'utente di approvare le autorizzazioni dell'applicazione. Anche se non strettamente necessario, può essere utile per creare un'esperienza più intuitiva per gli utenti. Per autenticare l'utente, seguire le esercitazioni sui protocolli di Microsoft Identity Platform.

Richiedere le autorizzazioni da un amministratore della directory

Quando si è pronti per richiedere le autorizzazioni dall'amministratore dell'organizzazione, è possibile reindirizzare l'utente all'endpoint di consenso amministratore di Microsoft Identity Platform.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Suggerimento pro: provare a incollare la richiesta seguente in un browser.

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
Parametro Condizione Descrizione
tenant Obbligatorio Il tenant della directory da cui si desidera ottenere autorizzazione. Può essere in formato GUID o nome descrittivo. Se non si conosce il tenant a cui appartiene l'utente e si vuole consentire l'accesso con qualsiasi tenant, usare common.
client_id Obbligatorio L'ID applicazione (client) che la funzionalità Microsoft Entra admin center – Registrazioni app ha assegnato all'app.
redirect_uri Obbligatorio URI di reindirizzamento in cui si desidera che venga inviata la risposta per la gestione da parte dell'app. Deve corrispondere esattamente a uno degli URI di reindirizzamento registrati nel portale, ad eccezione del fatto che deve essere codificato con URL e può avere segmenti di percorso aggiuntivi.
state Consigliato Un valore incluso nella richiesta, che viene anche restituito nella risposta del token. Può essere una stringa di qualsiasi contenuto desiderato. Lo stato viene usato per codificare informazioni sullo stato dell'utente nell'app prima che si sia verificata la richiesta di autenticazione, ad esempio la pagina o la visualizzazione in cui si trovavano.

A questo punto, Microsoft Entra ID impone che solo un amministratore tenant possa accedere per completare la richiesta. All'amministratore verrà chiesto di approvare tutte le autorizzazioni dirette dell'applicazione richieste per l'app nel portale di registrazione delle app.

Risposta con esito positivo

Se l'amministratore approva le autorizzazioni per l'applicazione, la risposta con esito positivo sarà simile alla seguente:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parametro Descrizione
tenant Cliente della directory che ha concesso all'applicazione le autorizzazioni richieste, in formato GUID.
state Valore incluso nella richiesta restituita anche nella risposta del token. Può essere una stringa di qualsiasi contenuto desiderato. Lo stato viene usato per codificare informazioni sullo stato dell'utente nell'app prima che si sia verificata la richiesta di autenticazione, ad esempio la pagina o la visualizzazione in cui si trovavano.
admin_consent Impostato su True.
Risposta di errore

Se l'amministratore non approva le autorizzazioni per l'applicazione, la risposta non riuscita sarà simile alla seguente:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parametro Descrizione
error Stringa di codice di errore che è possibile usare per classificare i tipi di errori e che è possibile usare per reagire agli errori.
error_description Messaggio di errore specifico che consente di identificare la causa radice di un errore.

Dopo aver ricevuto una risposta positiva dall'endpoint di provisioning dell'app, l'app ha ottenuto le autorizzazioni applicative dirette richieste. È ora possibile richiedere un token per la risorsa desiderata.

Ottenere un token

Dopo aver acquisito l'autorizzazione necessaria per l'applicazione, procedere con l'acquisizione di token di accesso per le API. Per ottenere un token usando la concessione delle credenziali client, inviare una richiesta POST a /token Microsoft Identity Platform. Esistono alcuni casi diversi:

Primo caso: richiesta di token di accesso con un segreto condiviso

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
Parametro Condizione Descrizione
tenant Obbligatorio Tenant della directory in cui l'applicazione prevede di operare, in formato GUID o nome di dominio.
client_id Obbligatorio ID dell'applicazione assegnato alla tua app. Queste informazioni sono disponibili nel portale in cui è stata registrata l'app.
scope Obbligatorio Il valore passato per il scope parametro in questa richiesta deve essere l'identificatore di risorsa (URI ID applicazione) della risorsa desiderata, con suffisso con .default. Tutti gli ambiti inclusi devono essere per una singola risorsa. L'inclusione degli ambiti per più risorse genererà un errore.
Per l'esempio di Microsoft Graph, il valore è https://graph.microsoft.com/.default. Questo valore indica a Microsoft Identity Platform che di tutte le autorizzazioni dirette applicative che hai configurato per la tua app, l'endpoint deve rilasciare un token per quelle associate alla risorsa che intendi utilizzare. Per altre informazioni sull'ambito /.default , vedere la documentazione sul consenso.
client_secret Obbligatorio Il segreto client che hai generato per la tua app nel portale di registrazione dell'app. Il segreto client deve essere codificato con URL prima di essere inviato. È supportato anche il modello di Autenticazione di Base, che prevede la fornitura delle credenziali nell'intestazione di autorizzazione, secondo RFC 6749.
grant_type Obbligatorio Deve essere impostato su client_credentials.

Secondo caso: richiesta di token di accesso con un certificato

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Parametro Condizione Descrizione
tenant Obbligatorio Tenant della directory in cui l'applicazione prevede di operare, in formato GUID o nome di dominio.
client_id Obbligatorio L'ID dell'applicazione (client) assegnato alla tua app.
scope Obbligatorio Il valore passato per il scope parametro in questa richiesta deve essere l'identificatore di risorsa (URI ID applicazione) della risorsa desiderata, con suffisso con .default. Tutti gli ambiti inclusi devono essere per una singola risorsa. L'inclusione degli ambiti per più risorse genererà un errore.
Per l'esempio di Microsoft Graph, il valore è https://graph.microsoft.com/.default. Questo valore indica a Microsoft Identity Platform che di tutte le autorizzazioni dirette applicative che hai configurato per la tua app, l'endpoint deve rilasciare un token per quelle associate alla risorsa che intendi utilizzare. Per altre informazioni sull'ambito /.default , vedere la documentazione sul consenso.
client_assertion_type Obbligatorio Il valore deve essere impostato su urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Obbligatorio Un'attestazione (un token Web JSON) di cui hai bisogno di creare e firmare con il certificato che hai registrato come le credenziali della tua applicazione. Scopri di più sulle credenziali basate su certificato per informazioni su come registrare il tuo certificato e sul formato dell'asserzione.
grant_type Obbligatorio Deve essere impostato su client_credentials.

I parametri per la richiesta basata su certificato differiscono in un solo modo rispetto alla richiesta basata su segreto condiviso: il client_secret parametro viene sostituito dai client_assertion_type parametri e client_assertion .

Terzo caso: richiesta di token di accesso con credenziali federate

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Parametro Condizione Descrizione
client_assertion Obbligatorio Asserzione (token Web JWT o JSON) ottenuta dall'applicazione da un altro provider di identità all'esterno di Microsoft Identity Platform, ad esempio Kubernetes. Le specifiche di questo token JWT devono essere registrate nell'applicazione come credenziale di identità federata. Leggere informazioni sulla federazione delle identità per i carichi di lavoro per apprendere come configurare e usare le asserzioni generate da altri provider di identità.

Tutto nella richiesta è identico al flusso basato su certificati, con l'eccezione cruciale dell'origine dell'oggetto client_assertion. In questo flusso, l'applicazione non crea l'asserzione JWT stessa. L'app usa invece un token JWT creato da un altro provider di identità. Questa operazione è denominata federazione delle identità dei carichi di lavoro, in cui l'identità delle app in un'altra piattaforma di identità viene usata per acquisire i token nella Microsoft Identity Platform. Questo è più adatto per scenari tra cloud, ad esempio l'hosting del calcolo all'esterno di Azure, ma l'accesso alle API protette da Microsoft Identity Platform. Per informazioni sul formato richiesto dei JWT creati da altri provider di identità, leggi il formato dell'asserzione.

Risposta con esito positivo

Una risposta con esito positivo da qualsiasi metodo è simile alla seguente:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Parametro Descrizione
access_token Token di accesso richiesto. L'app può usare questo token per eseguire l'autenticazione alla risorsa protetta, ad esempio per un'API Web.
token_type Indica il valore del tipo di token. L'unico tipo supportato da Microsoft Identity Platform è bearer.
expires_in Periodo di tempo in cui un token di accesso è valido (in secondi).

Avvertimento

Non tentare di convalidare o leggere i token per qualsiasi API di cui non si è proprietari, inclusi i token in questo esempio, nel codice. I token per i servizi Microsoft possono usare un formato speciale che non verrà convalidato come token JWT e potrebbe anche essere crittografato per gli utenti consumer (account Microsoft). Sebbene la lettura dei token sia uno strumento utile per il debug e l'apprendimento, è consigliabile non dipendere da questo per il codice o presupporre specifiche sui token che non sono per un'API che si controlla.

Risposta di errore

Una risposta di errore (400 Richiesta non valida) è simile alla seguente:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "YYYY-MM-DD HH:MM:SSZ",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parametro Descrizione
error Stringa di codice di errore che è possibile usare per classificare i tipi di errori che si verificano e per reagire agli errori.
error_description Messaggio di errore specifico che potrebbe aiutare a identificare la causa radice di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di STS che potrebbero essere utili per la diagnostica.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta di assistenza per la diagnostica.
correlation_id Identificatore univoco per la richiesta per facilitare la diagnostica tra i componenti.

Usare un token

Dopo aver acquisito un token, usare il token per effettuare richieste alla risorsa. Quando il token scade, ripetere la richiesta all'endpoint /token per acquisire un nuovo token di accesso.

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...

Provare il comando seguente nel terminale, assicurandosi di sostituire il token con il proprio.

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'

Esempi di codice e altre documentazione

Leggere la documentazione di panoramica delle credenziali client da Microsoft Authentication Library

Esempio Piattaforma Descrizione
active-directory-dotnetcore-daemon-v2 .NET 6.0+ Un'applicazione ASP.NET Core che visualizza gli utenti di un tenant che esegue query su Microsoft Graph usando l'identità dell'applicazione, anziché per conto di un utente. L'esempio illustra anche la variante che usa i certificati per l'autenticazione.
active-directory-dotnet-daemon-v2 ASP.NET MVC Applicazione Web che sincronizza i dati da Microsoft Graph usando l'identità dell'applicazione, anziché per conto di un utente.
ms-identity-javascript-nodejs-console Console Node.js Un'applicazione Node.js che visualizza gli utenti di un tenant eseguendo una query su Microsoft Graph usando l'identità dell'applicazione