Cette page vous a-t-elle été utile ?
Votre avis sur ce contenu est important. N'hésitez pas à nous faire part de vos commentaires.
Vous avez d'autres commentaires ?
1500 caractères restants
Exporter (0) Imprimer
Développer tout

Demande de jeton à ACS via le protocole OAuth WRAP

Mis à jour: mars 2015

  • Microsoft Azure Active Directory Access Control (également appelé Access Control Service ou ACS)

Lorsque vos applications et services web gèrent l'authentification avec ACS, le client doit obtenir un jeton de sécurité émis par ACS pour se connecter à vos applications ou services. Pour obtenir ce jeton émis par ACS (jeton de sortie), le client doit s'authentifier directement auprès d'ACS ou envoyer un jeton de sécurité ACS émis par son fournisseur d'identité (jeton d'entrée). ACS valide ce jeton de sécurité d'entrée, traite les revendications d'identité qu'il contient via le moteur de règles ACS, calcule les revendications d'identité de sortie, puis émet un jeton de sécurité de sortie.

Cette rubrique décrit les méthodes de demande de jeton à ACS via le protocole OAuth WRAP. Toutes les demandes de jeton via le protocole OAuth WRAP sont transmises à l'aide du protocole SSL. ACS émet toujours un jeton web simple (SWT, Simple Web Token) via le protocole OAuth WRAP, en réponse à une demande de jeton correctement mise en forme. Toutes les demandes de jeton via le protocole OAuth WRAP sont envoyées à ACS dans une requête HTTP POST. Vous pouvez demander un jeton ACS via le protocole OAuth WRAP à toute plateforme capable d'établir une requête HTTPS FORM POST : .NET Framework, Windows Communication Foundation (WCF), Silverlight, ASP.NET, Java, Python, Ruby, PHP, Flash, entre autres.

Le tableau suivant répertorie trois méthodes prises en charge de demande de jeton SWT émis par ACS via le protocole OAuth WRAP.

Trois méthodes de demande de jeton à ACS via le protocole OAuth WRAP

Méthode de demande de jeton Description

Demandes de jeton de mot de passe

Cette méthode, la plus simple, requiert que le client envoie un nom d'utilisateur et un mot de passe directement d'une identité de service à ACS via le protocole OAuth WRAP à des fins d'authentification.

Demandes de jeton SWT

Cette méthode requiert que le client envoie un jeton SWT, pouvant être signé avec une clé symétrique d'identité de service ou de fournisseur d'identité, à ACS via le protocole OAuth WRAP à des fins d'authentification.

Demandes de jeton SAML

Initialement destinée à l'intégration des services ADFS (Active Directory Federation Services), la méthode SAML (Security Assertion Markup Language) nécessite que le client envoie un jeton SAML signé à ACS via le protocole OAuth WRAP à des fins d'authentification. Cette approche permet au client d'utiliser un identifiant d'entreprise pour s'authentifier auprès d'ACS.

Tous les demandes de jeton ACS via le protocole OAuth WRAP sont dirigées vers un point de terminaison émetteur de jeton ACS. L'URI de ce point de terminaison dépend de l'espace de noms Access Control. L'espace de noms se présente sous la forme d'un préfixe de nom DNS dans un URI de demande de jeton. Le reste du nom DNS est fixe, tout comme le chemin d'accès. Par exemple, si vous voulez demander un jeton à l'espace de noms Access Control « mysnservice », vous pouvez diriger une demande de jeton vers l'URI suivant : https://mysnservice.accesscontrol.windows.net/WRAPv0.9.

Une demande de jeton de mot de passe permet à un client d'envoyer un nom d'utilisateur et un mot de passe directement d'une identité de service à ACS via le protocole OAuth WRAP à des fins d'authentification. C'est la façon la plus simple de demander un jeton à ACS en utilisant le protocole OAuth WRAP. Cette approche ne nécessite aucune capacité de chiffrement autre que l'établissement d'une connexion SSL. Dans la pratique, elle est similaire au modèle de nom d'utilisateur/mot de passe qui prévaut dans les services web REST. Ce type de demande de jeton est en fait une requête HTTPS FORM POST. Les paramètres d'une demande de jeton de mot de passe sont en format codé.

Voici un exemple de transmission d'une demande en texte clair à un espace de noms nommé « 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

Le tableau ci-dessous fournit les noms, descriptions et exigences de valeur des paramètres qui doivent être présents dans une demande de jeton de mot de passe :

 

Nom du paramètre Description Exigences de valeur

wrap_scope

Compare la demande de jeton à un ensemble de règles. Définissez la valeur de ce paramètre sur la valeur du domaine d'application par partie de confiance. Vous pouvez obtenir cette valeur (dans le champ Domaine) via le portail de gestion ACS en sélectionnant l'application par partie de confiance appropriée dans la page Applications par partie de confiance.

  • URI HTTP ou HTTP(s)

  • Aucun paramètre de requête ou ancre.

  • Segments de chemin d'accès <= 32.

  • Longueur maximale : 256 caractères.

  • Doit être codé URL.

wrap_name

Valide la clé du paramètre suivant. Définissez la valeur de ce paramètre sur le nom d'une identité de service dans votre espace de noms Access Control. Vous pouvez obtenir cette valeur (dans le champ Nom) via le portail de gestion ACS en sélectionnant l'identité de service appropriée dans la page Identités de service.

  • Longueur minimale : 1 caractère.

  • Longueur maximale : 128 caractères.

  • Doit être codé URL.

wrap_password

Authentifie la demande entrante. Définissez la valeur de ce paramètre sur le mot de passe d'une identité de service dans votre espace de noms Access Control. Vous pouvez obtenir cette valeur (dans le champ Mot de passe de la page Modifier les informations d'identification) via le portail de gestion ACS, en sélectionnant l'identité de service appropriée dans la page Identités de service, puis en sélectionnant le mot de passe approprié dans le tableau Informations d'identification dans la page Modifier l'identité de service.

  • Chaîne d'une longueur de 1 à 64 caractères.

  • Doit être codé URL.

Avant d'envoyer la demande à ACS, les valeurs de ces paramètres doivent être codés URL. Votre application ou service web peut fournir la valeur du paramètre wrap_scope au client, ou celui-ci peut la définir sur l'URI de la ressource d'application ou de service web cible.

Les demandes de jetons de mot de passe via le protocole OAuth WRAP peuvent également contenir des paramètres supplémentaires qu'ACS peut utiliser durant le processus de calcul de revendication de sortie. Ces noms et valeurs de paramètres supplémentaires doivent être codés URL, et les valeurs ne doivent pas être mises entre guillemets.

La méthode de demande de jeton de mot de passe est assez simple.

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

Pour plus d'informations sur la décompression du jeton de sortie à partir d'ACS et son envoi à l'application ou au service web, consultez Unwrapping and sending the token to a web application or service.

Vous pouvez également demander un jeton à ACS via le protocole OAuth WRAP à l'aide d'un jeton SWT signé par une clé symétrique. Toutes les demandes de jeton SWT sont effectuées via une requête HTTPS FORM POST. Les valeurs de paramètre de cette méthode de demande de jeton sont en format codé.

Voici un exemple de transmission d'une demande de jeton SWT adressée à l'espace de noms « 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

Une demande de jeton SWT doit présenter les paramètres et valeurs suivants :

 

Nom du paramètre Description Exigences de valeur

wrap_scope

Compare la demande de jeton à un ensemble de règles.

  • Définissez la valeur de ce paramètre sur la valeur du domaine d'application par partie de confiance. Vous pouvez obtenir cette valeur (dans le champ Domaine) via le portail de gestion ACS en sélectionnant l'application par partie de confiance appropriée dans la page Applications par partie de confiance.

  • URI HTTP ou HTTP(s).

  • Aucun paramètre de requête ou ancre.

  • Segments de chemin d'accès <= 32.

  • Longueur maximale : 256 caractères.

  • Doit être codé URL.

wrap_assertion

Ceci est le jeton d'entrée envoyé à ACS.

  • Jeton SWT signé avec des revendications d'entrée qui incluent l'émetteur et des paramètres HMACSHA256.

  • Longueur maximale : 2 048 caractères.

  • Doit être codé URL.

wrap_assertion_format

Ceci est le format du jeton d'entrée envoyé à ACS.

SWT

Comme indiqué dans l'exemple suivant, le code requis pour effectuer une demande de jeton SWT ressemble au code requis pour effectuer une demande de jeton de mot de passe.

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

Pour plus d'informations sur la décompression de la réponse d'ACS et son envoi à l'application ou au service web, consultez Unwrapping and sending the token to a web application or service.

Un jeton SWT est un ensemble de paires clé-valeur signées avec une clé de l'émetteur (clé symétrique). Un jeton SWT envoyé à ACS dans une demande de jeton SWT doit contenir l'émetteur et les paramètres HMACSHA256, ainsi que des paramètres supplémentaires, par exemple, ExpiresOn, Audience et d'autres revendications spécifiques du client. Le tableau suivant répertorie les noms et les descriptions des paramètres de jeton SWT :

 

Nom du paramètre Description

Émetteur

Dans ACS, recherche la clé qui utilisée pour signer le jeton. Si la signature est valide, cette valeur est utilisée pour effectuer le calcul de revendication de sortie.

Vous pouvez définir ce paramètre sur la valeur du domaine d'un fournisseur d'identité au sein de votre espace de noms Access Control, ou sur le nom d'une identité de service au sein de votre espace de noms Access Control. Vous pouvez obtenir cette valeur (dans le champ Domaine de la page Modifier le fournisseur d'identité) via le portail de gestion ACS, en sélectionnant le fournisseur d'identité approprié dans la page Fournisseurs d'identité. Vous pouvez également obtenir cette valeur via le service de gestion ACS. Il s'agit de la propriété name de l'enregistrement « Issuer » créé pour chaque fournisseur d'identité.

HMACSHA256

Dans ACS, valide la signature SWT et recherche la clé de l'émetteur nommée dans le Issuer.

La signature SWT est créée à l'aide de la clé de signature symétrique attachée à une identité de service ou à un fournisseur d'identité au sein de votre espace de noms Access Control.

Audience

Le cas échéant, ACS utilise cette valeur pour s'assurer qu'ACS est la cible visée du jeton SWT. Il s'agit de l'URL de votre espace de noms Access Control, par exemple, https://contoso.accesscontrol.windows.net/

ExpiresOn

Le cas échéant (dans le temps Epoch), indique si le jeton a expiré. Par exemple, la valeur de ce paramètre peut être 1324300962.

Revendications supplémentaires

Le cas échéant, ACS utilise ces paramètres pour effectuer un calcul de revendication de sortie. Chaque type de revendication ne peut apparaître qu'une seule fois. Plusieurs valeurs de revendication du même type doivent être concaténées à l'aide d'une virgule (« , »). Pour plus d'informations sur l'assertion de revendications dans ACS, consultez Assertion de revendications via le protocole OAuth WRAP.

L'exemple de code suivant montre comment générer un jeton SWT à l'aide de . Il contient un type qui crée des jetons SWT comprenant les paramètres Issuer et 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;
    }
}

La méthode de demande de jeton SAML est principalement destinée à l'intégration AD FS 2.0. Elle permet au client d'utiliser une identité d'entreprise (Active Directory) pour s'authentifier auprès d'ACS. Avec la méthode de demande de jeton SAML, vous pouvez envoyer un jeton signé SAML 1.1 ou SAML 2.0 émis par AD FS 2.0 (jeton d'entrée) à ACS via le protocole OAuth WRAP.

ACS utilise des règles pour calculer les revendications de sortie, les regrouper dans un jeton SWT (jeton de sortie), signer celui-ci et le renvoyer au client via le protocole OAuth WRAP.

Une demande de jeton SAML doit présenter les paramètres et valeurs suivants :

 

Nom du paramètre Description Exigences de valeur

wrap_scope

Compare la demande de jeton à un ensemble de règles.

  • Définissez la valeur de ce paramètre sur la valeur du domaine d'application par partie de confiance. Vous pouvez obtenir cette valeur (dans le champ Domaine) via le portail de gestion ACS en sélectionnant l'application par partie de confiance appropriée dans la page Applications par partie de confiance.

  • URI HTTP ou HTTP(s).

  • Aucun paramètre de requête ou ancre.

  • Segments de chemin d'accès <= 32.

  • Longueur maximale : 256 caractères.

  • Doit être codé URL.

wrap_assertion

Ceci est le jeton d'entrée envoyé à ACS.

  • Jeton signé SAML 1.1 ou 2.0 avec des revendications d'entrée. Les jetons SAML 1.1 font l'objet d'une restriction. Ils nécessitent au moins une revendication d'entrée. Cela signifie qu'un fournisseur d'identité ou une identité de service prenant en charge les revendications doivent être utilisés pour l'authentification de jeton SAML 1.1. Les jetons SAML 2.0 ne nécessitent pas de revendication d'entrée pour l'authentification par rapport à une identité de service, à part la revendication NameIdentifier implicite. Par conséquent, des jetons SAML 2.0 peuvent être utilisés pour authentifier par rapport à une identité de service normale ne prenant pas en charge les revendications.

  • Doit être codé URL.

wrap_assertion_format

Ceci est le format du jeton d'entrée envoyé à ACS.

SAML

Voici un exemple de code requis pour effectuer une demande de jeton 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;
 }
}  

Pour plus d'informations sur la décompression de la réponse d'ACS et son envoi à l'application ou au service web, consultez Désencapsulage et envoi du jeton à un service ou à une application web.

Pour activer la compatibilité descendante avec le comportement de demande de jeton ACS 1.0, ACS prend en charge la possibilité d'assertion de revendications dans le cadre de demandes de jeton.

La méthode recommandée pour ce faire consiste à enregistrer l'application ou le service effectuant l'assertion comme un fournisseur d'identité ACS. Ensuite, l'application ou le service demande un jeton à ACS, en présentant un jeton SAML ou SWT contenant les revendications faisant l'objet de l'assertion. Ce jeton est signé à l'aide d'une clé de fournisseur d'identité stockée dans ACS. Par exemple, vous pouvez envoyer une demande de jeton SAML avec des revendications à ACS via le protocole OAuth WRAP à partir d'AD FS 2.0 ou de tout service de jeton de sécurité (STS) créé à l'aide de Windows Identity Foundation (WIF), et enregistré dans ACS comme un fournisseur d'identité WS-Federation.

Vous pouvez utiliser le portail de gestion ACS pour enregistrer un fournisseur d'identité à l'aide de métadonnées WS-Federation, ou utiliser le service de gestion ACS pour définir individuellement des propriétés, adresses et clés de fournisseur d'identité. (Pour un exemple, consultez Procédure : Utiliser le service de gestion ACS pour configurer AD FS 2.0 en tant que fournisseur d'identité d'entreprise.) Aucune identité de service n'est requise dans cette méthode d'assertion de revendications dans une demande de jeton. Cette méthode fonctionne via tous les protocoles pris en charge par ACS.

Si la demande de jeton est correctement authentifiée, ACS renvoie deux paramètres en format codé : wrap_token et wrap_token_expires_in. Les valeurs de ces paramètres sont respectivement le jeton SWT que le client peut utiliser pour accéder à votre application ou service web, et la durée restante approximative de ce jeton (en secondes).

Avant d'envoyer le jeton SWT à l'application ou au service web, le client doit l'extraire et décoder son URL à partir de la réponse ACS. Si l'application ou le service web requièrent que le jeton soit présenté dans l'en-tête HTTP Authorization, le jeton doit être précédé par le schéma WRAPv0.9.

L'exemple de code suivant montre comment décompresser un jeton et mettre en forme l'en-tête 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 renvoie des erreurs lorsqu'il ne peut pas satisfaire une demande de jeton. Conformément à la conception REST, l'erreur contient un code de réponse HTTP. Souvent, les erreurs ACS contiennent des éléments de SubCode et de Detail qui fournissent un contexte sur l'échec. Le format d'erreur est le suivant : Error:Code:<httpStatus>:Sub-Code:<code>:Detail:<message>. Le Content-Type d'une erreur est toujours texte/brut.

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>

Pour plus d'informations sur les codes d'erreur ACS, consultez Codes d'erreur ACS.

En cas de débogage ou de récupération suite à une erreur renvoyée par ACS, il est souvent nécessaire pour lire le corps de la réponse. L'exemple de code suivant montre comment lire le message d'erreur d'un objet 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
}

Voir aussi

Ajouts de la communauté

Afficher:
© 2015 Microsoft