Útmutató: Jogkivonat kérése az ACS-től az OAuth WRAP protokollon keresztül
Érvényesség
- Microsoft Azure Active Directory Access Control (más néven Access Control Szolgáltatás vagy ACS)
Áttekintés
Amikor a webalkalmazások és -szolgáltatások ACS használatával kezelik a hitelesítést, az ügyfélnek be kell szereznie az ACS által kiadott biztonsági jogkivonatot az alkalmazásba vagy szolgáltatásba való bejelentkezéshez. Az ACS által kiadott jogkivonat (kimeneti jogkivonat) beszerzéséhez az ügyfélnek vagy közvetlenül az ACS-vel kell hitelesítenie, vagy el kell küldenie az ACS-nek az identitásszolgáltatója által kiadott biztonsági jogkivonatot (bemeneti jogkivonat). Az ACS ellenőrzi ezt a bemeneti biztonsági jogkivonatot, feldolgozza a jogkivonat identitásjogcímeit az ACS szabálymotoron keresztül, kiszámítja a kimeneti identitás jogcímeit, és kiad egy kimeneti biztonsági jogkivonatot.
Ez a témakör azt ismerteti, hogyan kérhet jogkivonatot az ACS-től az OAuth WRAP protokollon keresztül. Az OAuth WRAP protokollon keresztüli összes jogkivonat-kérés SSL-en keresztül lesz továbbítva. Az ACS mindig kiad egy egyszerű webes jogkivonatot (SWT) az OAuth WRAP protokollon keresztül, egy megfelelően formázott jogkivonat-kérésre válaszul. Az OAuth WRAP protokollon keresztüli jogkivonat-kérelmeket a rendszer egy HTTP POST-ben küldi el az ACS-nek. Az OAuth WRAP protokollon keresztül bármilyen olyan platformról kérhet ACS-jogkivonatot, amely KÉPES HTTPS FORM POST-t készíteni: .NET-keretrendszer, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash és egyéb platformok.
Az alábbi táblázat az ACS által kiadott SWT-jogkivonat OAuth WRAP protokollon keresztüli lekérésének három támogatott módszerét sorolja fel.
Az ACS-ből az OAuth WRAP protokollon keresztüli jogkivonat kérésének három módszere
| Jogkivonat-kérési módszer | Description |
|---|---|
Jelszó-jogkivonat-kérések |
Ez a legegyszerűbb módszer megköveteli, hogy az ügyfél közvetlenül az OAuth WRAP protokollon keresztül küldjön egy felhasználónevet és jelszót egy szolgáltatásidentitásból az ACS-nek a hitelesítéshez. |
SWT-jogkivonat-kérések |
Ez a módszer megköveteli, hogy az ügyfél küldjön egy SWT-jogkivonatot, amely egy szolgáltatásidentitás-szimmetrikus kulccsal vagy identitásszolgáltatói szimmetrikus kulccsal írható alá az ACS-nek az OAuth WRAP protokollon keresztül a hitelesítéshez. |
SAML-jogkivonat-kérelmek |
Elsősorban az Active Directory összevonási szolgáltatás (AD FS) 2.0-s integrációjához készült Security Assertion Markup Language (SAML) metódus megköveteli, hogy az ügyfél aláírt SAML-jogkivonatot küldjön az ACS-nek az OAuth WRAP protokollon keresztül a hitelesítéshez. Ez a módszer lehetővé teszi, hogy az ügyfél vállalati identitást használjon az ACS-hitelesítéshez. |
Jogkivonatot kibocsátó végpont
Az OAuth WRAP protokollon keresztüli összes ACS-jogkivonat-kérés egy ACS-jogkivonatot kibocsátó végpontra irányul. A végpont URI-ja a Access Control névtértől függ. A névtér DNS-névelőtagként jelenik meg egy jogkivonat-kérelem URI-jában. A DNS-név többi része ki van javítva, ahogyan az elérési út is. Ha például a "mysnservice" nevű Access Control névtérből szeretne jogkivonatot kérni, a jogkivonat-kérést a következő URI-ra irányíthatja: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.
Jelszó-jogkivonat-kérések
Jelszó-jogkivonat-kéréssel az ügyfél közvetlenül az OAuth WRAP protokollon keresztül küldhet felhasználónevet és jelszót egy szolgáltatásidentitásból az ACS-nek a hitelesítéshez. Ez a legegyszerűbb módja annak, hogy jogkivonatot kérjen az ACS-től az OAuth WRAP protokoll használatával. Az SSL-kapcsolat létesítésen kívül ez a megközelítés nem igényel titkosítási képességet. A gyakorlatban hasonló a REST-webszolgáltatásokban elterjedt felhasználónév-jelszó modellhez. Az ilyen típusú jogkivonat-kérés valójában EGY HTTPS-űrlap POST. A jelszó-jogkivonat-kérés paraméterei űrlapkódolva vannak.
Az alábbi példa egy egyszerű szöveges kérés vezetékes nyomkövetésére mutat egy "mysnservice" nevű névtérre.
POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded
wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_name=mysncustomer1&
wrap_password=5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ%3D
Az alábbi táblázat azoknak a paramétereknek a nevét, leírását és értékkövetelményeit tartalmazza, amelyeknek jelen kell lenniük egy jelszókivonat-kérésben:
| Paraméter neve | Leírás | Értékkövetelmények |
|---|---|---|
wrap_scope |
Megfelel a jogkivonat-kérésnek egy szabálykészlettel. Állítsa a paraméter értékét a függő entitás alkalmazástartományának értékére. Ezt az értéket (a Tartomány mezőben) az ACS felügyeleti portálon szerezheti be, ha kiválasztja a megfelelő függő entitásalkalmazást a Függő entitásalkalmazások lapon. |
|
wrap_name |
Ellenőrzi a következő paraméter kulcsát. Állítsa a paraméter értékét egy szolgáltatásidentitás nevére a Access Control névtérben. Ezt az értéket (a Név mezőben) az ACS felügyeleti portálon szerezheti be, ha kiválasztja a megfelelő szolgáltatásidentitást a Szolgáltatásidentitások lapon. |
|
wrap_password |
Hitelesíti a bejövő kérést. Állítsa a paraméter értékét egy szolgáltatásidentitás jelszavára a Access Control névtérben. Ezt az értéket (a Hitelesítő adatok szerkesztése lap Jelszó mezőjében) az ACS felügyeleti portálon szerezheti be, ha először kiválasztja a megfelelő szolgáltatásidentitást a Szolgáltatásidentitások lapon, majd kiválasztja a megfelelő jelszót a Szolgáltatásidentitás szerkesztése lap Hitelesítő adatok táblájában. |
|
Ezeknek a paramétereknek az értékeit URL-kódolással kell megadni, mielőtt elküldené a kérést az ACS-nek. A webalkalmazás vagy a szolgáltatás megadhatja a wrap_scope értékét az ügyfélnek, vagy az ügyfél dönthet úgy, hogy a wrap_scope paraméter értékét a webalkalmazás vagy szolgáltatás erőforrás-céljának URI-jára állítja be.
Az OAuth WRAP protokollon keresztüli jelszó-jogkivonat-kérelmek további paramétereket is tartalmazhatnak, amelyeket az ACS a kimeneti jogcím számítási folyamata során használhat. Ezeknek a további paramétereknek és értékeknek URL-kódolásúnak kell lenniük, és az értékeket nem szabad idézni.
A jelszó jogkivonat-kérési módszere meglehetősen egyszerű a használatával.
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");
// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
A kimeneti jogkivonat ACS-ből való kicsomagolásával és webalkalmazásba vagy szolgáltatásba való küldésével kapcsolatos információkért tekintse meg a jogkivonat kibontásáról és webalkalmazásnak vagy szolgáltatásnak való küldéséről szóló témakört.
SWT-jogkivonat-kérések
Az ACS-től az OAuth WRAP protokollon keresztül is kérhet jogkivonatot egy szimmetrikus kulccsal aláírt SWT-jogkivonattal. Minden SWT-jogkivonat-kérés EGY HTTPS-űrlap postán keresztül történik. A tokenkérelem-metódus paraméterértékei űrlapkódolva vannak.
Az alábbi példa egy SWT-jogkivonat-kérés vezetékes nyomkövetésére mutat a "mysnservice" névtérre.
POST /WRAPv0.9/ HTTP/1.1
Host: mysnservice.accesscontrol.windows.net
Content-Type: application/x-www-form-urlencoded
wrap_scope=http%3A%2F%2Fmysnservice.com%2Fservices%2F&
wrap_assertion_format=SWT&
wrap_assertion=Issuer%3dmysncustomer1%26HMACSHA256%3db%252f%252bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%253d
A SWT-jogkivonat-kérelmeknek a következő paraméterekkel és értékekkel kell rendelkezniük:
| Paraméter neve | Leírás | Értékkövetelmények |
|---|---|---|
wrap_scope |
Megfelel a jogkivonat-kérésnek egy szabálykészlettel. |
|
wrap_assertion |
Ez az ACS-nek küldött bemeneti jogkivonat. |
|
wrap_assertion_format |
Ez az ACS-be küldött bemeneti jogkivonat formátuma. |
SWT |
Az alábbi példában látható módon az SWT-jogkivonat-kérés létrehozásához szükséges kód hasonlít a jelszó-jogkivonat kéréséhez szükséges kódra.
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
// add the wrap_scope
values.Add("wrap_scope", "http://mysnservice.com/services");
// add the format
values.Add("wrap_assertion_format", "SWT");
// add the SWT
values.Add("wrap_assertion", "Issuer=mysncustomer1&HMACSHA256=b%2f%2bJFwbngGdufECFjQb8qhb9YH0e32Cf9ABMDZFiPPA%3d");
// WebClient takes care of the remaining URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
A válasz ACS-ből való kicsomagolásáról és a webalkalmazásnak vagy szolgáltatásnak való elküldéséről további információt a jogkivonat kibontása és webalkalmazásnak vagy szolgáltatásnak való elküldése című témakörben talál.
SWT-jogkivonat létrehozása
Az SWT-jogkivonat olyan kulcs-érték párok készlete, amelyek egy kiállítói kulccsal (szimmetrikus kulccsal) vannak aláírva. Az SWT-jogkivonat-kérelemben az ACS-nek küldött SWT-jogkivonatnak tartalmaznia kell a Kiállító és a HMACSHA256 paramétereket, valamint további paramétereket, például az ExpiresOn, a Audience és más ügyfélspecifikus jogcímeket. Az alábbi táblázat az SWT-jogkivonat paramétereinek nevét és leírását tartalmazza:
| Paraméter neve | Leírás |
|---|---|
Kibocsátó |
Az ACS-ben megkeresi a jogkivonat aláírásához használt kulcsot. Ha az aláírás érvényes, akkor a rendszer ezt az értéket használja a kimeneti jogcím kiszámításához. Ezt a paramétert beállíthatja egy identitásszolgáltató tartományának értékére a Access Control névtérben, vagy egy szolgáltatásidentitás nevére a Access Control névtérben. Ezt az értéket (az Identitásszolgáltató szerkesztése lap Tartomány mezőjében) az ACS felügyeleti portálon szerezheti be, ha kiválasztja a megfelelő identitásszolgáltatót az Identitásszolgáltatók lapon. Ezt az értéket az ACS felügyeleti szolgáltatáson keresztül is beszerezheti – ez az egyes identitásszolgáltatókhoz létrehozott "Kiállító" rekord névtulajdonsága. |
HMACSHA256 |
Az ACS-ben ellenőrzi az SWT-aláírást, és megkeresi a Kiállító paraméterben megnevezett kiállítókulcsot. Az SWT-aláírás a szolgáltatásidentitáshoz vagy egy identitásszolgáltatóhoz csatolt szimmetrikus aláírókulccsal jön létre a Access Control névtérben. |
Célközönség |
Ha van ilyen, az ACS ezt az értéket használja annak biztosításához, hogy az ACS legyen az SWT-jogkivonat célhelye. Ez a Access Control névtér URL-címe, például:https://contoso.accesscontrol.windows.net/ |
Lejárat dátuma |
Ha jelen van (alapidőszakban), azt jelzi, hogy a jogkivonat lejárt-e. Ennek a paraméternek például az értéke lehet |
További jogcímek |
Ha van ilyen, az ACS ezeket a paramétereket használja a kimeneti jogcím kiszámításához. Minden jogcímtípus csak egyszer jelenhet meg. Az azonos jogcímtípusú több jogcímértéket össze kell fűzni egy "," (vessző) karakterrel. További információ a jogcímek ACS-ben való érvényesítéséről: Jogcímek helyességi feltételének meghatározása az OAuth WRAP protokollon keresztül. |
Az alábbi kódminta bemutatja, hogyan hozhat létre SWT-jogkivonatot a használatával. Olyan típust tartalmaz, amely az Issuer és a HMACSHA256 paramétereket tartalmazó SWT-jogkivonatokat készít.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Web;
public class TokenFactory
{
string signingKey;
string issuer;
public TokenFactory(string issuer, string signingKey)
{
this.issuer = issuer;
this.signingKey = signingKey;
}
public string CreateToken()
{
StringBuilder builder = new StringBuilder();
// add the issuer name
builder.Append("Issuer=");
builder.Append(HttpUtility.UrlEncode(this.issuer));
string signature = this.GenerateSignature(builder.ToString(), this.signingKey);
builder.Append("&HMACSHA256=");
builder.Append(signature);
return builder.ToString();
}
private string GenerateSignature(string unsignedToken, string signingKey)
{
HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String(signingKey));
byte[] locallyGeneratedSignatureInBytes = hmac.ComputeHash(Encoding.ASCII.GetBytes(unsignedToken));
string locallyGeneratedSignature = HttpUtility.UrlEncode(Convert.ToBase64String(locallyGeneratedSignatureInBytes));
return locallyGeneratedSignature;
}
}
SAML-jogkivonat-kérelmek
Az SAML-jogkivonat-kérési módszer elsősorban az AD FS 2.0 integrációjára szolgál, és lehetővé teszi, hogy az ügyfél vállalati identitást (Active Directoryt) használjon az ACS-hitelesítéshez. Az SAML-jogkivonat-kérési metódussal elküldhet egy aláírt SAML 1.1-es vagy egy AD FS 2.0 által kibocsátott SAML 2.0-jogkivonatot (bemeneti jogkivonatot) az ACS-nek az OAuth WRAP protokollon keresztül.
Az ACS a szabályaival kiszámítja a kimeneti jogcímeket, SWT-jogkivonatba (kimeneti jogkivonatba) csoportosítja őket, aláírja, majd az OAuth WRAP protokollon keresztül visszaküldi az ügyfélnek.
Az SAML-jogkivonat-kérelmeknek a következő paraméterekkel és értékekkel kell rendelkezniük:
| Paraméter neve | Leírás | Értékkövetelmények |
|---|---|---|
wrap_scope |
Megfelel a jogkivonat-kérelemnek egy szabálykészlethez. |
|
wrap_assertion |
Ez az ACS-nek küldött bemeneti jogkivonat. |
|
wrap_assertion_format |
Ez az ACS-be küldött bemeneti jogkivonat formátuma. |
SAML |
Az alábbi példa az SAML-jogkivonat-kérés végrehajtásához szükséges kódra mutat be példát.
private static string SendSAMLTokenToACS(string samlToken)
{
try
{
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection parameters = new NameValueCollection();
parameters.Add("wrap_assertion_format", "SAML");
parameters.Add("wrap_assertion", samlToken);
parameters.Add("wrap_scope", "http://mysnservice.com/services");
byte[] responseBytes = client.UploadValues("WRAPv0.9", parameters);
string response = Encoding.UTF8.GetString(responseBytes);
return response
.Split('&')
.Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
.Split('=')[1];
}
catch (WebException wex)
{
string value = new StreamReader(wex.Response.GetResponseStream()).ReadToEnd();
throw;
}
}
Az ACS válaszának kicsomagolásával és webalkalmazásba vagy szolgáltatásba való küldésével kapcsolatos információkért lásd: A jogkivonat kicsomagolása és webalkalmazásba vagy szolgáltatásba való elküldése.
Jogcím-érvényesítés az OAuth WRAP protokollon keresztül
Az ACS 1.0 jogkivonat-kérelmek viselkedésével való visszamenőleges kompatibilitás érdekében az ACS támogatja a jogcímek jogkivonat-kérelmek részeként történő érvényesítését.
Regisztrálja a helyes alkalmazást vagy szolgáltatást ACS-identitásszolgáltatóként.
Ennek ajánlott módja a helyes alkalmazás vagy szolgáltatás regisztrálása ACS-identitásszolgáltatóként. Ezután az alkalmazás vagy szolgáltatás jogkivonatot kér az ACS-től egy SAML- vagy SWT-jogkivonat bemutatásával, amely tartalmazza az érvényesíteni kívánt jogcímeket, és ezt a jogkivonatot egy ACS-ben tárolt identitásszolgáltatói kulccsal írja alá. Például az AD FS 2.0 OAuth WRAP protokolljával vagy bármely olyan egyéni biztonságijogkivonat-szolgáltatással (STS) küldhet SAML-jogkivonat-kérést az ACS-nek, amely Windows Identity Foundation (WIF) használatával készült, és WS-Federation identitásszolgáltatóként regisztrálva van az ACS-ben.
Az ACS felügyeleti portálon WS-Federation metaadatok használatával regisztrálhat egy identitásszolgáltatót, vagy az ACS felügyeleti szolgáltatással egyedileg állíthat be identitásszolgáltatói tulajdonságokat, címeket és kulcsokat. (Lásd például : Az ACS felügyeleti szolgáltatás használata az AD FS 2.0 vállalati identitásszolgáltatóként való konfigurálásához.) A jogcímek jogkivonat-kérelmekben való érvényesítésének ebben a módszerében nincs szükség szolgáltatásidentitásra. Ez a módszer az összes ACS által támogatott protokollon keresztül működik.
A jogkivonat kibontása és elküldése egy webalkalmazásnak vagy szolgáltatásnak
Ha a jogkivonat-kérelem sikeresen hitelesítve van, az ACS két űrlapkódolt paramétert ad vissza: wrap_token és wrap_token_expires_in. Ezeknek a paramétereknek az értékei a tényleges SWT-jogkivonat, amellyel az ügyfél hozzáférhet a webalkalmazáshoz vagy szolgáltatáshoz, valamint a jogkivonat hozzávetőleges hátralévő élettartama (másodpercben).
Mielőtt elküldi az SWT-jogkivonatot a webalkalmazásnak vagy szolgáltatásnak, az ügyfélnek ki kell nyernie és URL-dekódolnia kell azt az ACS-válaszból. Ha a webalkalmazásnak vagy szolgáltatásnak meg kell jelenítenie a jogkivonatot a HTTP-fejlécben Authorization , a jogkivonatot a séma WRAPv0.9előzi meg.
Az alábbi példakód bemutatja, hogyan csomagolhat ki egy jogkivonatot, és hogyan formázhatja a fejlécet Authorization .
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");
// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
string token = response
.Split('&')
.Single(value => value.StartsWith("wrap_token=", StringComparison.OrdinalIgnoreCase))
.Split('=')[1];
string.Format("WRAP access_token=\"{0}\"", HttpUtility.UrlDecode(token));
ACS-hibakódok és -leírások
Az ACS olyan hibákat ad vissza, amelyek nem felelnek meg a jogkivonat-kérelmeknek. A REST-kialakításnak megfelelően a hiba egy HTTP-válaszkódot tartalmaz. Az ACS-hibák sok esetben tartalmaznak egy SubCode , a Detail sikertelen művelettel kapcsolatos kontextust is. A hiba formátuma: Error:Code:<httpStatus>:Sub-Code:<code>:D etail:<message>. A Content-Type hiba mindig szöveges/egyszerű.
HTTP/1.1 401 Access Forbidden
Content-Type: text/plain; charset=us-ascii
Error:Code:401:SubCode:T0:Detail:ACS50009: SWT token is invalid. :TraceID:<trace id value>:TimeStamp:<timestamp value>
Az ACS-hibakódokkal kapcsolatos további információkért lásd az ACS hibakódjait.
Az ACS által visszaadott hiba hibakeresése vagy helyreállítása során gyakran szükséges elolvasni a válasz törzsét. Az alábbi példakód bemutatja, hogyan olvasható be a hibaüzenet egy WebException objektumból.
try
{
WebClient client = new WebClient();
client.BaseAddress = string.Format("https://mysnservice.accesscontrol.windows.net");
NameValueCollection values = new NameValueCollection();
values.Add("wrap_name", "mysncustomer1");
values.Add("wrap_password", "5znwNTZDYC39dqhFOTDtnaikd1hiuRa4XaAj3Y9kJhQ=");
values.Add("wrap_scope", "http://mysnservice.com/services");
// WebClient takes care of the URL Encoding
byte[] responseBytes = client.UploadValues("WRAPv0.9", "POST", values);
// the raw response from ACS
string response = Encoding.UTF8.GetString(responseBytes);
string token = response
.Split('&')
.Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase))
.Split('=')[1];
}
catch (WebException wex)
{
if (wex.Response != null)
{
// the response Stream contains the error message
StreamReader reader = new StreamReader(wex.Response.GetResponseStream());
string message = reader.ReadToEnd();
}
// Throw as appropriate
}