Vorgehensweise: Anfordern eines Token von ACS über das OAuth WRAP-Protokoll
Gilt für
- Zugriffssteuerung für Microsoft Azure Active Directory (auch Zugriffssteuerungsdienst oder ACS)
Übersicht
Wenn Ihre Webanwendungen und Dienste die Authentifizierung mithilfe von ACS verarbeiten, muss der Client ein von ACS ausgestelltes Sicherheitstoken abrufen, um sich bei Ihrer Anwendung oder Ihrem Dienst anzumelden. Um dieses ACS-ausgestellte Token (Ausgabetoken) abzurufen, muss der Client entweder direkt mit ACS authentifizieren oder ACS ein Sicherheitstoken senden, das vom Identitätsanbieter (Eingabetoken) ausgestellt wurde. ACS überprüft dieses Eingabesicherheitstoken, verarbeitet die Identitätsansprüche in diesem Token über das ACS-Regelmodul, berechnet die Ausgabeidentitätsansprüche und stellt ein Ausgabesicherheitstoken dar.
In diesem Thema werden die Methoden zum Anfordern eines Token von ACS über das OAuth WRAP-Protokoll beschrieben. Alle Tokenanforderungen über das OAuth WRAP-Protokoll werden über SSL übertragen. ACS stellt immer ein Einfaches Webtoken (SWT) über das OAuth WRAP-Protokoll in Reaktion auf eine ordnungsgemäß formatierte Tokenanforderung bereit. Alle Tokenanforderungen über das OAuth WRAP-Protokoll werden an ACS in einem HTTP POST gesendet. Sie können ein ACS-Token über das OAuth WRAP-Protokoll aus einer beliebigen Plattform anfordern, die einen HTTPS FORM POST erstellen kann: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash und andere Plattformen.
In der folgenden Tabelle sind drei unterstützte Methoden aufgeführt, mit denen über das OAuth WRAP-Protokoll ein ACS-ausgestelltes SWT-Token angefordert wird.
Drei Verfahren zum Anfordern eines Tokens bei ACS mithilfe des OAuth-WRAP-Protokolls
| Tokenanforderungsverfahren | BESCHREIBUNG |
|---|---|
Kennworttokenanforderungen |
Diese einfachste Methode erfordert, dass der Client einen Benutzernamen und ein Kennwort direkt an ACS über das OAuth WRAP-Protokoll zur Authentifizierung senden kann. |
SWT-Tokenanforderungen |
Diese Methode erfordert, dass der Client ein SWT-Token sendet, das mit einem dienstidentitätssymmetrischen Schlüssel oder einem symmetrischen Identitätsanbieterschlüssel über das OAuth WRAP-Protokoll für die Authentifizierung signiert werden kann. |
SAML-Tokenanforderungen |
In erster Linie für die Integration des Active Directory-Verbunddiensts (AD FS) 2.0 ist die Security Assertion Markup Language (SAML) -Methode erforderlich, um ein signiertes SAML-Token über das OAuth WRAP-Protokoll zur Authentifizierung an ACS zu senden. Mit diesem Ansatz kann der Client eine Unternehmensidentität verwenden, um sich mit ACS zu authentifizieren. |
Token ausgebender Endpunkt
Alle ACS-Tokenanforderungen über das OAuth WRAP-Protokoll werden an einem ACS-Tokenausstellendpunkt geleitet. Der URI dieses Endpunkts hängt vom Access Control Namespace ab. Der Namespace erscheint im URI von Tokenanforderungen als DNS-Namenspräfix. Der Rest des DNS-Namens ist fest, ebenso der Pfad. Wenn Sie beispielsweise ein Token aus dem Access Control Namespace namens "mysnservice" anfordern möchten, können Sie eine Tokenanforderung an den folgenden URI weiterleiten: https://mysnservice.accesscontrol.windows.net/WRAPv0.9
Kennworttokenanforderungen
Mit einer Kennworttokenanforderung kann ein Client einen Benutzernamen und ein Kennwort direkt an ACS über das OAuth WRAP-Protokoll zur Authentifizierung senden. Dies ist die einfachste Möglichkeit, ein Token von ACS mithilfe des OAuth WRAP-Protokolls anzufordern. Im Gegensatz zum Einrichten einer SSL-Verbindung erfordert dieser Ansatz keine Kryptografiefähigkeit. Praktisch ähnelt es dem Modell von Benutzername/Kennwort, das in REST-Webdiensten vorherrschend ist. Diese Art Tokenanforderung stellt tatsächlich einen HTTPS-Formular-POST dar. Die Parameter in einer Kennworttokenanforderung sind formularcodiert.
Das folgende Beispiel ist eine Skizze für eine Klartextanforderung an einen Namespace mit dem Namen "meinsnservice".
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
Die Tabelle unten enthält die Namen, Beschreibungen und erforderlichen Parameterwerte, die in einer Kennworttokenanforderung vorhanden sein müssen:
| Parametername | BESCHREIBUNG | Wertanforderungen |
|---|---|---|
wrap_scope |
Ordnet die Tokenanforderung anhand einer Menge von Regeln zu. Legen Sie den Wert dieses Parameters auf den Wert des Bereichs der Anwendung der vertrauenden Seite fest. Sie können diesen Wert ( im Bereichsfeld ) über das ACS-Verwaltungsportal abrufen, indem Sie die entsprechende vertrauende Parteianwendung auf der Seite " Vertrauende Parteianwendungen " auswählen. |
|
wrap_name |
Überprüft den Schlüssel des nächsten Parameters. Legen Sie den Wert dieses Parameters auf den Namen einer Dienstidentität in Ihrem Access Control Namespace fest. Sie können diesen Wert (im Feld "Name ") über das ACS-Verwaltungsportal abrufen, indem Sie die entsprechende Dienstidentität auf der Seite "Dienstidentitäten " auswählen. |
|
wrap_password |
Authentifiziert die eingehende Anforderung. Legen Sie den Wert dieses Parameters auf das Kennwort einer Dienstidentität innerhalb Ihres Access Control Namespace fest. Sie können diesen Wert (im Kennwortfeld auf der Seite "Anmeldeinformationen bearbeiten") über das ACS-Verwaltungsportal abrufen, indem Sie zuerst die entsprechende Dienstidentität auf der Seite "Dienstidentitäten" auswählen und dann das entsprechende Kennwort auf der Seite "Anmeldeinformationen bearbeiten" auf der Seite "Dienstidentität bearbeiten" auswählen. |
|
Die Werte dieser Parameter müssen URL-codiert sein, bevor Sie die Anforderung an ACS senden. Ihre Webanwendung oder Ihr Dienst kann den Wert des wrap_scope für den Client bereitstellen, oder der Client kann entscheiden, den Wert des wrap_scope-Parameters auf den URI der Webanwendung oder des Dienstressourceziels festzulegen.
Kennworttokenanforderungen über das OAuth WRAP-Protokoll können auch zusätzliche Parameter enthalten, die ACS während des Ausgabeanspruchsberechnungsprozesses verwenden kann. Die Namen und Werte dieser zusätzlichen Parameter müssen URL-codiert sein und die Werte dürfen nicht in Anführung stehen.
Das Kennworttokenanforderungs-Verfahren ist ziemliche geradlinig in seiner Verwendung von .
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);
Informationen zum Entpacken des Ausgabetokens von ACS und zum Senden an die Webanwendung oder den Dienst finden Sie unter Entwrapping und Senden des Token an eine Webanwendung oder einen Dienst.
SWT-Tokenanforderungen
Sie können auch ein Token von ACS über das OAuth WRAP-Protokoll anfordern, indem Sie ein SWT-Token verwenden, das von einem symmetrischen Schlüssel signiert ist. Alle SWT-Tokenanforderungen erfolgen mittels eines HTTPS-Formular-POSTs. Die Parameterwerte in dieser Tokenanforderungsmethode sind formularcodiert.
Das Folgendes ist ein Beispiel einer Ablaufverfolgung einer SWT-Tokenanforderung mit dem Namespace "meinsnservice" über das Netzwerk.
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
Eine SWT-Tokenanforderung muss die folgenden Parameter und Werte aufweisen:
| Parametername | BESCHREIBUNG | Wertanforderungen |
|---|---|---|
wrap_scope |
Ordnet die Tokenanforderung anhand einer Menge von Regeln zu. |
|
wrap_assertion |
Dies ist das Eingabetoken, das an ACS gesendet wird. |
|
wrap_assertion_format |
Dies ist das Format des Eingabetokens, das an ACS gesendet wird. |
SWT |
Wie im folgenden Beispiel gezeigt, ähnelt der Code, der erforderlich ist, um eine SWT-Tokenanforderung zu stellen, dem Code, der für eine Kennworttokenanforderung erforderlich ist.
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);
Informationen zum Entpacken der Antwort von ACS und zum Senden an Ihre Webanwendung oder Ihren Dienst finden Sie unter Aufheben und Senden des Token an eine Webanwendung oder einen Dienst.
Erstellen eines SWT-Tokens
Ein SWT-Token ist ein Satz von Schlüssel/Wert-Paaren, die mit einem Ausstellerschlüssel (einen symmetrischen Schlüssel) signiert werden. Ein SWT-Token, das an ACS in einer SWT-Tokenanforderung gesendet wurde, muss die Parameter "Aussteller " und "HMACSHA256 " sowie zusätzliche Parameter enthalten, z. B. "ExpiresOn", " Audience" und andere clientspezifische Ansprüche. Die folgende Tabelle enthält die Namen und Beschreibungen von SWT-Tokenparametern:
| Parametername | BESCHREIBUNG |
|---|---|
Aussteller |
Sucht in ACS nach dem Schlüssel, der zum Signieren des Token verwendet wurde. Wenn die Signatur gültig ist, wird dieser Wert verwendet, um die Berechnung des Ausgabeanspruchs durchzuführen. Sie können diesen Parameter auf den Wert des Bereichs eines Identitätsanbieters innerhalb Ihres Access Control Namespace oder den Namen einer Dienstidentität innerhalb Ihres Access Control Namespace festlegen. Sie können diesen Wert ( im Bereichsfeld auf der Seite "Identitätsanbieter bearbeiten ") über das ACS-Verwaltungsportal abrufen, indem Sie den entsprechenden Identitätsanbieter auf der Seite "Identitätsanbieter bearbeiten" auswählen. Oder Sie können diesen Wert über den ACS Management Service abrufen – dies ist die Nameeigenschaft des "Issuer"-Datensatzes, der für jeden Identitätsanbieter erstellt wird. |
HMACSHA256 |
Überprüft in ACS die SWT-Signatur und sucht den Ausstellerschlüssel im Parameter "Aussteller". Die SWT-Signatur wird mithilfe des symmetrischen Signaturschlüssels erstellt, der an eine Dienstidentität oder einen Identitätsanbieter in Ihrem Access Control-Namespace angefügt ist. |
Zielgruppe |
Wenn vorhanden, verwendet ACS diesen Wert, um sicherzustellen, dass ACS das beabsichtigte Ziel des SWT-Token ist. Dies ist die URL Ihres Access Control-Namespaces, z. B.https://contoso.accesscontrol.windows.net/ |
AbläuftOn |
Gibt falls vorhanden (in Epochenzeit) an, ob das Token abgelaufen ist. Beispielsweise kann der Wert dieses Parameters |
Zusätzliche Ansprüche |
Wenn vorhanden, verwendet ACS diese Parameter zum Ausführen der Ausgabeanspruchsberechnung. Jeder Anspruchstyp darf nur ein Mal vorkommen. Mehrere Anspruchswerte des gleichen Anspruchstyps müssen mit einem Komma (",") verkettet werden. Weitere Informationen zur Durchsetzung von Ansprüchen in ACS finden Sie unter Anspruchsbesicherung über das OAuth WRAP-Protokoll. |
Das folgende Codebeispiel zeigt, wie ein SWT-Token mithilfe von erstellt wird. Es enthält einen Typ, der SWT-Token erstellt, die die Parameter Issuer und HMACSHA256 enthalten.
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-Tokenanforderungen
Die SAML-Tokenanforderungsmethode ist hauptsächlich für die AD FS 2.0-Integration vorgesehen und ermöglicht es dem Client, eine Unternehmensidentität (Active Directory) zum Authentifizieren mit ACS zu verwenden. Mit der SAML-Tokenanforderungsmethode können Sie eine signierte SAML 1.1 oder ein SAML 2.0-Token senden, das von AD FS 2.0 (Eingabetoken) über das OAuth WRAP-Protokoll an ACS ausgestellt wurde.
ACS verwendet seine Regeln, um die Ausgabeansprüche zu berechnen, gruppiert sie in einem SWT-Token (Ausgabetoken), signiert es und schickt es über das OAuth-WRAP-Protokoll an den Client zurück.
Eine SAML-Tokenanforderung muss die folgenden Parameter und Werte aufweisen:
| Parametername | BESCHREIBUNG | Wertanforderungen |
|---|---|---|
wrap_scope |
Ordnet die Tokenanforderung anhand einer Menge von Regeln zu. |
|
wrap_assertion |
Dies ist das Eingabetoken, das an ACS gesendet wird. |
|
wrap_assertion_format |
Dies ist das Format des Eingabetokens, das an ACS gesendet wird. |
SAML |
Folgendes ist ein Beispiel für den Code, der für SAML-Tokenanforderungen erforderlich ist.
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;
}
}
Informationen zum Entpacken der Antwort von ACS und zum Senden an Ihre Webanwendung oder Ihren Dienst finden Sie unter Aufheben und Senden des Token an eine Webanwendung oder einen Dienst.
Anspruchsbestätigung mithilfe des OAuth-WRAP-Protokolls
Um die Abwärtskompatibilität mit ACS 1.0-Tokenanforderungsverhalten zu aktivieren, unterstützt ACS die Möglichkeit, Ansprüche als Teil von Tokenanforderungen geltend zu machen.
Registrieren Sie die bestätigende Anwendung oder den bestätigenden Dienst als ACS-Identitätsanbieter.
Das empfohlene Verfahren besteht darin die bestätigende Anwendung oder den bestätigenden Dienst als ACS-Identitätsanbieter zu registrieren. Anschließend fordert die Anwendung oder der Dienst ein Token von ACS an, indem ein SAML- oder SWT-Token angezeigt wird, das die Ansprüche enthält, die er festlegen möchte, und dieses Token wird mithilfe eines in ACS gespeicherten Identitätsanbieterschlüssels signiert. Sie können beispielsweise eine SAML-Tokenanforderung mit behaupteten Ansprüchen an ACS über das OAuth WRAP-Protokoll von AD FS 2.0 oder einen benutzerdefinierten Security Token Service (STS) senden, der mithilfe Windows Identity Foundation (WIF) erstellt und als WS-Federation Identitätsanbieter registriert ist.
Sie können das ACS-Verwaltungsportal verwenden, um einen Identitätsanbieter mit WS-Federation Metadaten zu registrieren, oder Sie können den ACS-Verwaltungsdienst verwenden, um Identitätsanbietereigenschaften, Adressen und Schlüssel einzeln festzulegen. (Beispiel: Verwenden des ACS-Verwaltungsdiensts zum Konfigurieren von AD FS 2.0 als Enterprise Identitätsanbieter.) Bei diesem Verfahren der Bestätigung von Ansprüchen in einer Tokenanforderung werden keine Dienstidentitäten benötigt. Diese Methode ist über alle ACS-unterstützten Protokolle funktionsfähig.
Entpacken und Senden des Tokens an eine Webanwendung oder einen Webdienst
Wenn die Tokenanforderung erfolgreich authentifiziert wird, gibt ACS zwei formularcodierte Parameter zurück: wrap_token und wrap_token_expires_in. Die Werte dieser Parameter sind das eigentliche SWT-Token, das der Client verwenden kann, um Zugriff auf Ihre Webanwendung oder Ihren Webdienst zu erhalten, und die ungefähre verbleibende Lebensdauer in Sekunden.
Bevor Sie das SWT-Token an die Webanwendung oder den Dienst senden, muss der Client ihn aus der ACS-Antwort extrahieren und URL-decoden. Wenn die Webanwendung oder der Webdienst die Übergabe des Tokens im Authorization-Header erfordert, muss dem Token das WRAPv0.9-Schema vorangestellt sein.
Das folgende Codebeispiel veranschaulicht, wie ein Token entpackt und der Authorization-Header formatiert wird.
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-Fehlercodes und -beschreibungen
ACS gibt Fehler zurück, wenn sie eine Tokenanforderung nicht erfüllen kann. In Übereinstimmung mit dem REST-Entwurf enthält der Fehler einen HTTP-Antwortcode. In vielen Fällen enthalten ACS-Fehler auch einen SubCodeDetail Kontext zu dem, was fehlgeschlagen ist. Das Fehlerformat lautet: Error:Code:httpStatus>:Sub-Code:code><:D etail<:<message>. Der Content-Type eines Fehlers ist immer Text/unformatiert.
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>
Weitere Informationen zu ACS-Fehlercodes finden Sie unter ACS-Fehlercodes.
Beim Debuggen oder Wiederherstellen eines fehlers, der von ACS zurückgegeben wird, ist es häufig erforderlich, den Antworttext zu lesen. Im folgenden Codebeispiel wird gezeigt, wie die Fehlermeldung aus einem WebException-Objekt gelesen wird.
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
}