Problémy s deklaracemi identity, žádosti o deklarace identity a možnosti klienta

Výzva deklarací identity je odpověď odeslaná z rozhraní API, která indikuje, že přístupový token odeslaný klientskou aplikací nemá dostatek deklarací identity. Důvodem může být to, že token nevyhovuje zásadám podmíněného přístupu nastaveným pro toto rozhraní API nebo byl přístupový token odvolán.

Žádost o deklarace identity provádí klientská aplikace, aby přesměrovala uživatele zpět na zprostředkovatele identity, aby načetla nový token s deklaracemi, které splňují ostatní požadavky, které nebyly splněny.

Aplikace, které používají vylepšené funkce zabezpečení, jako je průběžné vyhodnocování přístupu (CAE) a kontext ověřování podmíněného přístupu, musí být připravené na řešení problémů s deklaracemi identity.

Vaše aplikace dostává problémy s deklaracemi identity z oblíbených služeb, jako je Microsoft Graph, pouze pokud deklaruje možnosti klienta ve svých voláních služby.

Formát hlavičky výzvy deklarací

Výzva deklarací identity je direktiva www-authenticate jako hlavička vrácená rozhraním API, když přístupový token předaný není autorizovaný a vyžaduje se nový přístupový token se správnými možnostmi. Výzva deklarací identity se skládá z několika částí: stavový kód HTTP odpovědi a hlavičky www-authenticate , která má více částí a musí obsahovat direktivu deklarací identity.

Tady je příklad:

HTTP 401; Unauthorized

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

Stavový kód HTTP: Musí být 401 Neautorizováno.

hlavička odpovědi www-authenticate obsahující:

Parametr	Povinné nebo volitelné	Popis
Authentication type	Požaduje se	Musí být nosný.
Sféra	Volitelné	Id tenanta nebo název domény tenanta (například microsoft.com), ke které se přistupuje. V případě, že ověřování prochází společným koncovým bodem, musí být prázdný řetězec.
authorization_uri	Požaduje se	Identifikátor URI koncového authorize bodu, kde je možné v případě potřeby provést interaktivní ověřování. Pokud jsou zadané v sférách, musí být informace o tenantovi zahrnuty do authorization_uri. Pokud je sféra prázdný řetězec, authorization_uri MUSÍ být proti společnému koncovému bodu.
error	Požaduje se	Při generování výzvy deklarací identity musí být "insufficient_claims".
claims	Vyžaduje se, pokud je chyba "insufficient_claims".	Řetězec s uvozovou sadou obsahující požadavek deklarací deklarací identity s kódováním base 64. Žádost o deklarace identity by měla požadovat deklarace identity pro "access_token" na nejvyšší úrovni objektu JSON. Hodnota (požadované deklarace identity) bude závislá na kontextu a bude zadána dále v tomto dokumentu. Z důvodů velikosti by aplikace předávající strany měly před kódováním base 64 minifikovat JSON. Nezpracovaný KÓD JSON výše uvedeného příkladu je {"access_token":{"acrs":{"essential":true,"value":"cp1"}}}.

Odpověď 401 může obsahovat více než jednu www-authenticate hlavičku. Všechna pole v předchozí tabulce musí být obsažena ve stejné www-authenticate hlavičce. Hlavička www-authenticate obsahující výzvu deklarací identity může obsahovat další pole. Pole v záhlaví nejsou seřazená. Podle RFC 7235 musí každý název parametru nastat pouze jednou na výzvu schématu ověřování.

Žádost o deklarace identity

Když aplikace obdrží výzvu deklarací identity, znamená to, že předchozí přístupový token už není považován za platný. V tomto scénáři by aplikace měla token vymazat z jakékoli místní mezipaměti nebo uživatelské relace. Pak by měl přihlášeného uživatele přesměrovat zpět na MICROSOFT Entra ID a načíst nový token pomocí toku autorizačního kódu OAuth 2.0 s parametrem deklarací identity , který bude splňovat další požadavky, které nebyly splněny.

Tady je příklad:

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

Výzva deklarací identity by měla být předána jako součást všech volání koncového bodu Microsoft Entra /authorize , dokud se token úspěšně nenačte. Po načtení tokenu už není potřeba.

K naplnění parametru deklarací identity musí vývojář:

1. Dekódujte dříve přijatý řetězec base64.
2. Řetězec zakódujte pomocí adresy URL a znovu ho přidejte do parametru deklarací identity .

Po dokončení tohoto toku obdrží aplikace přístupový token, který má další deklarace identity, které dokládají, že uživatel splnil požadované podmínky.

Možnosti klienta

Možnosti klienta pomáhají poskytovateli prostředků, jako je webové rozhraní API, zjistit, jestli volající klientská aplikace rozumí výzvě deklarací identity a pak může odpovídajícím způsobem přizpůsobit svou odpověď. Tato funkce může být užitečná, když ne všichni klienti rozhraní API dokážou zpracovat problémy s deklaracemi identity a některé starší verze stále očekávají jinou odpověď.

Některé oblíbené aplikace, jako je Microsoft Graph , odesílají problémy s deklaracemi identity jenom v případě, že volající klientská aplikace deklaruje, že je dokáže zpracovat pomocí funkcí klienta.

Aby se zabránilo dalšímu provozu nebo dopadům na uživatelské prostředí, Microsoft Entra ID nepředpokládá, že vaše aplikace dokáže zpracovat deklarace identity, pokud se výslovně nepřihlásíte. Aplikace nebude dostávat problémy s deklaracemi identity (a nebude moct používat související funkce, jako jsou tokeny CAE), pokud deklaruje, že je připravená je zpracovat pomocí funkce cp1.

Komunikace schopností klienta s ID Microsoft Entra

Následující příklad parametr deklarací identity ukazuje, jak klientská aplikace komunikuje s Microsoft Entra ID v toku autorizačního kódu OAuth 2.0.

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

.NET

Pokud používáte knihovnu MSAL, použijte následující kód:

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

Ti, kteří používají Microsoft.Identity.Web, mohou do konfiguračního souboru přidat následující kód:

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

JavaScript

Ti, kteří používají MSAL.js nebo UZEL MSAL, mohou do objektu konfigurace přidat clientCapabilities vlastnost. Poznámka: Tato možnost je dostupná pro veřejné i důvěrné klientské aplikace.

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

const msalInstance = new msal.PublicClientApplication(msalConfig);

Podívejte se na následující fragment kódu a podívejte se na ukázkový požadavek na ID Microsoft Entra:

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

Pokud už máte existující datovou část pro parametr deklarací identity, přidejte ji do existující sady.

Pokud už například máte následující odpověď z operace ověřování přístupu k podmínce;

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

V existující datové části deklarací identity byste předplatili funkci klienta.

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

Příjem deklarace identity xms_cc v přístupového tokenu

Aby bylo možné získat informace o tom, jestli klientské aplikace můžou zpracovávat problémy s deklaracemi, musí implementátor rozhraní API požadovat xms_cc jako volitelnou deklaraci identity v manifestu aplikace.

Deklarace identity xms_cc s hodnotou "cp1" v přístupovém tokenu je autoritativní způsob, jak identifikovat klientskou aplikaci, která dokáže zpracovat výzvu deklarací identity. xms_cc je volitelná deklarace identity, která nebude v přístupovém tokenu vždy vydána, i když klient odešle žádost o deklarace identity s "xms_cc". Aby přístupový token obsahoval deklaraci identity xms_cc , musí aplikace prostředků (tj. implementátor rozhraní API) požadovat xms_cc jako volitelnou deklaraci identity v manifestu aplikace. Pokud se požaduje jako volitelná deklarace identity, xms_cc se přidá do přístupového tokenu jenom v případě, že klientská aplikace odešle xms_cc v žádosti o deklarace identity. Hodnota požadavku na deklaraci identity xms_cc je zahrnuta jako hodnota deklarace identity xms_cc v přístupovém tokenu, pokud se jedná o známou hodnotu. Jediná aktuálně známá hodnota je cp1.

U hodnot se nerozlišují malá a velká a neuspořádaná. Pokud je v požadavku na deklaraci identity xms_cc zadáno více než jedna hodnota, budou tyto hodnoty vícehodnotovou kolekcí jako hodnota deklarace identity xms_cc .

Jako příklad použijte následující požadavek:

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

Výsledkem je deklarace následujícího fragmentu kódu v přístupovém tokenu, pokud jsou známé možnosti cp1, foo a bar .

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

Po vyžádání xms_ccvolitelné deklarace identity se manifest aplikace změní tak, aby vypadal takto:

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

Rozhraní API pak může přizpůsobit odpovědi na základě toho, jestli klient dokáže zpracovat výzvu deklarací identity, nebo ne.

.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

Následující fragment kódu znázorňuje vlastní middleware Express.js:

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

Ukázky kódu

• Povolení jednostránkakové aplikace Angular pro přihlášení uživatelů a volání Microsoft Graphu
• Povolení jednostránka aplikace React pro přihlášení uživatelů a volání Microsoft Graphu
• Povolení webové aplikace ASP.NET Core pro přihlášení uživatelů a volání Microsoft Graphu

Další kroky

• Microsoft Identity Platform a tok autorizačního kódu OAuth 2.0
• Jak ve svých aplikacích používat rozhraní API s podporou průběžného vyhodnocování přístupu
• Podrobný podmíněný přístup pro citlivá data a akce