Flussi e scenari di applicazione di OpenID Connect/OAuth in AD FS

• Si applica a:

  ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016

Si applica ad AD FS 2019 e versioni successive

Scenario	Procedura dettagliata per lo scenario con esempi	Flusso/concessione OAuth 2.0	Tipo di client
App a singola pagina	Esempio di utilizzo di MSAL	Implicito	Pubblico
App Web che esegue l'accesso degli utenti	Esempio di utilizzo di OWIN	Codice di autorizzazione	Pubblico, riservato
App nativa che chiama l'API Web	Esempio di utilizzo di MSAL	Codice di autorizzazione	Pubblico
App Web che chiama l'API Web	Esempio di utilizzo di MSAL	Codice di autorizzazione	Riservati
Implementazione PKCE		Codice di autorizzazione	Pubblico
API Web che chiama un'altra API Web per conto dell'utente (OBO)	Esempio di utilizzo di MSAL	On-behalf-of	L'app Web funziona come riservata
App daemon che chiama l'API Web		Credenziali del client	Riservati
App Web che chiama l'API Web usando le credenziali dell'utente		Credenziali password del proprietario della risorsa	Pubblico, riservato
App senza browser che chiama l'API Web		Codice del dispositivo	Pubblico, riservato

Flusso di concessione implicita

Nota

Microsoft consiglia vivamente di eseguire la migrazione all'ID Microsoft Entra invece di eseguire l'aggiornamento a una versione più recente di AD FS. Per altre informazioni sul flusso di concessione implicita nell'ID Microsoft Entra, vedere Flusso di concessione implicita in Microsoft Identity Platform.

Per le applicazioni a pagina singola (AngularJS, Ember.js, React.js e così via), AD FS supporta il flusso di concessione implicita OAuth 2.0. Il flusso implicito è descritto nella specifica di OAuth 2.0. Offre come vantaggio principale la possibilità per l'app di ottenere i token da AD FS senza eseguire uno scambio di credenziali con il server back-end. Ciò consente all'app di eseguire l'accesso dell'utente, gestire la sessione e ottenere i token per altre API Web all'interno del codice JavaScript del client. Esistono alcune importanti considerazioni sulla sicurezza di cui tenere conto quando si usa il flusso implicito in particolare per il client.

Se si vuole usare il flusso implicito e AD FS per aggiungere l'autenticazione all'app JavaScript, seguire la procedura generale riportata di seguito.

Diagramma del protocollo

Il diagramma seguente illustra l'intero flusso di accesso implicito e le sezioni che seguono descrivono ogni passaggio in modo più dettagliato.

Token ID richiesta e token di accesso

Per eseguire l'accesso iniziale dell'utente nell'app, si può inviare una richiesta di autenticazione OpenID Connect e ottenere id_token e il token di accesso dall'endpoint AD FS.

// Line breaks for legibility only

https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345

Parametro	Obbligatorio/facoltativo	Descrizione
client_id	necessario	ID dell'applicazione (client) assegnato da AD FS all'app.
response_type	necessario	Deve includere id_token per l'accesso a OpenID Connect. Può includere anche response_typetoken. L'uso del token consente all'app di ricevere immediatamente un token di accesso dall'endpoint di autorizzazione senza dover effettuare una seconda richiesta all'endpoint del token.
redirect_uri	necessario	Valore redirect_uri dell'app, dove possono essere inviate e ricevute dall'app le risposte di autenticazione. Deve corrispondere esattamente a uno dei valori redirect_uri configurati in AD FS.
nonce	necessario	Valore incluso nella richiesta, generato dall'app, che verrà incluso come attestazione nel parametro id_token risultante. L'app può quindi verificare questo valore per l'attenuazione degli attacchi di riproduzione del token. Il valore è in genere una stringa casuale univoca che può essere usata per identificare l'origine della richiesta. Obbligatorio solo quando viene richiesto un valore id_token.
ambito	facoltative	Elenco di ambiti separato da spazi. Per OpenID Connect, deve includere l'ambitoopenid.
resource	facoltative	URL dell'API Web. Nota: se si usa la libreria client MSAL, il parametro della risorsa non viene inviato. L'URL della risorsa viene invece inviato come parte del parametro di ambito: scope = [resource url]//[scope values e.g., openid] se la risorsa non viene passata qui o nell'ambito, AD FS usa una risorsa predefinita urn:microsoft:userinfo. I criteri di risorsa userinfo, come ad esempio l’autenticazione a più fattori, il criterio di rilascio o autorizzazione, non possono essere personalizzati.
response_mode	facoltative	Specifica il metodo da usare per inviare il token risultante a un'app. Il valore predefinito è fragment.
state	facoltative	Valore incluso nella richiesta che verrà restituito anche nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto desiderato. Per evitare gli attacchi di richiesta intersito falsa, viene in genere usato un valore univoco generato casualmente. Il parametro state viene anche usato per codificare le informazioni sullo stato dell'utente nell'app attivo prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la vista attiva.
prompt	facoltative	Indica il tipo di interazione utente richiesto. Gli unici valori validi al momento sono sign-in e none. - prompt=login forza l'utente a immettere le proprie credenziali su tale richiesta, negando l'accesso Single Sign-On. - prompt=noneè l'opposto: garantisce che all'utente non venga presentata alcuna richiesta interattiva. Se la richiesta non può essere completata automaticamente tramite Single-Sign-On, AD FS restituirà un errore interaction_required.
login_hint	facoltative	Può essere usato per precompilare il campo nome utente/indirizzo di posta elettronica della pagina di accesso per l'utente, se ne conosci già il nome. Le app useranno spesso questo parametro durante la riautenticazione, avendo già estratto il nome utente da un accesso precedente usando l'attestazione upn da id_token.
domain_hint	facoltative	Se incluso, questo parametro ignorerà il processo di individuazione basato su dominio a cui viene sottoposto l'utente nella pagina di accesso, garantendo un'esperienza utente leggermente più semplice.

A questo punto viene chiesto all'utente di immettere le credenziali e completare l'autenticazione. Dopo che l'utente ha eseguito l'autenticazione, l'endpoint di autorizzazione AD FS restituisce una risposta all'app in corrispondenza del valore redirect_uri indicato, usando il metodo specificato nel parametro response_mode.

Risposta riuscita

Una risposta di esito positivo con response_mode=fragment and response_type=id_token+token ha un aspetto simile al seguente

// Line breaks for legibility only

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345

Parametro	Descrizione
access_token	Parametro incluso se response_type includetoken.
token_type	Parametro incluso se response_type includetoken. è sempre "Bearer”.
expires_in	Parametro incluso se response_type includetoken. Indica il numero di secondi di validità del token, ai fini della memorizzazione nella cache.
ambito	Indica gli ambiti per i quali avrà validità access_token.
id_token	Parametro incluso se response_type includeid_token. Token JSON Web (JWT) firmato. L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per i limiti di autorizzazione o di sicurezza.
state	Se nella richiesta è incluso un parametro state, lo stesso valore deve essere visualizzato nella risposta. L'app deve verificare che i valori state nella richiesta e nella risposta siano identici.

Token di aggiornamento

La concessione implicita non fornisce token di aggiornamento. Sia id_tokens che access_tokens scadono dopo un breve periodo di tempo, quindi l'app deve essere preparata ad aggiornare periodicamente questi token. Per aggiornare entrambi i tipi di token, è possibile eseguire la stessa richiesta iframe nascosta precedente usando il parametro prompt=none per controllare il comportamento della piattaforma di identità. Se vuoi ricevere new id_token, usaresponse_type=id_token.

Flusso di concessione del codice di autorizzazione

Nota

Microsoft consiglia vivamente di eseguire la migrazione all'ID Microsoft Entra invece di eseguire l'aggiornamento a una versione più recente di AD FS. Per altre informazioni sul flusso di concessione del codice di autorizzazione nell'ID Microsoft Entra, vedere Flusso di concessione del codice di autorizzazione in Microsoft Identity Platform.

La concessione del codice di autorizzazione OAuth 2.0 può essere usata nelle app Web per ottenere l'accesso a risorse protette, ad esempio le API Web. Il flusso del codice di autorizzazione di OAuth 2.0 è descritto nella sezione 4.1 della specifica di OAuth 2.0. Viene usato per eseguire l'autenticazione e l'autorizzazione nella maggior parte dei tipi di app, tra cui app Web e app installate in modo nativo. Il flusso consente alle app di acquisire in modo sicuro parametri access_token che possono essere usati per accedere a risorse che considerano AD FS attendibile.

Diagramma del protocollo

A livello generale, il flusso di autenticazione per un'applicazione nativa ha un aspetto simile al seguente:

Richiedere un codice di autorizzazione

Il flusso del codice di autorizzazione inizia con il client che indirizza l'utente all'endpoint /authorize. In questa richiesta il client indica le autorizzazioni che deve acquisire dall'utente:

// Line breaks for legibility only

https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345

Parametro	Obbligatorio/facoltativo	Descrizione
client_id	necessario	ID dell'applicazione (client) assegnato da AD FS all'app.
response_type	necessario	Deve includere il codice per il flusso del codice di autorizzazione.
redirect_uri	necessario	Parametro redirect_uri dell'app, dove possono essere inviate e ricevute dall'app le risposte di autenticazione. Deve corrispondere esattamente a uno dei parametri redirect_uri registrati in AD FS per il client.
resource	facoltative	URL dell'API Web. Nota: se si usa la libreria client MSAL, il parametro della risorsa non viene inviato. L'URL della risorsa viene invece inviato come parte del parametro di ambito: scope = [resource url]//[scope values e.g., openid] se la risorsa non viene passata qui o nell'ambito, AD FS usa una risorsa predefinita urn:microsoft:userinfo. I criteri di risorsa userinfo, come ad esempio l’autenticazione a più fattori, il criterio di rilascio o autorizzazione, non possono essere personalizzati.
ambito	facoltative	Elenco di ambiti separato da spazi.
response_mode	facoltative	Specifica il metodo da usare per inviare il token risultante a un'app. Può essere uno dei metodi seguenti: - query - frammento - form_post query fornisce il codice come parametro della stringa di query sull'URI di reindirizzamento. Se si richiede il codice, è possibile usare query, frammento o form_post. form_post esegue un POST contenente il codice all'URI di reindirizzamento.
state	facoltative	Valore incluso nella richiesta che verrà restituito anche nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto desiderato. Per evitare gli attacchi di richiesta intersito falsa, viene in genere usato un valore univoco generato casualmente. Il valore può anche codificare le informazioni sullo stato dell'utente nell'app attivo prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la vista attiva.
prompt	facoltative	Indica il tipo di interazione utente richiesto. Gli unici valori validi al momento sono sign-in e none. - prompt=login forza l'utente a immettere le proprie credenziali su tale richiesta, negando l'accesso Single Sign-On. - prompt=noneè l'opposto: garantisce che all'utente non venga presentata alcuna richiesta interattiva. Se la richiesta non può essere completata automaticamente tramite Single-Sign-On, AD FS restituirà un errore interaction_required.
login_hint	facoltative	Può essere usato per precompilare il campo nome utente/indirizzo di posta elettronica della pagina di accesso per l'utente, se ne conosci già il nome. Le app useranno spesso questo parametro durante la riautenticazione, avendo già estratto il nome utente da un accesso precedente usando l'attestazione upn da id_token.
domain_hint	facoltative	Se incluso, questo parametro ignorerà il processo di individuazione basato su dominio a cui viene sottoposto l'utente nella pagina di accesso, garantendo un'esperienza utente leggermente più semplice.
code_challenge_method	facoltative	Metodo usato per codificare code_verifier per il parametro code_challenge. Può essere uno dei valori seguenti: - plain - S256 Se escluso, si presuppone che code_challenge sia testo non crittografato se code_challenge è incluso. AD FS supporta sia plain che S256. Per altre informazioni, vedere il PKCE RFC.
code_challenge	facoltative	Usato per proteggere le concessioni del codice di autorizzazione tramite PKCE (Proof Key for Code Exchange) da un client nativo. Obbligatorio con code_challenge_method incluso. Per altre informazioni, vedere il PKCE RFC

A questo punto viene chiesto all'utente di immettere le credenziali e completare l'autenticazione. Dopo che l'utente ha eseguito l'autenticazione, AD FS restituisce una risposta all'app in corrispondenza del valore di redirect_uri indicato, usando il metodo specificato nel parametro response_mode.

Risposta riuscita

Una risposta di esito positivo con response_mode=query è simile alla seguente:

GET https://adfs.contoso.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Parametro	Descrizione
codice	authorization_code richiesto dall'app. L'app può usare il codice di autorizzazione per richiedere un token di accesso per la risorsa di destinazione. I parametri authorization_code hanno breve durata, in genere scadono dopo circa 10 minuti.
state	Se nella richiesta è incluso un parametro state, lo stesso valore deve essere visualizzato nella risposta. L'app deve verificare che i valori state nella richiesta e nella risposta siano identici.

Richiedere un token di accesso

Dopo aver acquisito un parametro authorization_code e aver ottenuto l'autorizzazione da parte dell'utente, è possibile riscattare il codice per un access_token per la risorsa desiderata. Riscattare il codice inviando una richiesta POST all'endpoint /token:

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for confidential clients (web apps)

Parametro	Obbligatoria/facoltativa	Descrizione
client_id	necessario	ID dell'applicazione (client) assegnato da AD FS all'app.
grant_type	necessario	Deve essere authorization_code per il flusso del codice di autorizzazione.
codice	necessario	authorization_code acquisito nella prima parte del flusso.
redirect_uri	necessario	Lo stesso valore redirect_uri usato per acquisire authorization_code.
client_secret	obbligatorio per le app Web	Segreto dell'applicazione creato durante la registrazione dell'app in AD FS. Non è consigliabile usare il segreto dell'applicazione in un'app nativa perché i parametri client_secret non possono essere archiviati in modo affidabile nei dispositivi. Questo parametro è obbligatorio per le app Web e le API Web, che hanno la possibilità di archiviare il parametro client_secret in modo sicuro sul lato server. Il segreto client deve essere codificato nell'URL prima dell'invio. Queste app possono anche usare un'autenticazione basata su chiave firmando un token JWT e aggiungendolo come parametro client_assertion.
code_verifier	facoltative	Lo stesso code_verifier usato per ottenere il valore authorization_code. Obbligatorio se è stato usato PKCE nella richiesta di concessione del codice di autorizzazione. Per altre informazioni, vedere il PKCE RFC. Questa opzione si applica ad AD FS 2019 e versioni successive

Risposta riuscita

Una risposta di token con esito positivo ha un aspetto simile al seguente:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Parametro	Descrizione
access_token	Token di accesso richiesto. L'app può usare questo token per eseguire l'autenticazione nella risorsa protetta (API Web).
token_type	Indica il valore del tipo di token. L'unico tipo supportato da AD FS è Bearer.
expires_in	Tempo di validità del token di accesso (in secondi).
token di aggiornamento	Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire altri token di accesso dopo che quello corrente è scaduto. I parametri refresh_token sono di lunga durata e possono essere usati per mantenere l'accesso alle risorse per lunghi periodi di tempo.
refresh_token_expires_in	Tempo di validità del token di aggiornamento (in secondi).
id_token	Token JWT (JSON Web Token). L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per i limiti di autorizzazione o di sicurezza.

Usare il token di accesso

GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Flusso di concessione dei token di aggiornamento

I parametri access_token sono di breve durata e devi aggiornarli dopo la scadenza per continuare ad accedere alle risorse. A tale scopo, inviare un'altra richiesta POST all'endpoint /token, questa volta specificando il refresh_token anziché il codice. I token di aggiornamento sono validi per tutte le autorizzazioni per cui il client ha già ricevuto il token di accesso.

I token di aggiornamento non hanno una durata specificata. In genere, la durata dei token di aggiornamento è relativamente lunga. In alcuni casi tuttavia i token di aggiornamento scadono, vengono revocati o non dispongono di privilegi sufficienti per l'azione desiderata. L'applicazione deve prevedere e gestire correttamente gli errori restituiti dall'endpoint di rilascio dei token.

Anche se i token di aggiornamento non vengono revocati quando vengono usati per acquisire nuovi token di accesso, è necessario rimuovere il token di aggiornamento precedente. Come indicato nella specifica OAuth 2.0, “Il server di autorizzazione PUÒ rilasciare un nuovo token di aggiornamento, nel qual caso il client DEVE rimuovere il token di aggiornamento precedente e sostituirlo con quello nuovo. Il server di autorizzazione PUÒ revocare il token di aggiornamento precedente dopo aver rilasciato un nuovo token di aggiornamento per il client". AD FS rilascia un token di aggiornamento quando la durata del nuovo token di aggiornamento è maggiore della durata di quello precedente. Per altre informazioni sulle durate dei token di aggiornamento di AD FS, vedi Impostazioni di Single Sign-on di AD FS.

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for confidential clients (web apps)

Parametro	Obbligatorio/facoltativo	Descrizione
client_id	necessario	ID dell'applicazione (client) assegnato da AD FS all'app.
grant_type	necessario	Deve essere refresh_token per questa sezione del flusso del codice di autorizzazione.
resource	facoltative	URL dell'API Web. Nota: se si usa la libreria client MSAL, il parametro della risorsa non viene inviato. L'URL della risorsa viene invece inviato come parte del parametro di ambito: scope = [resource url]//[scope values e.g., openid] se la risorsa non viene passata qui o nell'ambito, AD FS usa una risorsa predefinita urn:microsoft:userinfo. I criteri di risorsa userinfo, come ad esempio l’autenticazione a più fattori, il criterio di rilascio o autorizzazione, non possono essere personalizzati.
ambito	facoltative	Elenco di ambiti separato da spazi.
token di aggiornamento	necessario	Parametro refresh_token acquisito nella seconda parte del flusso.
client_secret	obbligatorio per le app Web	Segreto dell'applicazione creato nel portale di registrazione dell'app. Non è consigliabile usarlo in un'app nativa perché i parametri client_secret non possono essere archiviati in modo affidabile nei dispositivi. Questo parametro è obbligatorio per le app Web e le API Web, che hanno la possibilità di archiviare il parametro client_secret in modo sicuro sul lato server. Queste app possono anche usare un'autenticazione basata su chiave firmando un token JWT e aggiungendolo come parametro client_assertion.

Risposta riuscita

Una risposta di token con esito positivo ha un aspetto simile al seguente:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Parametro	Descrizione
access_token	Token di accesso richiesto. L'app può usare questo token per eseguire l'autenticazione nella risorsa protetta, ad esempio un'API Web.
token_type	Indica il valore del tipo di token. L'unico tipo supportato da AD FS è Bearer
expires_in	Tempo di validità del token di accesso (in secondi).
ambito	Ambiti per i quali è valido access_token.
token di aggiornamento	Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire altri token di accesso dopo che quello corrente è scaduto. I parametri refresh_token sono di lunga durata e possono essere usati per mantenere l'accesso alle risorse per lunghi periodi di tempo.
refresh_token_expires_in	Tempo di validità del token di aggiornamento (in secondi).
id_token	Token JWT (JSON Web Token). L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per i limiti di autorizzazione o di sicurezza.

Supporto di Proof Key for Code Exchange (PKCE) per OAuth

I client pubblici OAuth che usano la concessione del codice di autorizzazione sono vulnerabili agli attacchi di intercettazione del codice di autorizzazione, come descritto in RFC 7636. Per attenuare questi attacchi, a partire da Windows Server 2019, AD FS ora supporta la chiave di prova per Code Exchange (PKCE) per il flusso di concessione del codice di autorizzazione OAuth.

La specifica di supporto PKCE aggiunge altri parametri alle richieste di autorizzazione e token di accesso OAuth 2.0. Il diagramma seguente mostra una struttura visiva del processo PKCE quando un client contatta AD FS in Windows Server 2019.

Nella sezione con etichetta A, il client crea e registra un segreto denominato code_verifier e deriva una versione trasformata del segreto denominato t(code_verifier), noto anche come code_challenge. Il client invia quindi il segreto nella richiesta di autorizzazione OAuth 2.0 insieme al metodo di t_m trasformazione.

Nella sezione con etichetta B l'endpoint di autorizzazione risponde come di consueto, ma registra il t(code_verifier) segreto e il metodo di trasformazione.

Nella sezione C, il client invia quindi il codice di autorizzazione nella richiesta del token di accesso come di consueto, ma include il code_verifier segreto generato nella sezione A.

Nella sezione con etichetta D, AD FS trasforma il code_verifiersegreto e lo confronta con il segreto dalla t(code_verifier) sezione B. Se i valori non sono uguali, AD FS nega l'accesso.

Come scegliere più provider di autenticazione per lo stesso criterio delle regole in Windows Server 2019

AD FS supporta già l'attivazione di un'autenticazione aggiuntiva basata su un criterio di regola attestazione (RP). Questi criteri È possibile impostarli per un determinato punto di ripristino o a livello globale. È possibile impostare un criterio di autenticazione aggiuntivo per un determinato punto di ripristino aprendo PowerShell come amministratore ed eseguendo il cmdlet Set-AdfsRelyingPartyTrust passando il parametro AdditionalAuthenticationRules o AdditionalAuthenticationRulesFile . Per impostarlo a livello globale, un amministratore può usare il cmdlet Set-AdfsAdditionalAuthenticationRule . L'impostazione di criteri aggiuntivi consente di usare più provider di autenticazione per la stessa applicazione.

Le regole attestazioni offrono la possibilità di selezionare il provider di autenticazione per l'autenticazione aggiuntiva, che risulta utile nelle situazioni in cui i clienti si spostano tra provider o richiedono un provider distinto per determinate applicazioni. A partire da Windows Server 2019, è ora possibile usare le regole delle attestazioni per decidere quale altro provider di autenticazione richiamare per l'autenticazione aggiuntiva. Questa funzionalità è utile per due scenari:

• Gli utenti passano da un altro provider di autenticazione a un altro. Durante l'onboarding degli utenti in un provider di autenticazione più recente, possono usare i gruppi per controllare quale provider di autenticazione aggiuntivo usa il servizio.

• Gli utenti necessitano di un provider di autenticazione aggiuntivo specifico per determinate applicazioni, ma devono anche usare un metodo diverso per altre applicazioni.

È possibile configurare queste impostazioni eseguendo il comando seguente da altri criteri di autenticazione:

Set-AdfsAdditionalAuthenticationRule -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn" );' 

Per configurare questa regola, è necessario rilasciare l'attestazione http://schemas.microsoft.com/claims/authnmethodsproviders da altri criteri di autenticazione. Il valore di questa attestazione deve essere la variabile Name del provider di autenticazione.

È anche possibile modificare questa configurazione della regola per consentire agli utenti di passare da un provider di autenticazione a un altro. Si supponga, ad esempio, di voler modificare un gruppo gestito per usare Azure AD MFA e un gruppo per usare i certificati come provider di autenticazione aggiuntivo.

Se si vuole tenere traccia del numero di persone che eseguono la registrazione per Azure AD MFA e l'autenticazione del certificato, eseguire un comando simile al seguente con i valori sostituiti con quelli rilevanti per l'organizzazione:

'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" ); 

 c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-608905689-872870963-3921916988-12345"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication"); 

not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value=="S-1-5-21-608905689-872870963-3921916988-12345"]) => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");’ 

Successivamente, è possibile impostare la prima applicazione, denominata AppA, per usare Azure AD Multi-Factor Authentication come provider di autenticazione aggiuntivo eseguendo questo comando:

Set-AdfsRelyingPartyTrust -TargetName AppA -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" ); 

c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");' 

Infine, è possibile impostare la seconda app, denominata AppB, per usare Certificate come provider di autenticazione aggiuntivo eseguendo questo comando:

Set-AdfsRelyingPartyTrust -TargetName AppB -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" ); 

c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");' 

Gli amministratori possono anche creare regole per consentire più provider di autenticazione aggiuntivi. In questo caso AD FS mostra i provider di metodi di autenticazione rilasciati e l’utente può sceglierne uno qualsiasi. Per consentire più provider di autenticazione aggiuntivi, devono emettere più attestazioni usando il valore http://schemas.microsoft.com/claims/authnmethodsproviders.

Se la valutazione dell'attestazione restituisce nessuno dei provider di autenticazione, AD FS esegue il rollback e visualizza un elenco che mostra tutti i provider di autenticazione aggiuntivi configurati dall'amministratore in AD FS. L'utente deve quindi selezionare manualmente il provider di autenticazione appropriato.

Se il provider di autenticazione preferito non è presente nell'elenco, è possibile eseguire il cmdlet seguente per visualizzare tutti i provider supportati:

(Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider

Il valore utilizzato per l'attestazione http://schemas.microsoft.com/claims/authnmethodsproviders deve essere uno dei nomi di provider restituiti dall'elenco dei provider restituiti da AD FS.

AD FS non supporta l'attivazione di un provider di autenticazione aggiuntivo specifico mentre il provider di servizi di ripristino usa criteri di Controllo di accesso in AD FS Windows Server 2016. Quando si sposta un'applicazione da un criterio di Controllo di accesso, AD FS copia i criteri corrispondenti da criteri di Controllo di accesso a AdditionalAuthenticationRules e IssuanceAuthorizationRules. Se un amministratore vuole usare un provider di autenticazione specifico, deve smettere di usare i criteri di Controllo di accesso e modificare invece AdditionalAuthenticationRules.

Flusso On-Behalf-Of

Nota

Microsoft consiglia vivamente di eseguire la migrazione all'ID Microsoft Entra invece di eseguire l'aggiornamento a una versione più recente di AD FS. Per altre informazioni sul flusso On-Behalf-Of nell'ID Microsoft Entra, vedere Flusso On-Behalf-Of in Microsoft Identity Platform.

Il flusso On-Behalf-Of (OBO) di OAuth 2.0 rappresenta il caso d'uso in cui un'applicazione richiama un'API servizio/Web, che a sua volta deve chiamare un'altra API servizio/Web. L'idea consiste nel propagare l'identità e le autorizzazioni dell'utente delegato tramite la catena di richieste. Per effettuare richieste autenticate al servizio downstream, il servizio di livello intermedio deve proteggere un token di accesso da AD FS per conto dell'utente.

Diagramma del protocollo

Si supponga che l'utente sia stato autenticato in un'applicazione usando il flusso di concessione del codice di autorizzazione OAuth 2.0 descritto nella sezione precedente. A questo punto, l'applicazione contiene un token di accesso per l'API A (token A) con le attestazioni dell'utente e il consenso per accedere all'API Web di livello intermedio (API A). Verifica che il client richieda l'ambito user_impersonation nel token. A questo punto, l'API A deve effettuare una richiesta autenticata all'API Web downstream (API B).

I passaggi che seguono costituiscono il flusso OBO e vengono spiegati con l'aiuto del diagramma seguente.

1. L'applicazione client effettua una richiesta all'API A con il token A. Nota: durante la configurazione del flusso OBO in AD FS, verificare che sia selezionato l'ambito user_impersonation e che il client richieda l'ambito user_impersonation nella richiesta.
2. API A esegue l'autenticazione all'endpoint di rilascio del token AD FS e richiede un token per accedere all'API B. Nota: durante la configurazione di questo flusso in AD FS, assicurarsi che l'API A sia registrata anche come applicazione server con clientID con lo stesso valore dell'ID risorsa nell'API A.
3. L'endpoint di rilascio dei token AD FS convalida le credenziali dell'API A con il token A e rilascia il token di accesso per l'API B (token B).
4. Il token B è impostato nell'intestazione dell'autorizzazione della richiesta sull'API B.
5. I dati della risorsa protetta vengono restituiti dall'API B.

Richiesta del token di accesso da servizio a servizio

Per richiedere un token di accesso, effettua una richiesta HTTP POST all'endpoint del token AD FS con i parametri seguenti.

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

Per un segreto condiviso, una richiesta di token di accesso da servizio a servizio contiene i parametri seguenti:

Parametro	Obbligatorio/facoltativo	Descrizione
grant_type	necessario	Tipo della richiesta di token. Per una richiesta che usa un token JWT, il valore deve essere urn:ietf:params:oauth:grant-type:jwt-bearer.
client_id	necessario	ID client configurato per la registrazione della prima API Web come app server (app di livello intermedio). Deve corrispondere all'ID risorsa usato nella prima parte, ovvero all'URL della prima API Web.
client_secret	necessario	Segreto dell'applicazione creato durante la registrazione dell'app server in AD FS.
assertion	necessario	Valore del token usato nella richiesta.
requested_token_use	necessario	Specifica la modalità di elaborazione della richiesta. Nel flusso OBO il valore deve essere impostato su on_behalf_of
resource	necessario	ID risorsa fornito durante la registrazione della prima API Web come app server (app di livello intermedio). L'ID risorsa deve essere l'URL della seconda API Web che verrà chiamato dall'app di livello intermedio per conto del client.
ambito	facoltative	Elenco di ambiti separato da spazi per la richiesta di token.

Esempio

La richiesta HTTP POST seguente richiede un token di accesso e un token di aggiornamento

//line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid

Secondo caso: richiesta del token di accesso con un certificato

Una richiesta di token di accesso da servizio a servizio con un certificato contiene i parametri seguenti:

Parametro	Obbligatorio/facoltativo	Descrizione
grant_type	necessario	Tipo della richiesta di token. Per una richiesta che usa un token JWT, il valore deve essere urn:ietf:params:oauth:grant-type:jwt-bearer.
client_id	necessario	ID client configurato per la registrazione della prima API Web come app server (app di livello intermedio). Deve corrispondere all'ID risorsa usato nella prima parte, ovvero all'URL della prima API Web.
client_assertion_type	necessario	Il valore deve essere urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion	necessario	Asserzione (token Web JSON) che devi creare e firmare con il certificato registrato come credenziali per l'applicazione.
assertion	necessario	Valore del token usato nella richiesta.
requested_token_use	necessario	Specifica la modalità di elaborazione della richiesta. Nel flusso OBO il valore deve essere impostato su on_behalf_of
resource	necessario	ID risorsa fornito durante la registrazione della prima API Web come app server (app di livello intermedio). L'ID risorsa deve essere l'URL della seconda API Web che verrà chiamato dall'app di livello intermedio per conto del client.
ambito	facoltative	Elenco di ambiti separato da spazi per la richiesta di token.

Si noti che i parametri sono quasi uguali. Questo esempio è simile alla richiesta dal segreto condiviso, ad eccezione del fatto che il parametro client_secret viene sostituito da due parametri: client_assertion_type e client_assertion.

Esempio

La richiesta HTTP POST seguente richiede un token di accesso per l'API Web con un certificato.

// line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid

Risposta del token di accesso da servizio a servizio

Una risposta di esito positivo è una risposta OAuth 2.0 JSON con i parametri seguenti.

Parametro	Descrizione
token_type	Indica il valore del tipo di token. L'unico tipo supportato da AD FS è Bearer.
ambito	Ambito di accesso concesso nel token.
expires_in	Intervallo di tempo, in secondi, durante il quale il token di accesso è valido.
access_token	Token di accesso richiesto. Il servizio chiamante può usare questo token per l'autenticazione nel servizio ricevente.
id_token	Token JWT (JSON Web Token). L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per i limiti di autorizzazione o di sicurezza.
token di aggiornamento	Token di aggiornamento per il token di accesso richiesto. Il servizio chiamante può usare questo token per richiedere un altro token di accesso dopo la scadenza del token di accesso corrente.
Refresh_token_expires_in	Intervallo di tempo, in secondi, durante il quale il token di aggiornamento è valido.

Esempio di risposta di esito positivo

Nell'esempio seguente viene illustrata una risposta di esito positivo a una richiesta di un token di accesso per l'API Web.

{
  "token_type": "Bearer",
  "scope": openid,
  "expires_in": 3269,
  "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
  "id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
  "refresh_token": "OAQABAAAAAABnfiG…"
  "refresh_token_expires_in": 28800,
}

Usa il token di accesso per accedere alla risorsa protetta. Ora il servizio di livello intermedio può usare il token acquisito nell’esempio di risposta precedente per eseguire richieste autenticate all'API Web downstream, impostando il token nell'intestazione dell'autorizzazione.

Esempio

GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…

Flusso di concessione di credenziali client

Nota

Microsoft consiglia vivamente di eseguire la migrazione all'ID Microsoft Entra invece di eseguire l'aggiornamento a una versione più recente di AD FS. Per altre informazioni sul flusso di concessione delle credenziali client in Microsoft Entra ID, vedere Flusso di concessione delle credenziali client in Microsoft Identity Platform.

Per accedere alle risorse ospitate sul Web tramite l'identità di un'applicazione, è possibile usare la concessione di credenziali client OAuth 2.0 specificata in RFC 6749. Questo tipo di concessione viene comunemente usato per le interazioni da server a server che devono essere eseguite in background, senza l'interazione immediata con un utente. Questo tipo di applicazioni viene spesso definito daemon o account di servizio.

Il flusso di concessione di credenziali client OAuth 2.0 permette a un servizio Web (client riservato) di usare le proprie credenziali per l'autenticazione in caso di chiamata a un altro servizio Web, invece di rappresentare un utente. In questo scenario il client è in genere un servizio Web di livello intermedio, un servizio daemon o un sito Web. Per un livello di sicurezza più elevato, AD FS consente inoltre al servizio chiamante di usare come credenziali un certificato, anziché un segreto condiviso.

Diagramma del protocollo

Il diagramma seguente illustra il flusso di concessione delle credenziali client.

Richiedere un token

Per ottenere un token usando la concessione delle credenziali client, invia una richiesta POST all'endpoint /token di AD FS:

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

POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity

Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

Parametro	Obbligatorio/facoltativo	Descrizione
client_id	necessario	ID dell'applicazione (client) assegnato da AD FS all'app.
ambito	facoltative	Elenco separato da spazi di ambiti a cui si vuole che l'utente dia il consenso.
client_secret	necessario	Segreto client generato per l'app nel portale di registrazione delle app. Il segreto client deve essere codificato nell'URL prima dell'invio.
grant_type	necessario	Deve essere impostato su client_credentials.

Secondo caso: richiesta del token di accesso con un certificato

POST /adfs/oauth2/token HTTP/1.1

// Line breaks for clarity

Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&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	Obbligatorio/facoltativo	Descrizione
client_assertion_type	necessario	Il valore deve essere impostato su urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion	necessario	Asserzione (token Web JSON) che devi creare e firmare con il certificato registrato come credenziali per l'applicazione.
grant_type	necessario	Deve essere impostato su client_credentials.
client_id	facoltative	ID dell'applicazione (client) assegnato da AD FS all'app. Fa parte di client_assertion, quindi non è necessario passarlo qui.
ambito	facoltative	Elenco separato da spazi di ambiti a cui si vuole che l'utente dia il consenso.

Usare un token

Ora che hai acquisito un token, usalo per effettuare richieste alla risorsa. Alla scadenza del token, ripeti la richiesta all'endpoint /token per acquisire un nuovo token di accesso.

GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Flusso di concessione delle credenziali password del proprietario della risorsa (operazione non consigliata)

Nota

Microsoft consiglia vivamente di eseguire la migrazione all'ID Microsoft Entra invece di eseguire l'aggiornamento a una versione più recente di AD FS. Per altre informazioni sul flusso di concessione delle credenziali per la password del proprietario della risorsa in Microsoft Entra ID, vedere Flusso di concessione delle credenziali per la password del proprietario della risorsa in Microsoft Identity Platform.

La concessione delle credenziali password del proprietario della risorsa consente a un'applicazione di eseguire l'accesso dell'utente gestendo direttamente la password. Questo flusso richiede un elevato livello di attendibilità e di esposizione degli utenti ed è consigliabile usarlo solo quando non è possibile usare altri flussi, più sicuri.

Diagramma del protocollo

Il diagramma seguente mostra il flusso di concessione delle credenziali password del proprietario della risorsa.

Richiesta di autorizzazione

Il flusso di concessione delle credenziali password del proprietario della risorsa è una singola richiesta. Invia le credenziali dell'utente e di identificazione del client all'IDP e quindi riceve i token come restituzione. Prima di eseguire questa operazione, il client deve richiedere l'indirizzo di posta elettronica (UPN) e la password dell'utente. Subito dopo una richiesta con esito positivo, il client deve rilasciare in modo sicuro le credenziali dell'utente dalla memoria. Non deve mai salvarle.

// Line breaks and spaces are for legibility only.

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password

Parametro	Obbligatorio/facoltativo	Descrizione
client_id	necessario	Client ID
grant_type	necessario	Questo parametro deve essere impostato su password.
username	necessario	Indirizzo e-mail dell'utente
password	necessario	Password dell'utente.
ambito	facoltative	Elenco di ambiti separato da spazi.

Risposta di autenticazione di esito positivo

Nell'esempio seguente viene illustrata una risposta di token di esito positivo:

{
    "token_type": "Bearer",
    "scope": "openid",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}

Parametro	Descrizione
token_type	Questo parametro deve essere sempre impostato su Bearer.
ambito	Se è stato restituito un token di accesso, questo parametro elenca gli ambiti per i quali è valido il token di accesso.
expires_in	Numero di secondi durante i quali è valido il token di accesso incluso.
access_token	Emessa per gli ambiti che sono stati richiesti.
id_token	Token JWT (JSON Web Token). L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per i limiti di autorizzazione o di sicurezza.
refresh_token_expires_in	Numero di secondi durante i quali è valido il token di aggiornamento incluso.
token di aggiornamento	Viene rilasciato se il parametro scope originale include offline_access.

È possibile usare il token di aggiornamento per acquisire nuovi token di accesso e token di aggiornamento usando lo stesso flusso descritto nella sezione flusso di concessione del codice di autenticazione di questo articolo.

Flusso del codice del dispositivo

Nota

Microsoft consiglia vivamente di eseguire la migrazione all'ID Microsoft Entra invece di eseguire l'aggiornamento a una versione più recente di AD FS. Per altre informazioni sul flusso del codice del dispositivo nell'ID Microsoft Entra, vedere Flusso del codice del dispositivo in Microsoft Identity Platform.

La concessione del codice del dispositivo consente agli utenti di accedere a dispositivi con vincoli di input, ad esempio Smart TV, dispositivi IoT o stampanti. Per abilitare questo flusso, il dispositivo richiede all'utente di visitare una pagina Web nel browser di un altro dispositivo per eseguire l'accesso. Dopo che l'utente ha eseguito l'accesso, il dispositivo è in grado di ottenere i token di accesso e i token di aggiornamento in base alle esigenze.

Diagramma del protocollo

L'intero flusso del codice del dispositivo ha un aspetto simile al diagramma seguente. Ciascuno di questi passaggi viene descritto più avanti in questo articolo.

Richiesta di autorizzazione per il dispositivo

Il client deve prima cercare con il server di autenticazione un dispositivo e un codice utente usato per avviare l'autenticazione. Il client raccoglie la richiesta dall'endpoint /devicecode. In questa richiesta il client deve anche includere le autorizzazioni che deve acquisire dall'utente. Dal momento dell'invio della richiesta, l'utente ha solo 15 minuti per accedere (il valore abituale per expires_in), pertanto effettua questa richiesta solo quando l'utente ha indicato di essere pronto per l'accesso.

// Line breaks are for legibility only.

POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
scope=openid

Parametro	Condizione	Descrizione
client_id	necessario	ID dell'applicazione (client) assegnato da AD FS all'app.
ambito	facoltative	Elenco di ambiti separato da spazi.

Risposta di autorizzazione per il dispositivo

Una risposta di esito positivo sarà un oggetto JSON contenente le informazioni necessarie per consentire all'utente di eseguire l'accesso.

Parametro	Descrizione
device_code	Stringa lunga usata per verificare la sessione tra il client e il server di autorizzazione. Il client usa questo parametro per richiedere al server di autorizzazione il token di accesso.
user_code	Stringa breve mostrata all'utente e usata per identificare la sessione in un dispositivo secondario.
verification_uri	URI a cui l'utente deve accedere con user_code per eseguire l'accesso.
verification_uri_complete	URI a cui l'utente deve accedere con user_code per eseguire l'accesso. Questo parametro è precompilato con user_code in modo che l'utente non debba immettere tale valore
expires_in	Numero di secondi prima della scadenza di device_code e user_code.
interval	Numero di secondi di attesa del client tra le richieste di polling.
messaggio	Stringa leggibile con le istruzioni per l'utente. Può essere localizzata includendo un parametro di query nella richiesta del modulo ?mkt=xx-XX, specificando il codice delle impostazioni cultura della lingua appropriato.

Autenticazione dell'utente

Dopo aver ricevuto user_code e verification_uri, il client li mostra all'utente, indicandogli di eseguire l'accesso con il browser del telefono cellulare o del PC. Inoltre, il client può usare un codice QR o un meccanismo simile per visualizzare il parametro verfication_uri_complete, che eseguirà il passaggio di immissione del valore user_code per l'utente. Mentre l'utente esegue l'autenticazione nel verification_uri, il client deve eseguire il polling dell'endpoint /token per il token richiesto usando il device_code.

POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 00001111-aaaa-2222-bbbb-3333cccc4444
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8

Parametro	necessario	Descrizione
grant_type	necessario	Deve essere urn:ietf:params:oauth:grant-type:device_code
client_id	necessario	Deve corrispondere al valore client_id usato nella richiesta iniziale.
codice	necessario	Valore device_code restituito nella richiesta di autorizzazione per il dispositivo.

Risposta di autenticazione di esito positivo

Una risposta di token con esito positivo ha un aspetto simile al seguente:

Parametro	Descrizione
token_type	Sempre "Bearer".
ambito	Se è stato restituito un token di accesso, questo parametro elenca gli ambiti per i quali è valido il token di accesso.
expires_in	Numero di secondi durante i quali è valido il token di accesso incluso.
access_token	Emessa per gli ambiti che sono stati richiesti.
id_token	Viene rilasciato se il parametro scope originale include l'ambito openid.
token di aggiornamento	Viene rilasciato se il parametro scope originale include offline_access.
refresh_token_expires_in	Numero di secondi durante i quali è valido il token di aggiornamento incluso.

Contenuto correlato

Per l'elenco completo degli articoli con le procedure, vedi Sviluppo in AD FS, che fornisce istruzioni dettagliate sull'uso dei flussi correlati.