Como solicitar um token do ACS por meio do protocolo OAuth WRAP

Aplica-se A

• Access Control do Active Directory do Microsoft Azure (também conhecido como Access Control Service ou ACS)

Visão geral

Quando seus aplicativos Web e serviços lidam com a autenticação usando o ACS, o cliente deve obter um token de segurança emitido pelo ACS para fazer logon em seu aplicativo ou serviço. Para obter esse token emitido pelo ACS (token de saída), o cliente deve autenticar diretamente com o ACS ou enviar ao ACS um token de segurança emitido por seu provedor de identidade (token de entrada). O ACS valida esse token de segurança de entrada, processa as declarações de identidade nesse token por meio do mecanismo de regras acs, calcula as declarações de identidade de saída e emite um token de segurança de saída.

Este tópico descreve os métodos de solicitação de um token do ACS por meio do protocolo OAuth WRAP. Todas as solicitações de token por meio do protocolo OAuth WRAP são transmitidas por SSL. O ACS sempre emite um SWT (Token Web Simples) por meio do protocolo OAuth WRAP, em resposta a uma solicitação de token formatada corretamente. Todas as solicitações de token por meio do protocolo OAuth WRAP são enviadas ao ACS em um HTTP POST. Você pode solicitar um token ACS por meio do protocolo OAuth WRAP de qualquer plataforma que possa fazer um HTTPS FORM POST: .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash e outras plataformas.

A tabela a seguir lista três métodos com suporte para solicitar um token SWT emitido pelo ACS por meio do protocolo OAuth WRAP.

Três métodos para solicitar um token do ACS através do protocolo OAuth WRAP

Ponto de extremidade de emissão de token

Todas as solicitações de token ACS por meio do protocolo OAuth WRAP são direcionadas a um ponto de extremidade emissor de token ACS. O URI desse ponto de extremidade depende do namespace Controle de Acesso. O namespace aparece como um prefixo de nome DNS em um URI de solicitação de token. O restante do nome DNS é fixo, assim como o caminho. Por exemplo, se você quiser solicitar um token do namespace Controle de Acesso chamado "mysnservice", poderá direcionar uma solicitação de token para o seguinte URI: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

Solicitações de token de senha

Com uma solicitação de token de senha, um cliente pode enviar um nome de usuário e uma senha de uma identidade de serviço diretamente para o ACS por meio do protocolo OAuth WRAP para autenticação. Essa é a maneira mais fácil de solicitar um token do ACS usando o protocolo OAuth WRAP. Diferente de estabelecer uma conexão SSL, essa abordagem não requer nenhum recurso de criptografia. Na prática, é semelhante ao modelo de nome de usuário/senha que é predominante em serviços Web REST. Esse tipo de solicitação de token é, na verdade, um formulário de HTTPS POST. Os parâmetros em uma solicitação de token de senha são formulários codificados.

Este é um exemplo de um rastreamento de transmissão de uma solicitação de texto simples para um namespace chamado "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

A tabela a seguir fornece os requisitos de nomes, descrições e valor dos parâmetros exigidos para uma solicitação de token de senha:

Os valores desses parâmetros devem ser codificados em URL antes de enviar a solicitação para o ACS. Seu aplicativo Web ou serviço pode fornecer o valor da wrap_scope para o cliente ou o cliente pode decidir definir o valor do parâmetro wrap_scope para o URI do aplicativo Web ou do destino do recurso de serviço.

As solicitações de token de senha por meio do protocolo OAuth WRAP também podem conter parâmetros adicionais que o ACS pode usar durante o processo de cálculo de declaração de saída. Esses nomes de parâmetros adicionais e os valores devem ter codificação de URL e os valores não devem estar entre aspas.

O método de solicitação de token de senha é bem simples usando .

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

Para obter informações sobre como desempacotar o token de saída do ACS e enviá-lo para o aplicativo Web ou serviço, consulte Desembrulhar e enviar o token para um aplicativo Web ou serviço.

Solicitações de token SWT

Você também pode solicitar um token do ACS por meio do protocolo OAuth WRAP usando um token SWT assinado por uma chave simétrica. Todas as solicitações de token SWT são feitas através de um formulário de HTTPS POST. Os valores dos parâmetros nesse método de solicitação de token têm codificação de formulário.

Este é um exemplo de um rastreamento de transmissão da solicitação de token SWT ao namespace "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

Uma solicitação de token SWT deve ter os seguintes parâmetros e valores:

Conforme mostrado no exemplo a seguir, o código necessário para fazer uma solicitação de token SWT se assemelha o código necessário para fazer uma solicitação de token de senha.

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

Para obter informações sobre como desempacotar a resposta do ACS e enviá-la para seu aplicativo Web ou serviço, consulte Desembrulhamento e envio do token para um aplicativo Web ou serviço.

Criar um token SWT

Um token SWT é um conjunto de pares de chave/valor que são assinados com uma chave do emissor (uma chave simétrica). Um token SWT enviado ao ACS em uma solicitação de token SWT deve conter os parâmetros Issuer e HMACSHA256 , bem como parâmetros adicionais, por exemplo, ExpiresOn, Audience e outras declarações específicas do cliente. A tabela a seguir fornece os nomes e as descrições dos parâmetros de token SWT:

O exemplo de código a seguir mostra como gerar um token de SWT usando . Ele contém um tipo que cria tokens SWT que contêm os parâmetros Emissor e 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;
    }
}

Solicitações de token SAML

O método de solicitação de token SAML destina-se principalmente à integração do AD FS 2.0 e permite que o cliente use uma identidade corporativa (Active Directory) para autenticar com o ACS. Com o método de solicitação de token SAML, você pode enviar um SAML 1.1 assinado ou um token SAML 2.0 emitido pelo AD FS 2.0 (token de entrada) para o ACS por meio do protocolo OAuth WRAP.

O ACS usa regras para calcular as declarações de saída, as agrupa em um token SWT (token de saída), assina e devolve ao cliente através do protocolo OAuth WRAP.

Uma solicitação de token SAML deve ter os seguintes parâmetros e valores:

Este é um exemplo do código necessário para fazer uma solicitação de 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;
 }
}  

Para obter informações sobre como desempacotar a resposta do ACS e enviá-la para seu aplicativo Web ou serviço, consulte Desembrulhamento e envio do token para um aplicativo Web ou serviço.

Declaração de afirmações através do protocolo OAuth WRAP

Para habilitar a compatibilidade com versões anteriores com o comportamento de solicitação de token ACS 1.0, o ACS dá suporte à capacidade de declarar declarações como parte de solicitações de token.

Registre o aplicativo ou serviço de afirmação como um provedor de identidade do ACS.

A maneira recomendada de fazer isso é registrar o aplicativo ou serviço de afirmação como um provedor de identidade do ACS. Em seguida, o aplicativo ou serviço solicita um token do ACS apresentando um token SAML ou SWT que contém as declarações que ele deseja declarar e esse token é assinado usando uma chave do provedor de identidade armazenada no ACS. Por exemplo, você pode enviar uma solicitação de token SAML com declarações declaradas para o ACS por meio do protocolo OAuth WRAP do AD FS 2.0 ou qualquer STS (Serviço de Token de Segurança) personalizado criado usando Windows Identity Foundation (WIF) e registrado no ACS como um provedor de identidade WS-Federation.

Você pode usar o Portal de Gerenciamento do ACS para registrar um provedor de identidade usando metadados WS-Federation ou usar o Serviço de Gerenciamento do ACS para definir individualmente propriedades, endereços e chaves do provedor de identidade. (Por exemplo, consulte Como usar o Serviço de Gerenciamento do ACS para configurar o AD FS 2.0 como um provedor de identidade Enterprise.) Nenhuma identidade de serviço é necessária nesse método de declarar as declarações em uma solicitação de token. Esse método é funcional por meio de todos os protocolos compatíveis com ACS.

Desempacotamento e enviando o token para um aplicativo ou serviço da Web

Se a solicitação de token for autenticada com êxito, o ACS retornará dois parâmetros codificados por formulário: wrap_token e wrap_token_expires_in. Os valores desses parâmetros são o token SWT real que o cliente pode usar para obter acesso ao seu aplicativo ou serviço da Web e a duração aproximada restante desse token (em segundos), respectivamente.

Antes de enviar o token SWT para o aplicativo Web ou serviço, o cliente deve extrai-lo e decodificá-lo da resposta ACS. Se o aplicativo ou serviço da Web exigir que o token seja apresentado em cabeçalho HTTP Authorization, o token deverá ser precedido pelo esquema WRAPv0.9.

O exemplo de código a seguir demonstra como descompactar um token e o formato de cabeçalho 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));

Descrições e códigos de erro do ACS

O ACS retorna erros quando não consegue atender a uma solicitação de token. Para manter o design REST, o erro contém um código de resposta HTTP. Em muitos casos, os erros de ACS também contêm um SubCode e Detail que fornecem contexto sobre o que falhou. O formato de erro é: Error:Code:<httpStatus>:Sub-Code:<code>:D etail:<message>. O Content-Type de um erro sempre é texto/simples.

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>

Para obter mais informações sobre códigos de erro acs, consulte códigos de erro acs.

Ao depurar ou se recuperar de um erro retornado do ACS, geralmente é necessário ler o corpo da resposta. O exemplo de código a seguir mostra como ler a mensagem de erro de um objeto 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
}

Consulte Também

Conceitos

Instruções do ACS