Procedure: Een token aanvragen bij ACS via het OAuth WRAP-protocol

Artikel
11/09/2015

Van toepassing op

Microsoft Azure Active Directory Access Control (ook wel bekend als Access Control Service of ACS)

Overzicht

Wanneer uw webtoepassingen en -services verificatie verwerken met BEHULP van ACS, moet de client een beveiligingstoken verkrijgen dat is uitgegeven door ACS om u aan te melden bij uw toepassing of service. Om dit door ACS uitgegeven token (uitvoertoken) te verkrijgen, moet de client zich rechtstreeks verifiëren bij ACS of ACS een beveiligingstoken verzenden dat is uitgegeven door de id-provider (invoertoken). ACS valideert dit invoerbeveiligingstoken, verwerkt de identiteitsclaims in dit token via de ACS-regelengine, berekent de uitvoeridentiteitsclaims en geeft een uitvoerbeveiligingstoken uit.

In dit onderwerp worden de methoden beschreven voor het aanvragen van een token van ACS via het OAuth WRAP-protocol. Alle tokenaanvragen via het OAuth WRAP-protocol worden verzonden via SSL. ACS geeft altijd een Simple Web Token (SWT) uit via het OAuth WRAP-protocol, als reactie op een correct opgemaakte tokenaanvraag. Alle tokenaanvragen via het OAuth WRAP-protocol worden verzonden naar ACS in een HTTP POST. U kunt een ACS-token aanvragen via het OAuth WRAP-protocol vanaf elk platform dat een HTTPS FORM POST kan maken: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash en andere platforms.

De volgende tabel bevat drie ondersteunde methoden voor het aanvragen van een DOOR ACS uitgegeven SWT-token via het OAuth WRAP-protocol.

Drie methoden voor het aanvragen van een token van ACS via het OAuth WRAP-protocol

Methode voor tokenaanvraag	Description
Wachtwoordtokenaanvragen	Voor deze eenvoudigste methode moet de client een gebruikersnaam en wachtwoord rechtstreeks vanuit een service-id rechtstreeks naar ACS verzenden via het OAuth WRAP-protocol voor verificatie.
SWT-tokenaanvragen	Voor deze methode moet de client een SWT-token verzenden dat kan worden ondertekend met een symmetrische sleutel van een service-id of een symmetrische sleutel van een id-provider naar ACS via het OAuth WRAP-protocol voor verificatie.
SAML-tokenaanvragen	Voor de integratie van Active Directory Federation Service (AD FS) 2.0 is de methode Security Assertion Markup Language (SAML) vereist dat de client een ondertekend SAML-token naar ACS verzendt via het OAuth WRAP-protocol voor verificatie. Met deze methode kan de client een bedrijfsidentiteit gebruiken om te verifiëren met ACS.

Eindpunt voor tokenuitgifte

Alle ACS-tokenaanvragen via het OAuth WRAP-protocol worden gericht op een ACS-tokenuitgevende eindpunt. De URI van dit eindpunt is afhankelijk van de Access Control naamruimte. De naamruimte wordt weergegeven als een DNS-naamvoorvoegsel in een tokenaanvraag-URI. De rest van de DNS-naam is opgelost, net als het pad. Als u bijvoorbeeld een token wilt aanvragen vanuit de Access Control naamruimte met de naam 'mysnservice', kunt u een tokenaanvraag doorsturen naar de volgende URI: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

Wachtwoordtokenaanvragen

Met een wachtwoordtokenaanvraag kan een client een gebruikersnaam en wachtwoord rechtstreeks vanuit een service-id rechtstreeks naar ACS verzenden via het OAuth WRAP-protocol voor verificatie. Dit is de eenvoudigste manier om een token aan te vragen bij ACS met behulp van het OAuth WRAP-protocol. Behalve het tot stand brengen van een SSL-verbinding, is voor deze benadering geen cryptografische mogelijkheid vereist. In de praktijk is het vergelijkbaar met het gebruikersnaam-/wachtwoordmodel dat gangbaar is in REST-webservices. Dit type tokenaanvraag is eigenlijk een HTTPS-formulier POST. De parameters in een wachtwoordtokenaanvraag zijn in een formulier gecodeerd.

Hier volgt een voorbeeld van een draadtracering van een aanvraag zonder opmaak naar een naamruimte met de naam 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

De onderstaande tabel bevat de namen, beschrijvingen en waardevereisten van de parameters die vereist zijn om aanwezig te zijn in een wachtwoordtokenaanvraag:

Parameternaam	Beschrijving	Waardevereisten
wrap_scope	Komt overeen met de tokenaanvraag op basis van een set regels. Stel de waarde van deze parameter in op de waarde van de relying party-toepassingsrealm. U kunt deze waarde (in het veld Realm ) verkrijgen via de ACS-beheerportal door de juiste relying party-toepassing te selecteren op de pagina Relying Party-toepassingen .	HTTP- of HTTP-URI('s) Geen queryparameters of ankers. Padsegmenten <= 32. Maximale lengte: 256 tekens. Moet url-gecodeerd zijn.
wrap_name	Valideert de sleutel van de volgende parameter. Stel de waarde van deze parameter in op de naam van een service-identiteit binnen uw Access Control naamruimte. U kunt deze waarde (in het veld Naam ) verkrijgen via de ACS-beheerportal door de juiste service-id te selecteren op de pagina Service-identiteiten .	Minimale lengte: 1 teken. Maximale lengte: 128 tekens. Moet url-gecodeerd zijn.
wrap_password	Hiermee wordt de binnenkomende aanvraag geverifieerd. Stel de waarde van deze parameter in op het wachtwoord van een service-identiteit binnen uw Access Control naamruimte. U kunt deze waarde verkrijgen (in het veld Wachtwoord op de pagina Referentie bewerken ), via de ACS-beheerportal door eerst de juiste service-id te selecteren op de pagina Service-identiteiten en vervolgens het juiste wachtwoord te selecteren in de tabel Referenties op de pagina Service-identiteit bewerken .	Tekenreeks, minimaal 1 en maximaal 64 tekens lang. Moet url-gecodeerd zijn.

De waarden van deze parameters moeten url-gecodeerd zijn voordat u de aanvraag naar ACS verzendt. Uw webtoepassing of -service kan de waarde van de wrap_scope aan de client leveren, of de client kan besluiten om de waarde van de parameter wrap_scope in te stellen op de URI van de webtoepassing of het serviceresourcedoel.

Wachtwoordtokenaanvragen via het OAuth WRAP-protocol kunnen ook aanvullende parameters bevatten die ACS kan gebruiken tijdens het berekeningsproces van de uitvoerclaim. Deze aanvullende parameternamen en -waarden moeten url-gecodeerd zijn en waarden mogen niet worden geciteerd.

De aanvraagmethode voor het wachtwoordtoken is vrij eenvoudig met behulp van.

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

Zie Het token uitpakken en verzenden naar de webtoepassing of -service voor meer informatie over het uitpakken van het uitvoertoken van ACS en het verzenden ervan naar de webtoepassing of -service.

SWT-tokenaanvragen

U kunt ook een token aanvragen bij ACS via het OAuth WRAP-protocol met behulp van een SWT-token dat is ondertekend door een symmetrische sleutel. Alle SWT-tokenaanvragen worden gedaan via een HTTPS-formulierPOST. De parameterwaarden in deze tokenaanvraagmethode worden in een formulier gecodeerd.

Hier volgt een voorbeeld van een draadtracering van een SWT-tokenaanvraag naar de naamruimte '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

Een SWT-tokenaanvraag moet de volgende parameters en waarden hebben:

Parameternaam	Beschrijving	Waardevereisten
wrap_scope	Komt overeen met de tokenaanvraag op basis van een set regels.	Stel de waarde van deze parameter in op de waarde van de relying party-toepassingsrealm. U kunt deze waarde (in het veld Realm ) verkrijgen via de ACS-beheerportal door de juiste relying party-toepassing te selecteren op de pagina Relying Party-toepassingen . HTTP- of HTTP-URI('s). Geen queryparameters of ankers. Padsegmenten <= 32. Maximale lengte: 256 tekens. Moet een URL zijn gecodeerd.
wrap_assertion	Dit is het invoertoken dat naar ACS wordt verzonden.	Een ondertekend SWT-token met invoerclaims die verlener- en HMACSHA256-parameters bevatten. Maximale lengte: 2048 tekens. Moet een URL zijn gecodeerd.
wrap_assertion_format	Dit is de indeling van het invoertoken dat naar ACS wordt verzonden.	SWT

Zoals in het volgende voorbeeld wordt weergegeven, lijkt de code die is vereist voor het maken van een SWT-tokenaanvraag op de code die is vereist om een wachtwoordtokenaanvraag te maken.

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

Zie Het token uitpakken en verzenden naar een webtoepassing of -service voor meer informatie over het uitpakken van het antwoord van ACS en het verzenden ervan naar uw webtoepassing of -service.

Een SWT-token maken

Een SWT-token is een set sleutel-waardeparen die zijn ondertekend met een verlenersleutel (een symmetrische sleutel). Een SWT-token dat is verzonden naar ACS in een SWT-tokenaanvraag, moet de parameters Issuer en HMACSHA256 bevatten, evenals aanvullende parameters, bijvoorbeeld ExpiresOn, Audience en andere clientspecifieke claims. De volgende tabel bevat de namen en beschrijvingen van swt-tokenparameters:

Parameternaam	Beschrijving
Uitgevende instelling	Zoek in ACS de sleutel op die is gebruikt om het token te ondertekenen. Als de handtekening geldig is, wordt deze waarde gebruikt om de berekening van uitvoerclaims uit te voeren. U kunt deze parameter instellen op de waarde van het realm van een id-provider binnen uw Access Control naamruimte of de naam van een service-id binnen uw Access Control naamruimte. U kunt deze waarde (in het veld Realm op de pagina Id-provider bewerken ) verkrijgen via de ACS-beheerportal door de juiste id-provider te selecteren op de pagina Id-providers. U kunt deze waarde ook verkrijgen via de ACS Management-service. Dit is de naameigenschap van de record Issuer die voor elke id-provider wordt gemaakt.
HMACSHA256	Valideert in ACS de SWT-handtekening en zoekt de sleutel van de verlener op met de parameter Issuer . De SWT-handtekening wordt gemaakt met behulp van de symmetrische ondertekeningssleutel die is gekoppeld aan een service-id of een id-provider in uw Access Control naamruimte.
Doelgroep	Indien aanwezig, gebruikt ACS deze waarde om ervoor te zorgen dat ACS het beoogde doel van het SWT-token is. Dit is bijvoorbeeld de URL van uw Access Control naamruimtehttps://contoso.accesscontrol.windows.net/
ExpiresOn	Indien aanwezig (in epochtijd), geeft u aan of het token is verlopen. De waarde van deze parameter kan bijvoorbeeld zijn `1324300962`.
Aanvullende claims	Indien aanwezig, gebruikt ACS deze parameters om de berekening van uitvoerclaims uit te voeren. Elk claimtype mag slechts één keer worden weergegeven. Meerdere claimwaarden van hetzelfde claimtype moeten worden samengevoegd met een "," (komma). Zie Claims assertion via het OAuth WRAP-protocol voor meer informatie over het asserteren van claims in ACS.

In het volgende codevoorbeeld ziet u hoe u een SWT-token genereert met behulp van . Het bevat een type waarmee SWT-tokens worden gebouwd die de parameters Issuer en HMACSHA256 bevatten.

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-tokenaanvragen

De SAML-tokenaanvraagmethode is voornamelijk bedoeld voor de AD FS 2.0-integratie en stelt de client in staat om een bedrijfsidentiteit (Active Directory) te gebruiken om te verifiëren met ACS. Met de aanvraagmethode SAML-token kunt u een ondertekende SAML 1.1 of een SAML 2.0-token verzenden dat is uitgegeven door AD FS 2.0 (invoertoken) naar ACS via het OAuth WRAP-protocol.

ACS gebruikt de regels voor het berekenen van de uitvoerclaims, groepeert deze in een SWT-token (uitvoertoken), ondertekent het en retourneert deze naar de client via het OAuth WRAP-protocol.

Een SAML-tokenaanvraag moet de volgende parameters en waarden hebben:

Parameternaam	Beschrijving	Waardevereisten
wrap_scope	Komt overeen met de tokenaanvraag op basis van een set regels.	Stel de waarde van deze parameter in op de waarde van de relying party-toepassingsrealm. U kunt deze waarde (in het veld Realm ) verkrijgen via de ACS-beheerportal door de juiste relying party-toepassing te selecteren op de pagina Relying Party-toepassingen . HTTP- of HTTP-URI('s). Geen queryparameters of ankers. Padsegmenten <= 32. Maximale lengte: 256 tekens. Moet een URL zijn gecodeerd.
wrap_assertion	Dit is het invoertoken dat naar ACS wordt verzonden.	Een ondertekend SAML 1.1- of 2.0-token met invoerclaims. VOOR SAML 1.1-tokens is ten minste één invoerclaim vereist als een tokenbeperking. Dit betekent dat een id-provider of een service-id met claims moet worden gebruikt voor SAML 1.1-tokenverificatie. SAML 2.0-tokens vereisen geen invoerclaims voor verificatie op basis van een service-identiteit, afgezien van de impliciete NameIdentifier-claim, daarom kunnen SAML 2.0-tokens worden gebruikt om te verifiëren tegen een normale service-identiteit die niet is ingeschakeld voor claims. Moet een URL zijn gecodeerd.
wrap_assertion_format	Dit is de indeling van het invoertoken dat naar ACS wordt verzonden.	SAML

Hier volgt een voorbeeld van de code die is vereist voor het maken van een SAML-tokenaanvraag.

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

Zie Het token uitpakken en verzenden naar een webtoepassing of -service voor meer informatie over het uitpakken van het antwoord van ACS en het verzenden ervan naar uw webtoepassing of -service.

Claimbevestiging via het OAuth WRAP-protocol

Acs ondersteunt de mogelijkheid om claims te bevestigen als onderdeel van tokenaanvragen om achterwaartse compatibiliteit met ACS 1.0-tokenaanvragen mogelijk te maken.

Registreer de assertietoepassing of -service als ACS-id-provider.

De aanbevolen manier om dit te doen, is door de assertietoepassing of -service te registreren als ACS-id-provider. Vervolgens vraagt de toepassing of service een token van ACS aan door een SAML- of SWT-token te presenteren dat de claims bevat die het wil bevestigen. Dit token wordt ondertekend met behulp van een id-providersleutel die is opgeslagen in ACS. U kunt bijvoorbeeld een SAML-tokenaanvraag met assertieclaims verzenden naar ACS via het OAuth WRAP-protocol van AD FS 2.0 of een aangepaste BEVEILIGINGstokenservice (STS) die is gebouwd met behulp van Windows Identity Foundation (WIF) en is geregistreerd in ACS als een WS-Federation-id-provider.

U kunt de ACS-beheerportal gebruiken om een id-provider te registreren met behulp van WS-Federation metagegevens, of u kunt de ACS Management Service gebruiken om de eigenschappen, adressen en sleutels van de id-provider afzonderlijk in te stellen. (Zie bijvoorbeeld Procedure: ACS Management Service gebruiken om AD FS 2.0 te configureren als een Enterprise Identity Provider.) Er zijn geen service-identiteiten vereist in deze methode voor het bevestigen van claims in een tokenaanvraag. Deze methode is functioneel via alle door ACS ondersteunde protocollen.

Het token uitpakken en verzenden naar een webtoepassing of -service

Als de tokenaanvraag is geverifieerd, retourneert ACS twee met formulieren gecodeerde parameters: wrap_token en wrap_token_expires_in. De waarden van deze parameters zijn het werkelijke SWT-token dat de client kan gebruiken om toegang te krijgen tot uw webtoepassing of -service en respectievelijk de resterende levensduur van dit token (in seconden).

Voordat het SWT-token naar de webtoepassing of -service wordt verzonden, moet de client het extraheren en de URL decoderen van het ACS-antwoord. Als de webtoepassing of -service vereist dat het token wordt weergegeven in de HTTP-header Authorization , moet het token worden voorafgegaan door het schema WRAPv0.9.

In het volgende codevoorbeeld ziet u hoe u een token uitpakt en de Authorization header formatteert.

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-foutcodes en -beschrijvingen

ACS retourneert fouten wanneer deze niet kan voldoen aan een tokenaanvraag. In overeenstemming met het REST-ontwerp bevat de fout een HTTP-antwoordcode. In veel gevallen bevatten ACS-fouten ook een SubCode en Detail die context bieden over wat er is mislukt. De foutindeling is: Error:Code:<httpStatus>:Sub-Code:<code>:D etail:<message>. De Content-Type fout is altijd tekst/tekst zonder opmaak.

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>

Zie ACS-foutcodes voor meer informatie over ACS-foutcodes.

Bij het opsporen van fouten of het herstellen van een fout die is geretourneerd vanuit ACS, is het vaak vereist om de hoofdtekst van het antwoord te lezen. In het volgende codevoorbeeld ziet u hoe u het foutbericht van een WebException-object kunt lezen.

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
}

Zie ook

Concepten

ACS-procedures

Share via