Postupy: Vyžádání tokenu ze služby ACS prostřednictvím protokolu OAuth WRAP
Platí pro
- Microsoft Azure Active Directory Access Control (označované také jako služba Access Control nebo služba ACS)
Přehled
Když webové aplikace a služby zpracovávají ověřování pomocí služby ACS, musí klient získat token zabezpečení vydaný službou ACS, aby se přihlásil k vaší aplikaci nebo službě. Aby bylo možné získat tento token ACS (výstupní token), musí se klient buď ověřit přímo pomocí služby ACS, nebo odeslat token zabezpečení vydaný jeho zprostředkovatelem identity (vstupní token). Služba ACS ověří tento vstupní token zabezpečení, zpracuje deklarace identity v tomto tokenu prostřednictvím modulu pravidel služby ACS, vypočítá deklarace identity výstupu a vydá výstupní token zabezpečení.
Toto téma popisuje metody vyžádání tokenu ze služby ACS prostřednictvím protokolu OAuth WRAP. Všechny požadavky na tokeny prostřednictvím protokolu OAuth WRAP se přenášejí přes PROTOKOL SSL. Služba ACS vždy vydává jednoduchý webový token (SWT) prostřednictvím protokolu OAuth WRAP v reakci na správně formátovaný požadavek na token. Všechny požadavky na tokeny prostřednictvím protokolu OAuth WRAP se odesílají do služby ACS v HTTP POST. Token ACS můžete požádat prostřednictvím protokolu OAuth WRAP z libovolné platformy, která může vytvořit HTTPS FORM POST: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash a další platformy.
Následující tabulka uvádí tři podporované metody vyžádání tokenu SWT vydaného službou ACS prostřednictvím protokolu OAuth WRAP.
Tři metody vyžádání tokenu ze služby ACS prostřednictvím protokolu OAuth WRAP
| Metoda žádosti o token | Description |
|---|---|
Žádosti o token hesla |
Tato nejjednodušší metoda vyžaduje, aby klient odeslal uživatelské jméno a heslo z identity služby přímo do služby ACS prostřednictvím protokolu OAuth WRAP pro ověřování. |
Žádosti o token SWT |
Tato metoda vyžaduje, aby klient odeslal token SWT, který je možné podepsat pomocí symetrického klíče identity služby nebo symetrického klíče zprostředkovatele identity do služby ACS prostřednictvím protokolu OAuth WRAP pro ověřování. |
Žádosti o token SAML |
Primárně je určená pro integraci služby AD FS (Active Directory Federation Service) 2.0, metoda SAML (Security Assertion Markup Language) vyžaduje, aby klient odeslal podepsaný token SAML do služby ACS prostřednictvím protokolu OAuth WRAP pro ověřování. Tento přístup umožňuje klientovi používat podnikovou identitu k ověřování pomocí služby ACS. |
Koncový bod pro vydávání tokenů
Všechny požadavky na tokenY služby ACS prostřednictvím protokolu OAuth WRAP jsou směrovány na koncový bod vydávající token služby ACS. Identifikátor URI tohoto koncového bodu závisí na oboru názvů Access Control. Obor názvů se zobrazí jako předpona názvu DNS v identifikátoru URI požadavku na token. Zbytek názvu DNS je opravený, stejně jako cesta. Pokud například chcete požádat o token z oboru názvů Access Control s názvem mysnservice, můžete žádost o token směrovat na následující identifikátor URI: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.
Žádosti o token hesla
Pomocí požadavku na token hesla může klient odeslat uživatelské jméno a heslo z identity služby přímo do služby ACS prostřednictvím protokolu OAuth WRAP pro ověřování. Toto je nejjednodušší způsob, jak vyžádat token ze služby ACS pomocí protokolu OAuth WRAP. Kromě navázání připojení SSL tento přístup nevyžaduje žádnou kryptografickou funkci. V praxi se podobá modelu uživatelského jména a hesla, který je ve webových službách REST rozšířen. Tento typ požadavku na token je ve skutečnosti formulář HTTPS POST. Parametry v požadavku na token hesla jsou kódované ve formátu.
Následuje příklad trasování přenosu požadavku ve formátu prostého textu na obor názvů s názvem mysnservice.
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
Následující tabulka obsahuje názvy, popisy a požadavky na hodnotu parametrů, které musí být přítomné v požadavku na token hesla:
| Název parametru | Description | Požadavky na hodnotu |
|---|---|---|
wrap_scope |
Odpovídá požadavku na token vůči sadě pravidel. Nastavte hodnotu tohoto parametru na hodnotu sféry aplikace předávající strany. Tuto hodnotu (v poli Sféra ) můžete získat prostřednictvím portálu pro správu služby ACS tak, že na stránce Aplikace předávající strany vyberete příslušnou aplikaci předávající strany. |
|
wrap_name |
Ověří klíč dalšího parametru. Nastavte hodnotu tohoto parametru na název identity služby v rámci oboru názvů Access Control. Tuto hodnotu (v poli Název ) můžete získat prostřednictvím portálu pro správu služby ACS tak, že na stránce Identity služby vyberete příslušnou identitu služby. |
|
wrap_password |
Ověří příchozí požadavek. Nastavte hodnotu tohoto parametru na heslo identity služby v rámci vašeho oboru názvů Access Control. Tuto hodnotu (v poli Heslo na stránce Upravit přihlašovací údaje ) můžete získat prostřednictvím portálu pro správu služby ACS tak, že nejprve vyberete příslušnou identitu služby na stránce Identity služby a pak vyberete odpovídající heslo v tabulce Přihlašovací údaje na stránce Upravit identitu služby . |
|
Hodnoty těchto parametrů musí být před odesláním požadavku do služby ACS zakódované adresou URL. Webová aplikace nebo služba může klientovi poskytnout hodnotu wrap_scope nebo se klient může rozhodnout nastavit hodnotu parametru wrap_scope na identifikátor URI cílového prostředku webové aplikace nebo služby.
Požadavky na token hesla prostřednictvím protokolu OAuth WRAP můžou obsahovat také další parametry, které může služba ACS používat během procesu výpočtu výstupní deklarace identity. Tyto další názvy parametrů a hodnoty musí být kódované adresou URL a hodnoty nesmí být uvozeny.
Metoda žádosti o token hesla je poměrně jednoduchá pomocí .
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);
Informace o tom, jak rozbalit výstupní token ze služby ACS a odeslat ho do webové aplikace nebo služby, najdete v tématu Rozbalení a odeslání tokenu do webové aplikace nebo služby.
Žádosti o token SWT
Token můžete také vyžádat ze služby ACS prostřednictvím protokolu OAuth WRAP pomocí tokenu SWT podepsaného symetrickým klíčem. Všechny požadavky na token SWT se provádějí prostřednictvím formuláře HTTPS POST. Hodnoty parametrů v této metodě žádosti o token jsou kódovány ve formátu.
Následuje příklad trasování přenosu požadavku tokenu SWT na obor názvů mysnservice.
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
Požadavek na token SWT musí mít následující parametry a hodnoty:
| Název parametru | Description | Požadavky na hodnotu |
|---|---|---|
wrap_scope |
Odpovídá požadavku na token vůči sadě pravidel. |
|
wrap_assertion |
Jedná se o vstupní token, který se odesílá do služby ACS. |
|
wrap_assertion_format |
Jedná se o formát vstupního tokenu, který se odesílá do služby ACS. |
SWT |
Jak je znázorněno v následujícím příkladu, kód, který je nutný k vytvoření požadavku na token SWT, se podobá kódu, který je nutný k vytvoření požadavku na token hesla.
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);
Informace o tom, jak rozbalit odpověď ze služby ACS a odeslat ji do webové aplikace nebo služby, najdete v tématu Rozbalení a odeslání tokenu do webové aplikace nebo služby.
Vytvoření tokenu SWT
Token SWT je sada párů klíč/hodnota, které jsou podepsané klíčem vystavitele (symetrický klíč). Token SWT odeslaný do služby ACS v požadavku na token SWT musí obsahovat parametry Vystavitel a HMACSHA256 a další parametry, například ExpirsOn, Audience a další deklarace identity specifické pro klienta. Následující tabulka obsahuje názvy a popisy parametrů tokenu SWT:
| Název parametru | Description |
|---|---|
Emitenta |
Ve službě ACS vyhledá klíč použitý k podepsání tokenu. Pokud je podpis platný, použije se tato hodnota k provedení výpočtu výstupní deklarace identity. Tento parametr můžete nastavit na hodnotu sféry zprostředkovatele identity v rámci oboru názvů Access Control nebo názvu identity služby v rámci vašeho oboru názvů Access Control. Tuto hodnotu (v poli Sféra na stránce Upravit zprostředkovatele identity ) můžete získat prostřednictvím portálu pro správu služby ACS tak, že na stránce Zprostředkovatelé identity vyberete příslušného zprostředkovatele identity. Nebo tuto hodnotu můžete získat prostřednictvím služby pro správu služby ACS – to je vlastnost názvu záznamu Vystavitel, který je vytvořen pro každého zprostředkovatele identity. |
HMACSHA256 |
V ACS ověří podpis SWT a vyhledá klíč vystavitele pojmenovaný v parametru Vystavitel . Podpis SWT se vytvoří pomocí symetrického podpisového klíče připojeného k identitě služby nebo zprostředkovateli identity v rámci vašeho oboru názvů Access Control. |
Cílová skupina |
Pokud je k dispozici, služba ACS tuto hodnotu použije k zajištění, aby služba ACS byla zamýšleným cílem tokenu SWT. Toto je adresa URL vašeho oboru názvů Access Control, napříkladhttps://contoso.accesscontrol.windows.net/ |
ExpirsOn |
Pokud je k dispozici (v epochovém čase), označuje, jestli platnost tokenu vypršela. Například hodnota tohoto parametru může být |
Další deklarace identity |
V případě přítomnosti používá ACS tyto parametry k provedení výpočtu výstupní deklarace identity. Každý typ deklarace identity musí být zobrazen pouze jednou. Více hodnot deklarací identity stejného typu deklarace identity musí být zřetězeno společně s znakem "," (čárka). Další informace o uplatnění deklarací identity ve službě ACS najdete v tématu Kontrolní výraz deklarací identity prostřednictvím protokolu OAuth WRAP. |
Následující ukázka kódu ukazuje, jak vygenerovat token SWT pomocí . Obsahuje typ, který sestavuje tokeny SWT, které obsahují parametry Vystavitel a HMACSHA256 .
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;
}
}
Žádosti o token SAML
Metoda žádosti o token SAML je určená hlavně pro integraci služby AD FS 2.0 a umožňuje klientovi používat podnikovou identitu (Active Directory) k ověřování pomocí služby ACS. Pomocí metody žádosti o token SAML můžete odeslat podepsaný token SAML 1.1 nebo token SAML 2.0 vydaný službou AD FS 2.0 (vstupní token) do služby ACS prostřednictvím protokolu OAuth WRAP.
Služba ACS používá pravidla k výpočtu výstupních deklarací identity, seskupí je do tokenu SWT (výstupního tokenu), podepíše ho a vrátí ho klientovi prostřednictvím protokolu OAuth WRAP.
Požadavek na token SAML musí mít následující parametry a hodnoty:
| Název parametru | Description | Požadavky na hodnotu |
|---|---|---|
wrap_scope |
Odpovídá požadavku na token vůči sadě pravidel. |
|
wrap_assertion |
Jedná se o vstupní token, který se odesílá do služby ACS. |
|
wrap_assertion_format |
Jedná se o formát vstupního tokenu, který se odesílá do služby ACS. |
SAML |
Následuje příklad kódu, který je nutný k vytvoření požadavku na token SAML.
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;
}
}
Informace o tom, jak rozbalit odpověď ze služby ACS a odeslat ji do webové aplikace nebo služby, najdete v tématu Rozbalení a odeslání tokenu do webové aplikace nebo služby.
Kontrolní výraz deklarací identity prostřednictvím protokolu OAuth WRAP
Aby bylo možné zpětnou kompatibilitu s chováním žádosti o token ACS 1.0, služba ACS podporuje možnost uplatnit deklarace identity jako součást požadavků tokenu.
Zaregistrujte aplikaci nebo službu jako zprostředkovatele identity služby ACS.
Doporučeným způsobem je zaregistrovat aplikaci nebo službu jako zprostředkovatele identity služby ACS. Potom aplikace nebo služba požaduje token ze služby ACS tím, že prezentuje token SAML nebo SWT obsahující deklarace identity, které chce uplatnit, a tento token je podepsaný pomocí klíče zprostředkovatele identity uloženého v ACS. Můžete například odeslat požadavek na token SAML s assertovanými deklaracemi identity do služby ACS prostřednictvím protokolu OAuth WRAP ze služby AD FS 2.0 nebo jakékoli vlastní služby tokenů zabezpečení (STS), která je vytvořená pomocí Windows Identity Foundation (WIF) a zaregistrovaná v ACS jako zprostředkovatel identity WS-Federation.
Portál pro správu služby ACS můžete použít k registraci zprostředkovatele identity pomocí WS-Federation metadat nebo můžete službu správy služby ACS použít k individuálnímu nastavení vlastností, adres a klíčů zprostředkovatele identity. (Příklad: Použití služby ACS Management Service ke konfiguraci služby AD FS 2.0 jako zprostředkovatele identity Enterprise.) V této metodě pro uplatnění deklarací identity v požadavku na token se nevyžadují žádné identity služeb. Tato metoda je funkční prostřednictvím všech protokolů podporovaných službou ACS.
Rozbalení a odeslání tokenu do webové aplikace nebo služby
Pokud se požadavek na token úspěšně ověří, služba ACS vrátí dva parametry kódované formulářem: wrap_token a wrap_token_expires_in. Hodnoty těchto parametrů jsou skutečný token SWT, který klient může použít k získání přístupu k webové aplikaci nebo službě a přibližné zbývající životnosti tohoto tokenu (v sekundách).
Před odesláním tokenu SWT webové aplikaci nebo službě musí klient extrahovat a dekódovat ho z odpovědi služby ACS. Pokud webová aplikace nebo služba vyžaduje, aby byl token prezentován v hlavičce HTTP Authorization , musí předcházet schéma WRAPv0.9.
Následující příklad kódu ukazuje, jak rozbalit token a naformátovat hlavičku 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));
Kódy a popisy chyb služby ACS
ACS vrátí chyby, když nemůže splnit požadavek na token. V souladu s návrhem REST obsahuje chyba kód odpovědi HTTP. V mnoha případech obsahují SubCodeDetail chyby služby ACS také kontext týkající se toho, co selhalo. Formát chyby je: Error:Code:<httpStatus>:Sub-Code:<code>:D etail:<message>. Chyba Content-Type je vždy text/prostý.
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>
Další informace o kódech chyb služby ACS najdete v tématu Kódy chyb služby ACS.
Při ladění nebo obnovení z chyby vrácené ze služby ACS se často vyžaduje čtení textu odpovědi. Následující příklad kódu ukazuje, jak číst chybovou zprávu z WebException objektu.
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
}