Problemen met claims, aanvragen van claims en clientmogelijkheden

Een claimvraag is een antwoord dat is verzonden vanuit een API die aangeeft dat een toegangstoken dat is verzonden door een clienttoepassing onvoldoende claims heeft. Dit kan zijn omdat het token niet voldoet aan het beleid voor voorwaardelijke toegang dat is ingesteld voor die API of omdat het toegangstoken is ingetrokken.

Er wordt een claimaanvraag gedaan door de clienttoepassing om de gebruiker terug te leiden naar de id-provider om een nieuw token op te halen met claims die voldoen aan de andere vereisten waaraan niet is voldaan.

Toepassingen die gebruikmaken van verbeterde beveiligingsfuncties, zoals CONTINUOUS Access Evaluation (CAE) en verificatiecontext voor voorwaardelijke toegang, moeten worden voorbereid voor het afhandelen van problemen met claims.

Uw toepassing ontvangt alleen claims van populaire services zoals Microsoft Graph als deze de clientmogelijkheden declareert in de aanroepen naar de service.

Header-indeling van claimuitdaging

De claimvraag is een instructie als een www-authenticate header die wordt geretourneerd door een API wanneer een toegangstoken dat eraan wordt gepresenteerd niet is geautoriseerd en er in plaats daarvan een nieuw toegangstoken met de juiste mogelijkheden is vereist. De claimvraag bestaat uit meerdere onderdelen: de HTTP-statuscode van het antwoord en de www-authenticate header, die zelf meerdere onderdelen heeft en een claimrichtlijn moet bevatten.

Hier volgt een voorbeeld:

HTTP 401; Unauthorized

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

HTTP-statuscode: moet 401 niet geautoriseerd zijn.

www-authenticate response header met:

Parameter	Vereist/optioneel	Description
Authentication type	Vereist	Moet Bearer zijn .
Realm	Optioneel	De tenant-id of tenantdomeinnaam (bijvoorbeeld microsoft.com) die wordt geopend. MOET een lege tekenreeks zijn in het geval dat de verificatie het algemene eindpunt doorloopt.
authorization_uri	Vereist	De URI van het authorize eindpunt waar een interactieve verificatie kan worden uitgevoerd, indien nodig. Indien opgegeven in realm, moeten de tenantgegevens worden opgenomen in de authorization_uri. Als realm een lege tekenreeks is, moet de authorization_uri tegen het algemene eindpunt zijn.
error	Vereist	Moet 'insufficient_claims' zijn wanneer een claimvraag moet worden gegenereerd.
claims	Vereist wanneer de fout 'insufficient_claims' is.	Een tekenreeks tussen aanhalingstekens met een met base 64 gecodeerde claimaanvraag. De claimaanvraag moet claims aanvragen voor de 'access_token' op het hoogste niveau van het JSON-object. De waarde (aangevraagde claims) is contextafhankelijk en later in dit document opgegeven. Om grootteredenen moeten relying party-toepassingen de JSON minificeren vóór base 64-codering. De onbewerkte JSON van het bovenstaande voorbeeld is {"access_token":{"acrs":{"essential":true,"value":"cp1"}}}.

Het 401-antwoord kan meerdere www-authenticate headers bevatten. Alle velden in de voorgaande tabel moeten zich in dezelfde www-authenticate koptekst bevinden. De www-authenticate header die de claimvraag bevat, kan andere velden bevatten. Velden in de koptekst zijn niet gerangschikt. Volgens RFC 7235 moet elke parameternaam slechts één keer per verificatieschema worden uitgevoerd.

Claimaanvraag

Wanneer een toepassing een claimvraag ontvangt, geeft dit aan dat het voorgaande toegangstoken niet langer als geldig wordt beschouwd. In dit scenario moet de toepassing het token wissen uit een lokale cache of gebruikerssessie. Vervolgens moet de aangemelde gebruiker worden omgeleid naar Microsoft Entra-id om een nieuw token op te halen met behulp van de OAuth 2.0-autorisatiecodestroom met een claimparameter die voldoet aan de andere vereisten waaraan niet is voldaan.

Hier volgt een voorbeeld:

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

De claimvraag moet worden doorgegeven als onderdeel van alle aanroepen naar een Microsoft Entra /autoriseren-eindpunt totdat een token is opgehaald. Nadat het token is opgehaald, is het niet meer nodig.

Om de parameter claims te vullen, moet de ontwikkelaar het volgende doen:

1. Decoderen van de base64-tekenreeks die u eerder hebt ontvangen.
2. Url-codeer de tekenreeks en voeg deze opnieuw toe aan de parameter claims .

Na voltooiing van deze stroom ontvangt de toepassing een toegangstoken met de andere claims die aantonen dat de gebruiker aan de vereiste voorwaarden voldoet.

Clientmogelijkheden

Clientmogelijkheden helpen een resourceprovider, zoals een web-API, te detecteren of de aanroepende clienttoepassing de claimvraag begrijpt en vervolgens het bijbehorende antwoord kan aanpassen. Deze mogelijkheid kan handig zijn wanneer niet alle API-clients claimuitdagingen kunnen afhandelen en sommige eerdere versies nog steeds een ander antwoord verwachten.

Sommige populaire toepassingen, zoals Microsoft Graph , verzenden alleen claims als de aanroepende client-app verklaart dat deze kunnen worden verwerkt met behulp van clientmogelijkheden.

Om extra verkeer of gevolgen voor de gebruikerservaring te voorkomen, gaat Microsoft Entra ID er niet van uit dat uw app claims kan verwerken die worden betwist, tenzij u zich expliciet aanmeldt. Een toepassing ontvangt geen problemen met claims (en kan de gerelateerde functies zoals CAE-tokens niet gebruiken) tenzij deze declareert dat deze gereed is om ze af te handelen met de cp1-mogelijkheid.

Clientmogelijkheden communiceren met Microsoft Entra ID

In de volgende voorbeeldclaimparameter ziet u hoe een clienttoepassing de mogelijkheid communiceert met Microsoft Entra-id in een OAuth 2.0-autorisatiecodestroom.

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

.NET

Gebruik de volgende code als u de MSAL-bibliotheek gebruikt:

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

Degenen die Microsoft.Identity.Web gebruiken, kunnen de volgende code toevoegen aan het configuratiebestand:

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

JavaScript

Degenen die MSAL.js of MSAL Node gebruiken, kunnen eigenschap toevoegen clientCapabilities aan het configuratieobject. Opmerking: deze optie is beschikbaar voor zowel openbare als vertrouwelijke clienttoepassingen.

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

const msalInstance = new msal.PublicClientApplication(msalConfig);

Raadpleeg het volgende codefragment om een voorbeeldaanvraag voor Microsoft Entra-id te zien:

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

Wanneer u al een bestaande nettolading voor claimparameter hebt, voegt u deze toe aan de bestaande set.

Als u bijvoorbeeld al het volgende antwoord hebt van een contextbewerking voor toegang tot voorwaarde;

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

U zou de clientmogelijkheid vooraf laten gaan in de bestaande nettolading van claims .

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

Xms_cc claim ontvangen in een toegangstoken

Als u informatie wilt ontvangen over of clienttoepassingen claims kunnen afhandelen, moet een API-implementer xms_cc aanvragen als een optionele claim in het toepassingsmanifest.

De xms_cc claim met een waarde 'cp1' in het toegangstoken is de gezaghebbende manier om een clienttoepassing te identificeren die een claimvraag kan afhandelen. xms_cc is een optionele claim die niet altijd wordt uitgegeven in het toegangstoken, zelfs als de client een claimaanvraag verzendt met 'xms_cc'. Als een toegangstoken de xms_cc claim moet bevatten, moet de resourcetoepassing (dat wil zeggen de API-implementer) xms_cc aanvragen als een optionele claim in het toepassingsmanifest. Wanneer dit wordt aangevraagd als een optionele claim, wordt xms_cc alleen toegevoegd aan het toegangstoken als de clienttoepassing xms_cc in de claimaanvraag verzendt. De waarde van de xms_cc claimaanvraag wordt opgenomen als de waarde van de xms_cc claim in het toegangstoken, als dit een bekende waarde is. De enige bekende waarde is cp1.

De waarden zijn niet hoofdlettergevoelig en ongeordeerd. Als er meer dan één waarde is opgegeven in de xms_cc claimaanvraag, zijn deze waarden een verzameling met meerdere waarden als de waarde van de xms_cc claim.

Neem de volgende aanvraag als voorbeeld:

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

Dit resulteert in een claim van het volgende fragment in het toegangstoken, als cp1, foo en balk bekende mogelijkheden zijn.

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

Nadat de xms_cc optionele claim is aangevraagd, worden de manifestwijzigingen van de app als volgt weergegeven:

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

De API kan vervolgens hun antwoorden aanpassen op basis van of de client in staat is om claims te verwerken of niet.

.NET

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");
}

JavaScript

Het volgende fragment illustreert een aangepaste Express.js middleware:

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' });
    }
}

Codevoorbeelden

• Uw Angular-toepassing met één pagina inschakelen om gebruikers aan te melden en Microsoft Graph aan te roepen
• Uw React-toepassing met één pagina inschakelen om gebruikers aan te melden en Microsoft Graph aan te roepen
• Uw ASP.NET Core-web-app inschakelen om gebruikers aan te melden en Microsoft Graph aan te roepen

Volgende stappen

• Microsoft identity platform en OAuth 2.0-autorisatiecodestroom
• API's met continue toegangsevaluatie gebruiken in uw toepassingen
• Gedetailleerde voorwaardelijke toegang voor gevoelige gegevens en acties