Cette documentation est archivée et n’est pas conservée.

SWT (Simple Web Token)

Mis à jour: juin 2015

Ce document de 2009 a été conçu comme une norme proposée relative au jeton web simple (SWT, Simple Web Token) pour le groupe de travail IETF (Internet Engineering Task Force). Bien qu'il soit incomplet et qu'il ne s'agisse pas d'une rubrique d'aide, il fournit des informations intéressantes sur le format et l'utilisation des jetons SWT.

Version 0.9.5.1, 4 novembre 2009

Un jeton SWT fournit un format pour la transmission d'une assertion entre deux parties. L'assertion est un ensemble de paires nom-valeur encodées dans formulaire HTML. La chaîne ainsi obtenue est insérée dans une assertion par un code SHA 256 HMAC utilisant une clé partagée entre les parties.

  • Dick Hardt (dick.hardt@microsoft.com), rédacteur

  • Yaron Goland (yarong@microsoft.com)

Cette spécification est disponible en vertu de l'accord Open Web Foundation version 0.9, accessible à l'adresse [http://groups.google.com/group/open-web-board/web/owf-agreement-for-final-specs---pt-9-draft][Note: URL à jour en attente.]Vous pouvez consulter les copies signées de l'accord Open Web Foundation version 0.9 relatif à cette spécification à l'adresse [Insérer l'URI de la banque de contrats du groupe], qui peuvent également inclure des parties en plus de celles mentionnées plus haut. L'utilisation de cette spécification peut être sujette à d'autres droits de tiers. CETTE SPÉCIFICATION EST FOURNIE « TELLE QUELLE ». Les collaborateurs excluent expressément toute garantie (expresse, implicite ou autre), notamment en matière de qualité marchande, d'absence de contrefaçon, d'adéquation à un usage particulier ou de titre, liée à la spécification. Le responsable de l'implémentation et l'utilisateur assument seuls la totalité des risques liés à l'implémentation ou à utilisation de la spécification. AUCUNE PARTIE NE POURRA EN AUCUN CAS ÊTRE TENUE POUR RESPONSABLE ENVERS UNE AUTRE PARTIE D'UNE PERTE DE BÉNÉFICES OU DE TOUTE FORME DE PRÉJUDICE INDIRECT, PARTICULIER, ACCESSOIRE OU CONSÉCUTIF, DE QUELQUE CARACTÈRE OU CAUSE D'ACTION QUE CE SOIT, CONCERNANT CETTE SPÉCIFICATION OU LE CONTRAT QUI LA RÉGIT, RÉSULTANT OU NON D'UNE RUPTURE OU VIOLATION DE CONTRAT, OU D'UNE FAUTE (Y COMPRIS UNE NÉGLIGENCE), QUAND BIEN MÊME L'AUTRE PARTIE N'AURAIT-ELLE PAS ÉTÉ AVERTIE DE LA POSSIBILITÉ D'UN TEL PRÉJUDICE.

Un jeton définit un format pour la transmission d'une assertion simple, compacte, et dont la mise en forme permet de l'inclure facilement dans un en-tête pour des protocoles tels que HTTP. Une assertion simple peut être représentée comme un ensemble de paires nom-valeur. Les valeurs encodées de formulaire HTML répondent aux objectifs souhaités d'être bien comprises et de présenter un format sûr pour les en-têtes HTTP.

Étant donné que le jetons SWT doivent communiquer des informations importantes sur l'identité et l'accès, il convient d'éviter toute falsification. C'est pourquoi, nous introduisons l'unique paire nom-valeur obligatoire dans un jeton SWT - HMACSHA256. Il s'agit toujours de la dernière paire nom-valeur dans un jeton SWT, et la valeur est le code HMAC SHA 256 des autres paires nom-valeur figurant dans le jeton SWT.

Le choix d'autres paires nom-valeur utilisées dans le jeton SWT sort du cadre de cette spécification. Cela dit, plusieurs conditions et attributs ont prouvé leur utilité dans divers infrastructures d'assertion. Il s'agit en particulier des éléments suivants : Issuer, Audience et ExpiresOn. Si l'utilisation de ces paires nom-valeur n'est pas obligatoire, nous les définissons ici pour faciliter l'interopérabilité.

Enfin, nous pensons que beaucoup d'attributs seront créés par des parties échangeant des jetons SWT. Nous utilisons des noms DNS inverses pour faciliter la création de noms d'attributs sans devoir se soucier d'éventuelles collisions de noms. Nous prenons également en charge l'utilisation d'URI comme noms. Les noms qui ne sont pas des noms DNS inverses ou des URI sont des noms privés, définis par un contrat entre le producteur et le consommateur du jeton SWT. De ce fait, ils sont susceptibles de collision. Les noms définis dans cette spécification sont réservés.

Les mots clés « DOIT », « NE PEUT PAS », « REQUIS », « DOIT », « NE DOIT PAS », « RECOMMANDÉ », « PEUT » et « FACULTATIF » utilisés dans ce document doivent être interprétés comme décrit dans [RFC2119] (Bradner, B, « Mots clés à utiliser dans les documents RFC pour indiquer les niveaux d'exigence »).. Les exemples de nom de domaine utilisent [RFC2606] (Eastlake, D. et A. Panitz, « Noms DNS de niveau supérieur réservés »)..

La partie qui génère un jeton SWT est le producteur du jeton. La partie qui vérifie un jeton SWT est le consommateur du jeton. Avant de générer un jeton SWT, le producteur et le consommateur sont convenus des attributs devant figurer dans le jeton, et ont échangé une clé 256 bits générée de manière aléatoire hors bande. Pour générer un jeton SWT, le producteur procède comme suit :

  1. Il collecte les paires nom-valeur à transporter dans le jeton SWT et les encode dans un formulaire sous la forme application/x-www-form-urlencoded, comme décrit dans la section 17.13.4 de HTML 4.01.

  2. Il entre le jeton SWT encodé en formulaire, et la clé convenue pour le processus SHA 256 HMAC.

  3. Il prend la valeur de clé HMAC obtenue et l'encode en base 64, comme décrit dans la section 4 de la norme RFC 4648.

  4. Il respecte les règles d'encodage de formulaire pour ajouter le nom « HMACSHA256 » et la valeur de clé HMAC codée en base 64 à la fin du jeton SWT encodé en formulaire.

Le consommateur d'un jeton SWT procède comme suit pour vérifier que le jeton SWT a été généré par le producteur et n'a pas été falsifié :

  1. Il prend le jeton SWT, et fractionne la chaîne en la portion située devant « &HMACSHA256 = » et la portion restante, qui est la valeur de clé HMAC encodée en URL. La première portion est noHMACSWT.

  2. Il décode en URL la portion restante de la chaîne SWT. Il s'agit de submittedHMAC.

  3. Il génère une valeur de clé HMAC pour noHMACSWT en utilisant la clé convenue, puis l'encode en base 64 conformément à l'encodage en base 64 décrit dans la section 4 de la norme RFC 4648. La chaîne obtenue est localHMAC.

  4. Il effectue une comparaison caractère par caractère entre les chaînes submittedHMAC et localHMAC. Si les chaînes sont identiques, la valeur de clé HMAC sur le jeton SWT est valide.

Un producteur de jeton SWT souhaite émettre un jeton SWT avec les informations suivantes :

Issuer = issuer.example.com
ExpiresOn = 1/1/2010, Midnight
com.example.group = gold
over18 = true

Avec la valeur de clé HMAC (représentée en base 64) suivante :

N4QeKa3c062VBjnVK6fb+rnwURkcwGXh7EoNK34n0uM=

Dans cet exemple, les éléments Issuer et ExpiresOn sont des noms réservés de cette spécification. L'attribut com.example.group est celui convenu dans la définition de la syntaxe et de la sémantique de groupe créée par le propriétaire du domaine example.com. Et over18 est un attribut défini de façon privée, convenu entre le producteur et le consommateur du jeton SWT.

Avant d'encoder le jeton SWT, nous devons convertir ExpiresOn en un nombre de secondes à partir du 1/1/1970 à minuit UTC, jusqu'à l'heure d'expiration, le 1/1/2010 à minuit. Le résultat est 1 262 304 000.

  1. Encodez les paires nom-valeur dans un formulaire HTML. Le résultat est le suivant (sauts de ligne insérés pour une meilleure lisibilité) :

    Issuer=issuer.example.com&
    ExpiresOn=1262304000&
    com.example.group=gold&
    over18=true
    
  2. Ensuite, calculez la valeur de clé HMAC de la valeur précédente en utilisant la clé.

  3. Encodez la valeur de clé HMAC en base 64. Le résultat est le suivant :

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
    
  4. Codez en URL la valeur de clé HMAC encodée en base 64, et ajoutez-la à la fin de l'assertion. Le jeton SWT ainsi obtenu est le suivant (sauts de ligne insérés pour une meilleure lisibilité) :

    Issuer=issuer.example.com&
    ExpiresOn=1262304000&
    com.example.group=gold&
    over18=true&
    HMACSHA256=
    AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D
    

  1. Fractionnez le jeton SWT en utilisant : &HMACSHA256= Nous obtenons la chaîne noHMACSWT suivante (sauts de ligne ajoutés pour une meilleure lisibilité) :

    Issuer=issuer.example.com&
    ExpiresOn=1262304000&
    com.example.group=gold&
    over18=true&
    
    Et nous obtenons la chaîne submittedHMAC suivante :

    AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D
    
  2. Ensuite, décodez par URL la valeur submittedHMAC. Le résultant est le suivant :

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
    
  3. Nous calculons ensuite la valeur localHMAC en utilisant noHMACSWT et la valeur de clé HMAC, et encodons en base 64 le résultat pour obtenir la valeur localHMAC suivante :

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
    
  4. Nous comparons les valeurs submittedHMAC et localHMAC, et constatons que les chaînes sont identiques. Nous décodons ensuite noHMACSWT par URL pour accéder aux valeurs de jeton SWT.

Les paires nom-valeur suivantes sont facultatives. Elles sont définies afin de faciliter l'interopérabilité pour les nombreux scénarios courants où elles sont utiles.

 

Nom Syntaxe de la valeur Sémantique de la valeur

Issuer

Chaîne UTF-8

Identifie la partie qui émet le jeton SWT.

ExpiresOn

Chaîne ASCII qui représente un nombre entier en base 10 non signé.

Identifie le moment où le jeton SWT ne doit ne pas être accepté pour un traitement supplémentaire.

Les date et heure d'expiration sont enregistrées en tant que nombre de secondes séparant l'heure 1970-01-01T0:0:0Z et le moment d'expiration mesuré en heure UTC.

Audience

Chaîne UTF-8

Identifie le public du jeton SWT auquel le jeton SWT est destiné. Le but est que, si un consommateur de jeton SWT reçoit un jeton SWT dont la valeur « audience » n'identifie pas le public du jeton SWT, celui-ci est rejeté.

Un producteur de jeton SWT peut utiliser un nom DNS inverse ou un URI pour définir des attributs supplémentaires.

Un producteur et un consommateur de jeton SWT peuvent convenir de n'importe quel nom d'attribut qui n'est pas un nom réservé ou public. Ces noms ne doivent pas figurer dans la liste des noms réservés répertoriés dans la section « Noms réservés » ci-dessus. Contrairement aux noms publics, ces noms privés sont sujets à collision, et doivent être utilisés avec précaution.

Voir aussi

Afficher: