Richieste di attestazioni e funzionalità client

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:

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"]}}}

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

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

const msalConfig = {
    auth: {
        clientId: 'Enter_the_Application_Id_Here', 
        clientCapabilities: ["CP1"]
        // remaining settings...
    }
}

const msalInstance = new msal.PublicClientApplication(msalConfig);

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_cc'attestazione facoltativa, il manifesto dell'app diventa 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");
}

const checkIsClientCapableOfClaimsChallenge = (req, res, next) => {
    // req.authInfo contains the decoded access token payload
    if (req.authInfo['xms_cc'] && req.authInfo['xms_cc'].includes('CP1')) {
          // Return formatted claims challenge as this client understands this
    } else {
          return res.status(403).json({ error: 'Client is not capable' });
    }
}

Esempi di codice

• Abilitare l'applicazione a pagina singola Angular per accedere agli utenti e chiamare Microsoft Graph
• Abilitare l'applicazione a pagina singola React per accedere agli utenti e chiamare Microsoft Graph
• Abilitare l'app Web ASP.NET Core per accedere agli utenti e chiamare Microsoft Graph

Passaggi successivi

• Flusso del codice di autorizzazione OAuth 2.0 e Microsoft Identity Platform
• Come usare le API abilitate per la valutazione continua dell'accesso nelle applicazioni
• Accesso condizionale granulare per dati e azioni sensibili