如何：通过 OAuth WRAP 协议从 ACS 请求令牌

应用于

• Microsoft Azure Active Directory 访问控制（也称为访问控制服务或 ACS）

概述

当 Web 应用程序和服务使用 ACS 处理身份验证时，客户端必须获取 ACS 颁发的安全令牌才能登录到应用程序或服务。 若要获取此 ACS 颁发的令牌 (输出令牌) ，客户端必须直接使用 ACS 进行身份验证，或者向其标识提供者颁发的安全令牌发送 ACS (输入令牌) 。 ACS 验证此输入安全令牌，通过 ACS 规则引擎处理此令牌中的标识声明，计算输出标识声明，并颁发输出安全令牌。

本主题介绍通过 OAuth WRAP 协议从 ACS 请求令牌的方法。 通过 OAuth WRAP 协议传输所有令牌请求都是通过 SSL 传输的。 ACS 始终通过 OAuth WRAP 协议发出简单的 Web 令牌 (SWT) ，以响应格式正确的令牌请求。 通过 OAuth WRAP 协议发出的所有令牌请求都会发送到 HTTP POST 中的 ACS。 可以从任何能够生成 HTTPS FORM POST 的平台（.NET Framework、Windows Communication Foundation (WCF) 、Silverlight、ASP.NET、Java、Python、Ruby、PHP、Flash 和其他平台）通过 OAuth WRAP 协议请求 ACS 令牌。

下表列出了通过 OAuth WRAP 协议请求 ACS 颁发的 SWT 令牌的三种受支持的方法。

通过 OAuth WRAP 协议从 ACS 请求令牌的三种方法

令牌颁发终结点

通过 OAuth WRAP 协议发出的所有 ACS 令牌请求都定向到 ACS 令牌颁发终结点。 此终结点的 URI 取决于访问控制命名空间。 命名空间在令牌请求 URI 中显示为 DNS 名称前缀。 与路径一样，DNS 名称的剩余部分是固定的。 例如，如果要从名为“mysnservice”的访问控制命名空间请求令牌，可以将令牌请求定向到以下 URI： https://mysnservice.accesscontrol.windows.net/WRAPv0.9

密码令牌请求

使用密码令牌请求，客户端可以通过 OAuth WRAP 协议将用户名和密码直接从服务标识发送到 ACS 进行身份验证。 这是使用 OAuth WRAP 协议从 ACS 请求令牌的最简单方法。 除了建立 SSL 连接以外，此方法不需要任何加密功能。 在实践中，这类似于 REST Web 服务中常见的用户名/密码模型。 这种类型的令牌请求实际上是 HTTPS 格式的 POST。 密码令牌请求中的参数已经过格式编码。

以下是向名为“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

下表提供了要在密码令牌请求中提供的参数的名称、说明和值要求：

将请求发送到 ACS 之前，必须对这些参数的值进行 URL 编码。 Web 应用程序或服务可以为客户端提供 wrap_scope 的值，或者客户端可以决定将 wrap_scope 参数的值设置为 Web 应用程序或服务资源目标的 URI。

通过 OAuth WRAP 协议的密码令牌请求还可以包含可在输出声明计算过程中使用的其他参数。 这些附加参数的名称和值必须采用 URL 编码，并且值必须用引号括住。

使用 执行的密码令牌请求方法相当直接。

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

有关如何从 ACS 解压缩输出令牌并将其发送到 Web 应用程序或服务的信息，请参阅取消打包并将令牌发送到 Web 应用程序或服务。

SWT 令牌请求

还可以使用由对称密钥签名的 SWT 令牌通过 OAuth WRAP 协议从 ACS 请求令牌。 所有 SWT 令牌请求都将通过 HTTPS 格式的 POST 发出。 此令牌请求方法中的参数值已经过格式编码。

以下是向“mysnservice”命名空间发出的 SWT 令牌请求线路跟踪示例。

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

SWT 令牌请求必须具有以下参数和值：

如下面的示例中所示，发出 SWT 令牌请求所需的代码类似于发出密码令牌请求所需的代码。

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

有关如何从 ACS 解压缩响应并将其发送到 Web 应用程序或服务的信息，请参阅取消打包并将令牌发送到 Web 应用程序或服务。

创建 SWT 令牌

SWT 令牌是使用颁发者密钥（对称密钥）签名的一组键/值对。 发送到 SWT 令牌请求中的 ACS 的 SWT 令牌必须包含 颁发者和HMACSHA256 参数，以及其他参数，例如 ，ExpiresOn、 Audience 和其他特定于客户端的声明。 下表提供了 SWT 令牌参数的名称和说明：

下面的代码示例演示了如何使用 生成 SWT 令牌。 它包含一个类型，该类型生成包含 Issuer 和 HMACSHA256 参数的 SWT 令牌。

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 令牌请求

SAML 令牌请求方法主要用于 AD FS 2.0 集成，并允许客户端使用企业标识 (Active Directory) 进行身份验证。 使用 SAML 令牌请求方法，可以通过 OAuth WRAP 协议将已签名的 SAML 1.1 或 AD FS 2.0 颁发的 SAML 2. (0 令牌发送到 ACS) 。

ACS 使用其规则来计算输出声明，将声明分组到 SWT 令牌（输出令牌）中，对其进行签名，然后通过 OAuth WRAP 协议将其返回到客户端。

SAML 令牌请求必须具有以下参数和值：

以下是发出 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;
 }
}  

有关如何从 ACS 解压缩响应并将其发送到 Web 应用程序或服务的信息，请参阅取消包装令牌并将其发送到 Web 应用程序或服务。

通过 OAuth WRAP 协议声明断言

若要启用与 ACS 1.0 令牌请求行为的向后兼容性，ACS 支持在令牌请求过程中断言声明的功能。

将断言应用程序或服务注册为 ACS 标识提供程序。

执行此操作的建议方法是将断言应用程序或服务注册为 ACS 标识提供程序。 然后，应用程序或服务通过提供包含要断言的声明的 SAML 或 SWT 令牌来请求 ACS 中的令牌，并且此令牌使用 ACS 中存储的标识提供者密钥进行签名。 例如，可以通过 AD FS 2.0 或任何自定义安全令牌服务 (STS) （使用 Windows Identity Foundation (WIF) 在 ACS 中注册为WS-Federation标识提供者）通过 OAuth WRAP 协议将具有断言声明的 SAML 令牌请求发送到 ACS。

可以使用 ACS 管理门户通过WS-Federation元数据注册标识提供者，也可以使用 ACS 管理服务单独设置标识提供者属性、地址和密钥。 (例如，请参阅如何：使用 ACS 管理服务将 AD FS 2.0 配置为Enterprise标识提供者.) 这种在令牌请求中断言声明的方法不需要服务标识。 此方法通过所有 ACS 支持的协议正常运行。

解包令牌并将其发送到 Web 应用程序或服务

如果令牌请求已成功进行身份验证，ACS 将返回两个格式编码的参数： wrap_token 和 wrap_token_expires_in。 这些参数的值分别是客户端可用来访问 Web 应用程序或服务的实际 SWT 令牌，以及此令牌的近似剩余生存期（以秒为单位）。

在将 SWT 令牌发送到 Web 应用程序或服务之前，客户端必须从 ACS 响应中提取和对它进行 URL 解码。 如果 Web 应用程序或服务要求在 HTTP Authorization 标头中提供令牌，该令牌的前面必须带有方案 WRAPv0.9。

下面的代码示例演示了如何解包令牌和设置 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 错误代码和描述

ACS 在无法满足令牌请求时返回错误。 错误中包含与 REST 设计相一致的 HTTP 响应代码。 在许多情况下，ACS 错误还包含一个 SubCode 并提供 Detail 有关失败情况的上下文。 错误格式为：Error：Code：<httpStatus>：Sub-Code：code>:D etail：<<message>。 错误的 Content-Type 始终是 text/plain。

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>

有关 ACS 错误代码的详细信息，请参阅 ACS 错误代码。

从 ACS 返回的错误进行调试或恢复时，通常需要读取响应正文。 下面的代码示例演示如何从 WebException 对象读取错误消息。

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
}

另请参阅

概念

ACS 操作指南