Esta documentação foi arquivada e não está sendo atualizada.

Como: Solicitar um token do ACS através do protocolo OAuth WRAP

Atualizado: junho de 2015

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

Quando seus aplicativos e serviços da Web lidam com a autenticação usando ACS, o cliente deve obter um token de segurança emitido pelo ACS para fazer logon no seu aplicativo ou serviço. Para obter esse ACS- token emitido (token de saída), o cliente deve autenticar diretamente com ACS ou enviar ACS um token de segurança emitido pelo 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 solicitar um token do ACS através do protocolo OAuth WRAP. Todas as solicitações de tokens feitas através do protocolo OAuth WRAP são transmitidas pelo SSL. O ACS sempre emite um Simple Web Token (SWT) através do protocolo OAuth WRAP, em resposta a uma solicitação de token formatada corretamente. Todas as solicitações de tokens feitas através do protocolo OAuth WRAP são enviadas ao ACS em um HTTP POST. Você pode solicitar um token ACS através 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 ACS token SWT emitido através do protocolo OAuth WRAP.

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

Método de solicitação de token Descrição

Solicitações de token de senha

Esse método mais simples exige que o cliente envie um nome de usuário e senha de uma identidade de serviço diretamente para ACS através do protocolo OAuth WRAP para autenticação.

Solicitações de token SWT

Este método requer que o cliente envie um token SWT que possa ser assinado com uma chave simétrica de identidade de serviço ou uma chave simétrica do provedor de identidade para ACS através do protocolo OAuth WRAP para autenticação.

Solicitações de token SAML

Destina-se principalmente para integração do Serviço de Federação do Active Directory (AD FS) 2.0, o método SAML (Security Assertion Markup Language) requer que o cliente envie um token SAML assinado para ACS através do protocolo OAuth WRAP para autenticação. Essa abordagem permite que o cliente use uma identidade de empresa para autenticar com ACS.

Todas as solicitações de token ACS feitas através do protocolo OAuth WRAP são direcionadas a um ponto de extremidade de emissão de token ACS. O URI do ponto de extremidade depende do Namespace do Access Control. 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ê deseja solicitar um token do Namespace do Access Control chamado "mysnservice", é possível direcionar uma solicitação de token para o seguinte URI: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

Com uma solicitação de token de senha, um cliente pode enviar um nome de usuário e senha de uma identidade de serviço diretamente para ACS através 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:

 

Nome do parâmetro Descrição Requisitos de valor

wrap_scope

Corresponde à solicitação de token com um conjunto de regras. Defina o valor desse parâmetro como o valor do realm de aplicativo de terceira parte confiável. Você pode obter esse valor (no campo Realm) através do Portal de Gerenciamento do ACS selecionando o aplicativo de terceira parte confiável adequado a partir da página Aplicativos de terceira parte confiáveis .

  • URI HTTP ou HTTP(s)

  • Não há parâmetros de consulta ou âncoras.

  • Segmentos de caminho <= 32.

  • Comprimento máximo: 256 caracteres.

  • Deve ter codificação de URL.

wrap_name

Valida a chave do próximo parâmetro. Defina o valor desse parâmetro como o nome de uma identidade de serviço dentro do seu Namespace do Access Control. Você pode obter esse valor (no campo Nome) através do Portal de Gerenciamento do ACS selecionando a identidade de serviço adequado na página Identidades de Serviço.

  • Comprimento mínimo: um caractere.

  • Comprimento máximo: 128 caracteres.

  • Deve ter codificação de URL.

wrap_password

Autentica a solicitação de entrada. Defina o valor desse parâmetro como a senha de uma identidade de serviço dentro do seu Namespace do Access Control. Você pode obter esse valor (no campo Senha na página Editar credencial) através do Portal de Gerenciamento do ACS, selecionando primeiro a identidade de serviço adequada na página Identidades de serviço e, em seguida, selecionando a senha adequada na tabela Credenciais na página Editar identidade de serviço.

  • Cadeia de caracteres, mínimo de 1 e máximo de 64 caracteres de comprimento.

  • Deve ter codificação de URL.

Os valores desses parâmetros devem ser URL codificadas antes de enviar a solicitação para ACS. O aplicativo ou serviço da Web pode fornecer o valor do wrap_scope para o cliente ou o cliente pode optar por definir o valor do parâmetro wrap_scope para o URI do alvo de recurso de serviço ou aplicativo da Web.

As solicitações de token de senha feitas através do protocolo OAuth WRAP também podem conter parâmetros adicionais que o ACS pode usar durante 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 descompactar o token de saída do ACS e enviá-lo para o aplicativo ou serviço da Web, consulte Unwrapping and sending the token to a web application or service.

Você também pode solicitar um token do ACS através 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:

 

Nome do parâmetro Descrição Requisitos de valor

wrap_scope

Corresponde à solicitação de token com um conjunto de regras.

  • Defina o valor desse parâmetro como o valor do realm de aplicativo de terceira parte confiável. Você pode obter esse valor (no campo Realm) através do Portal de Gerenciamento do ACS selecionando o aplicativo de terceira parte confiável adequado a partir da página Aplicativos de terceira parte confiáveis .

  • URI HTTP ou HTTP(s).

  • Não há parâmetros de consulta ou âncoras.

  • Segmentos de caminho <= 32.

  • Comprimento máximo: 256 caracteres.

  • Deve ter codificação de URL.

wrap_assertion

Esse é o token de entrada que está sendo enviado para ACS.

  • Um token SWT assinado com declarações de entrada que incluem parâmetros HMACSHA256 e emissor.

  • Comprimento máximo: 2048 caracteres.

  • Deve ter codificação de URL.

wrap_assertion_format

Este é o formato do token de entrada que está sendo enviado para ACS.

SWT

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 descompactar a resposta do ACS e enviá-la para seu aplicativo ou serviço da Web, consulte Unwrapping and sending the token to a web application or service.

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 Emissor e HMACSHA256, bem como parâmetros adicionais, por exemplo, ExpiresOn, Público 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:

 

Nome do parâmetro Descrição

Emissor

Em ACS, procura a chave usada para assinar o token. Se a assinatura for válida, esse valor será usado para executar o cálculo de declaração de saída.

Você pode definir esse parâmetro para o valor do realm de um provedor de identidade dentro de seu Namespace do Access Control ou o nome de uma identidade de serviço dentro de seu Namespace do Access Control. Você pode obter esse valor (no campo Realm na página Editar provedor de identidade) através do Portal de Gerenciamento do ACS, selecionando o provedor de identidade adequado na página Provedores de identidade. Ou você pode obter esse valor através do Serviço de Gerenciamento ACS – essa é a propriedade de nome do registro "Emissor" que é criada para cada provedor de identidade.

HMACSHA256

Em ACS, valida a assinatura SWT e procura a chave do emissor nomeada no parâmetro Emissor.

A assinatura SWT é criada usando a chave simétrica de assinatura anexada a uma identidade de serviço ou um provedor de identidade dentro de seu Namespace do Access Control.

Público

Se presente, o ACS usará esse valor para certificar-se de que ACS é o destino pretendido do token SWT. Esta é a URL de seu Namespace do Access Control, por exemplo, https://contoso.accesscontrol.windows.net/

ExpiresOn

Se estiver presente (em vez de Época), indica se o token tiver expirado. Por exemplo, o valor desse parâmetro pode ser 1324300962.

Declarações adicionais

Se estiver presente, ACS usará esses parâmetros para executar o cálculo de declaração de saída. Cada tipo de declaração deve aparecer apenas uma vez. Vários valores de declaração do mesmo tipo de declaração devem ser concatenados com uma "," (vírgula). Para obter mais informações sobre as afirmações de declarações no ACS, consulte Declaração de afirmações através do protocolo OAuth WRAP.

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

O método de solicitação de token SAML é destinado principalmente para a integração AD FS 2.0 e permite que o cliente use uma identidade de empresa (Active Directory) para autenticar com ACS. Com o método de solicitação de token SAML, é possível enviar um sinal SAML 1.1 ou um token SAML 2.0 emitido pelo AD FS 2.0 (token de entrada) para ACS através 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:

 

Nome do parâmetro Descrição Requisitos de valor

wrap_scope

Corresponde à solicitação de token com um conjunto de regras.

  • Defina o valor desse parâmetro como o valor do realm de aplicativo de terceira parte confiável. Você pode obter esse valor (no campo Realm) através do Portal de Gerenciamento do ACS selecionando o aplicativo de terceira parte confiável adequado a partir da página Aplicativos de terceira parte confiáveis .

  • URI HTTP ou HTTP(s).

  • Não há parâmetros de consulta ou âncoras.

  • Segmentos de caminho <= 32.

  • Comprimento máximo: 256 caracteres.

  • Deve ter codificação de URL.

wrap_assertion

Esse é o token de entrada que está sendo enviado para ACS.

  • Um token SAML 1.1 ou 2.0 assinado com declarações de entrada. Os tokens SAML 1.1, como uma limitação de token, requerem pelo menos uma declaração de entrada. Isso significa que um provedor de identidade ou uma identidade de serviço habilitado para declarações deve ser usado para autenticação de token SAML 1.1. Os tokens SAML 2.0 não requerem nenhuma declaração de entrada para autenticação em relação a uma identidade de serviço, além de declaração do NameIdentifier implícita, portanto os tokens SAML 2.0 podem ser usados para autenticar uma identidade de serviço normal que não está habilitado para declarações.

  • Deve ter codificação de URL.

wrap_assertion_format

Este é o formato do token de entrada que está sendo enviado para ACS.

SAML

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 descompactar a resposta do ACS e enviá-la ao seu aplicativo ou serviço da Web, consulte Desempacotamento e enviando o token para um aplicativo ou serviço da Web.

Para ativar a compatibilidade com versões anteriores com o comportamento de solicitação de token do ACS 1.0, o ACS suporta a capacidade de declarar declarações como parte das solicitações de token.

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 de ACS apresentando um token SAML ou SWT que contém as declarações que deseja declarar e esse token é assinado usando uma Chave do provedor de identidade armazenada em ACS. Por exemplo, você pode enviar uma solicitação de token SAML com declarações declaradas para ACS através do protocolo OAuth WRAP do AD FS 2.0 ou qualquer Serviço de Token de Segurança (STS) personalizado que é criado usando o Windows Identity Foundation (WIF) e registrado no ACS como um provedor de identidade do WS-Federation.

Você pode usar o Portal de Gerenciamento do ACS para registrar um provedor de identidade usando metadados de WS-Federation, ou pode usar o Serviço de Gerenciamento do ACS para definir individualmente propriedades de provedor de identidade, endereços e chaves. (Para obter um exemplo, consulte Como: Usar o Serviço de Gerenciamento do ACS para configurar o AD FS 2.0 como um provedor de identidade corporativo.) 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 através de todos os protocolos suportados pelo ACS.

Se a solicitação de token for autenticada com êxito, o ACS retorna dois parâmetros codificados de 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 ou serviço da Web, o cliente deve extrair e decodificar a URL da resposta do 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));

O ACS retornará erros quando ele não puder atender 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 do ACS também contêm um SubCode e Detail que fornecem contexto sobre a falha. O formato do erro é: Error:Code:<httpStatus>:Sub-Code:<code>:Detail:<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 informações sobre códigos de erro do ACS, consulte Códigos de erro do ACS.

Ao depurar ou recuperar de um erro retornado de ACS, muitas vezes é 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

Manuais do ACS

Mostrar: