Jogcímekkel kapcsolatos kihívások, jogcímkérelmek és ügyfélképességek

A jogcímekkel kapcsolatos kihívás egy API-ból küldött válasz, amely azt jelzi, hogy az ügyfélalkalmazás által küldött hozzáférési jogkivonat nem rendelkezik megfelelő jogcímekkel. Ennek az lehet az oka, hogy a jogkivonat nem felel meg az ADOTT API-hoz beállított feltételes hozzáférési szabályzatoknak, vagy a hozzáférési jogkivonatot visszavonták.

Az ügyfélalkalmazás egy jogcímkérelmet küld , amely átirányítja a felhasználót az identitásszolgáltatóhoz, hogy lekérjen egy új jogkivonatot olyan jogcímekkel, amelyek megfelelnek az egyéb követelményeknek, amelyek nem teljesültek.

Az olyan továbbfejlesztett biztonsági funkciókat használó alkalmazásokat, mint a folyamatos hozzáférés-kiértékelés (CAE) és a feltételes hozzáférés hitelesítési környezete , fel kell készülni a jogcímekkel kapcsolatos kihívások kezelésére.

Az alkalmazás csak akkor kap jogcímkérdéseket a népszerű szolgáltatásoktól, például a Microsoft Graphtól , ha deklarálja az ügyfélképességeit a szolgáltatáshoz intézett hívásaiban.

Jogcím-kihívás fejlécének formátuma

A jogcímekkel kapcsolatos kihívás egy olyan fejléc, www-authenticate amelyet egy API visszaad, ha a hozzáférési jogkivonat nincs engedélyezve, és ehelyett egy új, megfelelő képességekkel rendelkező hozzáférési jogkivonatra van szükség. A jogcímekkel kapcsolatos kihívás több részből áll: a válasz HTTP-állapotkódja és a www-authenticate fejléc, amelynek maga több részből áll, és tartalmaznia kell egy jogcím-irányelvet.

Példa:

HTTP 401; Unauthorized

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

HTTP-állapotkód: 401 jogosulatlannak kell lennie.

a következőt tartalmazó www-authenticate válaszfejléc :

Paraméter	Kötelező/nem kötelező	Leírás
Hitelesítés típusa	Kötelező	Tulajdonosnak kell lennie .
Tartomány	Választható	A bérlőazonosító vagy a bérlői tartománynév (például microsoft.com) elérése folyamatban van. Üres sztringnek kell lennie abban az esetben, ha a hitelesítés a közös végponton megy keresztül.
authorization_uri	Kötelező	Annak a végpontnak az authorize URI-ja, ahol szükség esetén interaktív hitelesítés végezhető el. Ha a tartományon belül van megadva, a bérlő adatait fel kell venni a authorization_uri. Ha a tartomány üres sztring, a authorization_uri a közös végponton kell lennie.
error	Kötelező	"insufficient_claims" értékűnek kell lennie, ha jogcímekkel kapcsolatos kihívást kell létrehozni.
claims	"insufficient_claims" hiba esetén szükséges.	Idézett sztring, amely egy 64-es alapkódolt jogcímkérelmet tartalmaz. A jogcímkérelemnek a JSON-objektum legfelső szintjén lévő "access_token" jogcímeket kell kérnie. Az érték (kért jogcímek) környezetfüggőek lesznek, és a dokumentum későbbi részében lesz megadva. Méretbeli okokból a függő entitásalkalmazásoknak a JSON-t a 64-es alapkódolás előtt minnálniuk kell. A fenti példa nyers JSON-ja a .{"access_token":{"acrs":{"essential":true,"value":"cp1"}}}

A 401-válasz több www-authenticate fejlécet is tartalmazhat. Az előző tábla összes mezőjének ugyanabban www-authenticate a fejlécben kell lennie. A www-authenticate jogcím-kihívást tartalmazó fejléc más mezőket is tartalmazhat. A fejléc mezői rendezetlenek. Az RFC 7235 szerint minden paraméternévnek csak egyszer kell előfordulnia a hitelesítési séma kihívásai alapján.

Jogcímkérelem

Amikor egy alkalmazás jogcímekkel kapcsolatos kihívást kap, az azt jelzi, hogy a korábbi hozzáférési jogkivonat már nem tekinthető érvényesnek. Ebben az esetben az alkalmazásnak törölnie kell a jogkivonatot bármely helyi gyorsítótárból vagy felhasználói munkamenetből. Ezután vissza kell irányítania a bejelentkezett felhasználót a Microsoft Entra-azonosítóra, hogy lekérjen egy új jogkivonatot az OAuth 2.0 engedélyezési kódfolyamat használatával egy jogcímparaméterrel , amely megfelel a többi nem teljesített követelménynek.

Példa:

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

A jogcímekkel kapcsolatos kihívást a Microsoft Entra /engedélyezési végpont felé irányuló összes hívás részeként kell átadni, amíg a jogkivonatot sikeresen le nem kérik. A jogkivonat lekérése után már nincs rá szükség.

A jogcímparaméter feltöltéséhez a fejlesztőnek a következőt kell megadnia:

1. Dekódolja a korábban kapott base64 sztringet.
2. URL-kódolja a sztringet, és adja hozzá újra a jogcímparaméterhez .

A folyamat befejezése után az alkalmazás kap egy hozzáférési jogkivonatot, amely más jogcímekkel rendelkezik, amelyek bizonyítják, hogy a felhasználó teljesítette a szükséges feltételeket.

Ügyfélképességek

Az ügyfél képességei segítenek egy erőforrás-szolgáltatónak, például a webes API-nak észlelni, hogy a hívó ügyfélalkalmazás megérti-e a jogcímekkel kapcsolatos kihívást, majd ennek megfelelően testre szabhatja a választ. Ez a képesség akkor lehet hasznos, ha nem minden API-ügyfél képes kezelni a jogcímekkel kapcsolatos kihívásokat, és egyes korábbi verziók továbbra is eltérő választ várnak.

Egyes népszerű alkalmazások, például a Microsoft Graph csak akkor küldenek jogcímekkel kapcsolatos kihívásokat, ha a hívó ügyfélalkalmazás kijelenti, hogy képes kezelni őket az ügyfél képességeinek használatával.

A további forgalom vagy a felhasználói élményre gyakorolt hatások elkerülése érdekében a Microsoft Entra-azonosító nem feltételezi, hogy az alkalmazás csak akkor tudja kezelni a kifogásolt jogcímeket, ha ön kifejezetten beleegyezik. Az alkalmazások nem kapnak jogcímekkel kapcsolatos kihívásokat (és nem fogják tudni használni a kapcsolódó funkciókat, például a CAE-jogkivonatokat), hacsak nem deklarálja, hogy készen áll a "cp1" képességgel való kezelésükre.

Ügyfélképességek kommunikációja a Microsoft Entra-azonosítóval

Az alábbi jogcímparaméter azt mutatja be, hogy egy ügyfélalkalmazás hogyan kommunikálja a képességét a Microsoft Entra-azonosítóval egy OAuth 2.0 engedélyezési kódfolyamatban.

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

.NET

Az MSAL-kódtár használata esetén használja a következő kódot:

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

A Microsoft.Identity.Web szolgáltatást használó felhasználók a következő kódot adhatják hozzá a konfigurációs fájlhoz:

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

JavaScript

Azok, akik MSAL.js vagy MSAL-csomópontot használnak, hozzáadhatnak clientCapabilities tulajdonságot a konfigurációs objektumhoz. Megjegyzés: ez a beállítás nyilvános és bizalmas ügyfélalkalmazások számára is elérhető.

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

const msalInstance = new msal.PublicClientApplication(msalConfig);

Tekintse meg az alábbi kódrészletet a Microsoft Entra-azonosítóra irányuló mintakérés megtekintéséhez:

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

Ha már rendelkezik meglévő hasznos adattartalommal a jogcímparaméterhez, akkor ezt hozzáadná a meglévő készlethez.

Ha például már rendelkezik a következő válaszsal egy feltételhozzáférés-hitelesítési környezet műveletéből;

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

A meglévő jogcímek hasznos adataiban előre fel kell függesztetnie az ügyfélképességet.

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

Xms_cc jogcím fogadása hozzáférési jogkivonatban

Ha információt szeretne kapni arról, hogy az ügyfélalkalmazások képesek-e kezelni a jogcímekkel kapcsolatos kihívásokat, az API-implementálónak xms_cc kell kérnie opcionális jogcímként az alkalmazásjegyzékben.

A hozzáférési jogkivonatban a "cp1" értékkel rendelkező xms_cc jogcím mérvadó módja annak azonosításának, hogy az ügyfélalkalmazás képes-e jogcímekkel kapcsolatos kihívások kezelésére. xms_cc nem kötelező jogcím, amely nem mindig lesz kiállítva a hozzáférési jogkivonatban, még akkor sem, ha az ügyfél "xms_cc" címmel küld jogcímkérelmet. Ahhoz, hogy egy hozzáférési jogkivonat tartalmazza a xms_cc jogcímet, az erőforrás-alkalmazásnak (vagyis az API-implementálónak) xms_cc kell kérnie az alkalmazásjegyzékben választható jogcímként. Ha választható jogcímként kérik, xms_cc csak akkor lesz hozzáadva a hozzáférési jogkivonathoz, ha az ügyfélalkalmazás xms_cc küld a jogcímkérelemben. A xms_cc jogcímkérelem értéke a hozzáférési jogkivonatban szereplő xms_cc jogcím értékeként szerepel, ha ismert érték. Az egyetlen jelenleg ismert érték a cp1.

Az értékek nem megkülönböztetik a kis- és nagybetűket, és rendezetlenek. Ha egynél több érték van megadva a xms_cc jogcímkérelemben, ezek az értékek többértékű gyűjtemények lesznek a xms_cc jogcím értékeként.

Példaként tekintse meg a következő kérést:

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

Ez az alábbi kódrészlet jogcímét eredményezi a hozzáférési jogkivonatban, ha a cp1, a foo és a sáv ismert képességek.

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

Az xms_ccválasztható jogcím kérése után az alkalmazás jegyzékbeli módosításai az alábbiakhoz hasonlóan változnak:

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

Az API ezután testreszabhatja a válaszaikat attól függően, hogy az ügyfél képes-e kezelni a jogcímekkel kapcsolatos kihívásokat.

.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

Az alábbi kódrészlet egy egyéni Express.js köztes szoftvereket mutat be:

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

Kódminták

• Az Angular egyoldalas alkalmazásának engedélyezése a felhasználók bejelentkezéséhez és a Microsoft Graph meghívásához
• A React egyoldalas alkalmazásának engedélyezése a felhasználók bejelentkezéséhez és a Microsoft Graph meghívásához
• A ASP.NET Core-webalkalmazás engedélyezése a felhasználók bejelentkezéséhez és a Microsoft Graph meghívásához

Következő lépések

• A Microsoft Identitásplatform és az OAuth 2.0 hitelesítési kódfolyamat
• Folyamatos hozzáférés-kiértékelést engedélyező API-k használata az alkalmazásokban
• Részletes feltételes hozzáférés bizalmas adatokhoz és műveletekhez