Como: Solicitar um Token da ACS através do Protocolo de WRAP OAuth
Aplica-se A
- Microsoft Azure Ative Directory Controlo de Acesso (também conhecido como serviço de Controlo de Acesso ou ACS)
Descrição Geral
Quando as suas aplicações e serviços web lidam com a autenticação utilizando o ACS, o cliente deve obter um sinal de segurança emitido pela ACS para iniciar sessão na sua aplicação ou serviço. Para obter este token emitido pela ACS (ficha de saída), o cliente deve autenticar diretamente com a ACS ou enviar à ACS um símbolo de segurança emitido pelo seu fornecedor de identidade (ficha de entrada). A ACS valida este token de segurança de entrada, processa as alegações de identidade neste token através do motor de regras ACS, calcula as alegações de identidade de saída e emite um sinal de segurança de saída.
Este tópico descreve os métodos de solicitar um token da ACS através do protocolo OAuth WRAP. Todos os pedidos simbólicos através do protocolo OAuth WRAP são transmitidos através de SSL. A ACS emite sempre um Simple Web Token (SWT) através do protocolo OAuth WRAP, em resposta a um pedido de token corretamente formatado. Todos os pedidos simbólicos através do protocolo OAuth WRAP são enviados para ACS num HTTP POST. Pode solicitar um token ACS através do protocolo OAuth WRAP a partir 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 que se segue enumera três métodos apoiados para solicitar um token SWT emitido pela ACS através do protocolo OAuth WRAP.
Três métodos de pedido de um token da ACS através do protocolo OAuth WRAP
| Método de pedido de token | Description |
|---|---|
Pedidos de token de palavra-passe |
Este método mais simples requer que o cliente envie um nome de utilizador e palavra-passe de uma identidade de serviço diretamente para ACS através do protocolo OAuth WRAP para autenticação. |
Pedidos simbólicos SWT |
Este método requer que o cliente envie um token SWT que pode ser assinado com uma chave simétrica de identidade de serviço ou uma chave simétrica do fornecedor de identidade para ACS através do protocolo OAuth WRAP para a autenticação. |
Pedidos de ficha SAML |
Destinado principalmente à integração 2.0 do Serviço de Federação de Diretórios Ativos (AD FS) 2.0, o método de Marcação de Afirmação de Segurança (SAML) requer que o cliente envie um token SAML assinado para a ACS através do protocolo OAuth WRAP para autenticação. Esta abordagem permite ao cliente utilizar uma identidade empresarial para autenticar com ACS. |
Ponto final de emissão de token
Todos os pedidos de fichas ACS através do protocolo OAuth WRAP são direcionados para um ponto final de emissão de fichas ACS. O URI deste ponto final depende do Controlo de Acesso espaço de nome. O espaço de nome aparece como um prefixo de nome DNS num pedido simbólico URI. O resto do nome DNS é fixo, assim como o caminho. Por exemplo, se quiser solicitar um token do Controlo de Acesso espaço de nome chamado "mysnservice", pode dirigir um pedido simbólico para o seguinte URI: https://mysnservice.accesscontrol.windows.net/WRAPv0.9.
Pedidos de token de palavra-passe
Com um pedido de sinal de palavra-passe, um cliente pode enviar um nome de utilizador e palavra-passe de uma identidade de serviço diretamente para ACS através do protocolo OAuth WRAP para autenticação. Esta é a maneira mais fácil de solicitar um token da ACS usando o protocolo OAuth WRAP. Além de estabelecer uma ligação SSL, esta abordagem não requer capacidade criptográfica. Na prática, é semelhante ao nome de utilizador/palavra-passe modelo que é predominante nos serviços DAE. Este tipo de pedido simbólico é na verdade um POST de formulário HTTPS. Os parâmetros de um pedido de sinal de palavra-passe estão codificados por formulários.
Segue-se um exemplo de um traço de fio de um pedido de texto simples para um espaço de nome 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
O quadro abaixo fornece os nomes, descrições e requisitos de valor dos parâmetros que são obrigados a estar presentes num pedido simbólico de palavra-passe:
| Nome do parâmetro | Descrição | Requisitos de valor |
|---|---|---|
wrap_scope |
Corresponde ao pedido simbólico contra um conjunto de regras. Desajuste o valor deste parâmetro ao valor do reino da aplicação do partido em gestão. Pode obter este valor (no campo Realm ) através do Portal de Gestão ACS, selecionando a aplicação adequada da parte de suporte na página De Candidaturas de Partidos Confiantes . |
|
wrap_name |
Valida a chave do próximo parâmetro. Desapasse o valor deste parâmetro com o nome de uma identidade de serviço dentro do seu Controlo de Acesso espaço de nome. Pode obter este valor (no campo Nome ) através do Portal de Gestão ACS, selecionando a identidade de serviço adequada na página Identidades de Serviço . |
|
wrap_password |
Autentica o pedido de entrada. Desapasse o valor deste parâmetro na palavra-passe de uma identidade de serviço dentro do seu espaço de nome Controlo de Acesso. Pode obter este valor (no campo Palavra-passe na página De Credencial de Edição ), através do Portal de Gestão acs, selecionando primeiro a identidade de serviço adequada na página Identidades de Serviço e, em seguida, selecionando a palavra-passe adequada na tabela Credenciais na página Identidade de Serviço de Edição . |
|
Os valores destes parâmetros devem ser codificados por URL antes de enviar o pedido para ACS. A sua aplicação web ou serviço pode fornecer o valor do wrap_scope ao cliente, ou o cliente pode decidir definir o valor do parâmetro wrap_scope para o URI da aplicação web ou alvo de recursos de serviço.
Os pedidos de token de palavra-passe através do protocolo OAuth WRAP também podem conter parâmetros adicionais que a ACS pode usar durante o processo de cálculo da reclamação de saída. Estes nomes e valores de parâmetros adicionais devem ser codificados por URL e os valores não devem ser citados.
O método de pedido de sinal de palavra-passe é bastante simples de usar .
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 da ACS e enviá-lo para a aplicação ou serviço web, consulte Desembrulhar e enviar o token para uma aplicação ou serviço web.
Pedidos simbólicos SWT
Também pode solicitar um token da ACS através do protocolo OAuth WRAP utilizando um token SWT assinado por uma chave simétrica. Todos os pedidos de ficha sWT são feitos através de um POST de formulário HTTPS. Os valores dos parâmetros neste método de pedido simbólico estão codificados pela forma.
Segue-se um exemplo de um traço de fio de um pedido de ficha SWT para o espaço de nome "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
Um pedido simbólico SWT deve ter os seguintes parâmetros e valores:
| Nome do parâmetro | Descrição | Requisitos de valor |
|---|---|---|
wrap_scope |
Corresponde ao pedido simbólico contra um conjunto de regras. |
|
wrap_assertion |
Este é o sinal de entrada que está a ser enviado para a ACS. |
|
wrap_assertion_format |
Este é o formato do token de entrada que está a ser enviado para a ACS. |
SWT |
Como mostrado no exemplo seguinte, o código que é necessário para fazer um pedido de token SWT assemelha-se ao código que é necessário para fazer um pedido de sinal 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 da ACS e enviá-la para a sua aplicação ou serviço web, consulte Desembrulhar e enviar o token para uma aplicação ou serviço web.
Criação de um símbolo SWT
Um token SWT é um conjunto de pares chave/valor que são assinados com uma chave emitente (uma chave simétrica). Um token SWT enviado à ACS num pedido simbólico da SWT deve conter os parâmetros emitente e HMACSHA256 , bem como parâmetros adicionais, por exemplo, ExpirasOn, Audience, e outras reclamações específicas do cliente. A tabela a seguir fornece os nomes e descrições dos parâmetros simbólicos SWT:
| Nome do parâmetro | Descrição |
|---|---|
Emissor |
Em ACS, procura a chave que foi usada para assinar o símbolo. Se a assinatura for válida, este valor é utilizado para realizar o cálculo da reclamação de saída. Pode definir este parâmetro para o valor do reino de um fornecedor de identidade dentro do seu Controlo de Acesso espaço de nome ou o nome de uma identidade de serviço dentro do seu Controlo de Acesso espaço de nome. Pode obter este valor (no campo Realm na página Fornecedor de Identidade de Edição ) através do Portal de Gestão de ACS, selecionando o fornecedor de identidade adequado na página Fornecedores de Identidade. Ou pode obter este valor através do Serviço de Gestão ACS – esta é a propriedade do nome do registo "Emitente" que é criado para cada fornecedor de identidade. |
HMACSHA256 |
No ACS, valida a assinatura SWT e procura a chave emitente nomeada no parâmetro emitente . A assinatura SWT é criada utilizando a chave de assinatura simétrica anexada a uma identidade de serviço ou a um fornecedor de identidade dentro do seu Controlo de Acesso espaço de nome. |
Audiência |
Se estiver presente, a ACS utiliza este valor para se certificar de que o ACS é o alvo pretendido do token SWT. Este é o URL do seu Controlo de Acesso espaço de nome, por exemplo,https://contoso.accesscontrol.windows.net/ |
Expiraon |
Se presente (no tempo de época), indica se o token está expirado. Por exemplo, o valor deste parâmetro pode ser |
Reclamações adicionais |
Se estiver presente, o ACS utiliza estes parâmetros para realizar o cálculo da reclamação de saída. Cada tipo de reclamação deve aparecer apenas uma vez. Os valores de reivindicação múltiplos do mesmo tipo de reclamação devem ser concatenados juntamente com um carácter "" (vírgula). Para obter mais informações sobre a afirmação de sinistros em ACS, consulte a afirmação de Claims através do protocolo OAuth WRAP. |
A seguinte amostra de código mostra como gerar um token SWT utilizando . Contém um tipo que constrói fichas SWT que contêm os parâmetros Emitente 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;
}
}
Pedidos de ficha SAML
O método de pedido de token SAML destina-se principalmente à integração AD FS 2.0 e permite ao cliente utilizar uma identidade empresarial (Ative Directory) para autenticar com ACS. Com o método de pedido de ficha SAML, pode enviar um saml 1.1 assinado ou um token SAML 2.0 emitido pela AD FS 2.0 (ficha de entrada) para ACS através do protocolo OAuth WRAP.
A ACS utiliza as suas regras para calcular as reclamações de saída, agrupá-las num token SWT (token de saída), assina-as e devolve-as ao cliente através do protocolo OAuth WRAP.
Um pedido de ficha SAML deve ter os seguintes parâmetros e valores:
| Nome do parâmetro | Descrição | Requisitos de valor |
|---|---|---|
wrap_scope |
Corresponde ao pedido simbólico contra um conjunto de regras. |
|
wrap_assertion |
Este é o sinal de entrada que está a ser enviado para a ACS. |
|
wrap_assertion_format |
Este é o formato do token de entrada que está a ser enviado para a ACS. |
SAML |
Segue-se um exemplo do código que é necessário para fazer um pedido 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 da ACS e enviá-la para a sua aplicação ou serviço web, consulte Desembrulhar e enviar o token para uma aplicação ou serviço web.
Afirmação de reclamações através do protocolo OAuth WRAP
Para permitir a retrocompatibilidade com o comportamento de pedido de ficha de ACS 1.0, a ACS apoia a capacidade de afirmar reclamações como parte de pedidos simbólicos.
Registe o pedido ou serviço de afirmação como fornecedor de identidade ACS.
A forma recomendada de o fazer é registar o pedido ou serviço de afirmação como prestador de identidade ACS. Em seguida, a aplicação ou serviço solicita um token da ACS apresentando um token SAML ou SWT que contém as alegações que quer afirmar, e este token é assinado usando uma Chave de Fornecedor de Identidade armazenada em ACS. Por exemplo, pode enviar um pedido de ficha SAML com reivindicações afirmadas à ACS através do protocolo OAuth WRAP a partir de AD FS 2.0 ou qualquer serviço de token de segurança personalizado (STS) que é construído usando Windows Identity Foundation (WIF) e registado em ACS como um fornecedor de identidade WS-Federation.
Pode utilizar o Portal de Gestão ACS para registar um fornecedor de identidade utilizando metadados WS-Federation, ou pode utilizar o Serviço de Gestão ACS para definir individualmente propriedades, endereços e chaves do fornecedor de identidade. (Por exemplo, ver Como: Utilizar o Serviço de Gestão ACS para configurar a AD FS 2.0 como Fornecedor de Identidade Empresarial.) Não são necessárias identidades de serviço neste método de afirmação de sinistros num pedido simbólico. Este método é funcional através de todos os protocolos suportados pelo ACS.
Desembrulhar e enviar o token para uma aplicação ou serviço web
Se o pedido de token for autenticado com sucesso, a ACS devolve dois parâmetros codificados por formulários: wrap_token e wrap_token_expires_in. Os valores destes parâmetros são o token SWT real que o cliente pode usar para ter acesso à sua aplicação ou serviço web e ao tempo de vida remanescente aproximado deste token (em segundos), respectivamente.
Antes de enviar o token SWT para a aplicação ou serviço web, o cliente deve extraí-lo e descodificá-lo da resposta ACS. Se a aplicação web ou o serviço exigirem que o token seja apresentado no cabeçalho HTTP Authorization , o símbolo deve ser precedido pelo esquema WRAPv0.9.
O seguinte exemplo de código demonstra como desempacotar um token e formatar o Authorization cabeçalho.
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));
Códigos e descrições de erros ACS
ACS retorna erros quando não consegue satisfazer um pedido simbólico. De acordo com o design REST, o erro contém um código de resposta HTTP. Em muitos casos, os erros da ACS também contêm um SubCode e Detail que fornecem contexto sobre o que falhou. O formato de erro é: Error:Code:<httpStatus>:Sub-Código:<código>:D etail:<message>. O Content-Type 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 recuperar de um erro devolvido da ACS, é frequentemente necessário ler o corpo de resposta. O exemplo de código que se segue mostra como ler a mensagem de erro a partir 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
}