Share via

Richieste di attestazioni e funzionalità client

  • Articolo

Una richiesta di attestazioni è una risposta inviata da un'API che indica che un token di accesso inviato da un'applicazione client non ha attestazioni sufficienti. Ciò può essere dovuto al fatto che il token non soddisfa i criteri di accesso condizionale impostati per tale API o che il token di accesso è stato revocato.

Una richiesta di attestazioni viene effettuata dall'applicazione client per reindirizzare l'utente al provider di identità per recuperare un nuovo token con attestazioni che soddisfano gli altri requisiti non soddisfatti.

Le applicazioni che usano funzionalità di sicurezza avanzate come la valutazione dell'accesso continuo (CAE) e il contesto di autenticazione dell'accesso condizionale devono essere preparate per gestire le richieste di attestazioni.

L'applicazione riceve richieste di attestazioni dai servizi più diffusi, ad esempio Microsoft Graph , solo se dichiara le sue funzionalità client nelle chiamate al servizio.

Formato dell'intestazione della richiesta di attestazioni

La richiesta di attestazioni è una direttiva come www-authenticate intestazione restituita da un'API quando un token di accesso presentato non è autorizzato e viene richiesto un nuovo token di accesso con le funzionalità appropriate. La richiesta di attestazioni comprende più parti: il codice di stato HTTP della risposta e l'intestazione www-authenticate , che ha più parti e deve contenere una direttiva claims.

Ecco un esempio:

HTTP 401; Unauthorized

www-authenticate =Bearer realm="", authorization_uri="https://login.microsoftonline.com/common/oauth2/authorize", error="insufficient_claims", claims="eyJhY2Nlc3NfdG9rZW4iOnsiYWNycyI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlIjoiY3AxIn19fQ=="

Codice di stato HTTP: deve essere 401 Non autorizzato.

intestazione della risposta www-authenticate contenente:

Parametro Obbligatoria/facoltativa Descrizione
Authentication type Richiesto Deve essere Bearer.
Realm Facoltativo Id tenant o nome di dominio tenant (ad esempio, microsoft.com) a cui si accede. DEVE essere una stringa vuota nel caso in cui l'autenticazione passa attraverso l'endpoint comune.
authorization_uri Richiesto URI dell'endpoint authorize in cui è possibile eseguire un'autenticazione interattiva, se necessario. Se specificato nell'area di autenticazione, le informazioni sul tenant devono essere incluse nella authorization_uri. Se realm è una stringa vuota, il authorization_uri DEVE essere rispetto all'endpoint comune.
error Richiesto Deve essere "insufficient_claims" quando deve essere generata una richiesta di attestazioni.
claims Obbligatorio quando l'errore è "insufficient_claims". Stringa tra virgolette contenente una richiesta di attestazioni con codifica base 64. La richiesta di attestazioni deve richiedere attestazioni per il "access_token" al livello superiore dell'oggetto JSON. Il valore (attestazioni richieste) sarà dipendente dal contesto e specificato più avanti in questo documento. Per motivi di dimensioni, le applicazioni relying party DOVREBBERO minificare il codice JSON prima della codifica base 64. Il codice JSON non elaborato dell'esempio precedente è {"access_token":{"acrs":{"essential":true,"value":"cp1"}}}.

La risposta 401 può contenere più intestazioni www-authenticate . Tutti i campi della tabella precedente devono essere contenuti nella stessa www-authenticate intestazione. L'intestazione www-authenticate che contiene la richiesta di verifica delle attestazioni può contenere altri campi. I campi nell'intestazione non sono ordinati. In base a RFC 7235, ogni nome di parametro deve verificarsi una sola volta per ogni richiesta di schema di autenticazione.

Richiesta di attestazioni

Quando un'applicazione riceve una richiesta di verifica delle attestazioni, indica che il token di accesso precedente non è più considerato valido. In questo scenario, l'applicazione deve cancellare il token da qualsiasi cache locale o sessione utente. Quindi, dovrebbe reindirizzare l'utente connesso a Microsoft Entra ID per recuperare un nuovo token usando il flusso del codice di autorizzazione OAuth 2.0 con un parametro di attestazione che soddisfa gli altri requisiti che non sono stati soddisfatti.

Ecco un esempio:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22acrs%22%3A%7B%22essential%22%3Atrue%2C%22value%22%3A%22c1%22%7D%7D%7D

La richiesta di verifica delle attestazioni deve essere passata come parte di tutte le chiamate a un endpoint Microsoft Entra /authorize fino a quando non viene recuperato correttamente un token. Dopo aver recuperato il token, non è più necessario.

Per popolare il parametro delle attestazioni, lo sviluppatore deve:

  1. Decodificare la stringa base64 ricevuta in precedenza.
  2. Codificare l'URL per la stringa e aggiungerla di nuovo al parametro delle attestazioni .

Al termine di questo flusso, l'applicazione riceve un token di accesso con le altre attestazioni che dimostrano che l'utente ha soddisfatto le condizioni necessarie.

Funzionalità client

Le funzionalità client consentono a un provider di risorse come un'API Web di rilevare se l'applicazione client chiamante riconosce la richiesta di attestazioni e può quindi personalizzare la risposta di conseguenza. Questa funzionalità può essere utile quando non tutti i client API sono in grado di gestire i problemi di attestazione e alcune versioni precedenti prevedono comunque una risposta diversa.

Alcune applicazioni popolari come Microsoft Graph inviano richieste di attestazioni solo se l'app client chiamante dichiara che è in grado di gestirle usando le funzionalità client.

Per evitare traffico aggiuntivo o impatto sull'esperienza utente, Microsoft Entra ID non presuppone che l'app possa gestire le attestazioni richieste, a meno che non si acconsenta esplicitamente. Un'applicazione non riceverà richieste di attestazioni (e non sarà in grado di usare le funzionalità correlate, ad esempio i token CAE), a meno che non dichiari che sia pronta per gestirle con la funzionalità "cp1".

Come comunicare le funzionalità client con Microsoft Entra ID

Il parametro di attestazioni di esempio seguente mostra come un'applicazione client comunica la sua funzionalità con l'ID Microsoft Entra in un flusso di codice di autorizzazione OAuth 2.0.

Claims: {"access_token":{"xms_cc":{"values":["cp1"]}}}

Usare il codice seguente se si usa la libreria MSAL:

_clientApp = PublicClientApplicationBuilder.Create(App.ClientId)
 .WithDefaultRedirectUri()
 .WithAuthority(authority)
 .WithClientCapabilities(new [] {"cp1"})
 .Build();

Gli utenti che usano Microsoft.Identity.Web possono aggiungere il codice seguente al file di configurazione:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": 'Enter_the_Application_Id_Here' 
    "ClientCapabilities": [ "cp1" ],
    // remaining settings...
},

Fare riferimento al frammento di codice seguente per visualizzare una richiesta di esempio per Microsoft Entra ID:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22xms_cc%22%3A%7B%22values%22%3A%5B%22cp1%22%5D%7D%7D%7D

Quando si dispone già di un payload esistente per il parametro delle attestazioni, è necessario aggiungerlo al set esistente.

Ad esempio, se si ha già la risposta seguente da un'operazione di contesto di autenticazione dell'accesso condizionale;

{"access_token":{"acrs":{"essential":true,"value":"c25"}}}

Si anteponeva la funzionalità client nel payload delle attestazioni esistente.

{"access_token":{"xms_cc":{"values":["cp1"]},"acrs":{"essential":true,"value":"c25"}}}

Ricezione dell'attestazione xms_cc in un token di accesso

Per ricevere informazioni sul fatto che le applicazioni client possano gestire le richieste di attestazioni, un implementatore dell'API deve richiedere xms_cc come attestazione facoltativa nel manifesto dell'applicazione.

L'attestazione xms_cc con valore "cp1" nel token di accesso è il modo autorevole per identificare un'applicazione client è in grado di gestire una richiesta di attestazioni. xms_cc è un'attestazione facoltativa che non verrà sempre rilasciata nel token di accesso, anche se il client invia una richiesta di attestazioni con "xms_cc". Affinché un token di accesso contenga l'attestazione xms_cc , l'applicazione della risorsa (ovvero l'implementatore api) deve richiedere xms_cc come attestazione facoltativa nel manifesto dell'applicazione. Quando richiesto come attestazione facoltativa, xms_cc viene aggiunto al token di accesso solo se l'applicazione client invia xms_cc nella richiesta di attestazioni. Il valore della richiesta di attestazione xms_cc è incluso come valore dell'attestazione xms_cc nel token di accesso, se si tratta di un valore noto. L'unico valore attualmente noto è cp1.

I valori non fanno distinzione tra maiuscole e minuscole e non sono ordinati. Se nella richiesta di attestazione xms_cc viene specificato più di un valore, tali valori saranno una raccolta multivalore come valore dell'attestazione xms_cc .

Si prenda la richiesta seguente come esempio:

{ "access_token": { "xms_cc":{"values":["cp1","foo", "bar"] } }}

Ciò comporta un'attestazione del frammento di codice seguente nel token di accesso, se cp1, foo e bar sono funzionalità note.

"xms_cc": ["cp1", "foo", "bar"]

Dopo aver richiesto il xms_ccattestazione facoltativa, il manifesto dell'app cambia in modo che abbia un aspetto simile al seguente:

"optionalClaims":
{
    "accessToken": [
    {
        "additionalProperties": [],
        "essential": false,
        "name": "xms_cc",
        "source": null
    }],
    "idToken": [],
    "saml2Token": []
}

L'API può quindi personalizzare le risposte in base al fatto che il client sia in grado di gestire o meno la richiesta di attestazioni.

Claim ccClaim = context.User.FindAll(clientCapabilitiesClaim).FirstOrDefault(x => x.Type == "xms_cc");
if (ccClaim != null && ccClaim.Value == "cp1")
{
    // Return formatted claims challenge as this client understands this
}
else
{
    // Throw generic exception
    throw new UnauthorizedAccessException("The caller does not meet the authentication bar to carry our this operation. The service cannot allow this operation");
}

Esempi di codice

Passaggi successivi