Aller au contenu principal

Préparer une requête authentifiée vers l'API

Après avoir créé et configuré un compte de service, votre application doit suivre les étapes suivantes :

  1. Créer un JSON Web Token (JWT), qui comprend l'en-tête, le payload et la signature ;
  2. Demander un jeton d'accès (AccessToken) à la plateforme d'authentification OAuth2 ;
  3. Traiter la réponse JSON que la plateforme d'authentification renverra.

Si la réponse inclut un jeton d'accès, vous pouvez l'utiliser pour effectuer des requêtes vers les API produit d'Unico pour lesquelles le compte de service dispose des autorisations d'accès. (Si la réponse n'inclut pas de jeton d'accès, votre JWT et votre requête de jeton peuvent être incorrects, ou le compte de service peut ne pas disposer des autorisations nécessaires pour accéder aux ressources demandées.)

Le jeton d'accès généré lors de la requête mentionnée ci-dessus a une validité par défaut de 3600 secondes, mais celle-ci peut varier selon la configuration de sécurité définie pour votre entreprise. Lorsque le jeton d'accès expire, votre application doit générer un nouveau JWT, le signer et demander un nouveau jeton d'accès à la plateforme d'authentification.

1 — Création du JWT​

Un JWT est composé de trois parties : un en-tête, un payload et une signature. L'en-tête et le payload sont des objets JSON. Ces objets JSON sont sérialisés en UTF-8, puis encodés à l'aide de l'encodage Base64url¹. Cet encodage offre une résilience face aux modifications d'encodage en cas d'opérations d'encodage répétées. L'en-tête, le payload et la signature sont concaténés avec un caractère point (.).

Un JWT est composé comme suit :

{En-tête en Base64url}.{Payload en Base64url}.{Signature en Base64url}

Le texte de base pour la signature est composé comme suit :

{En-tête en Base64url}.{Payload en Base64url}

1.1 — Formation de l'en-tête du JWT​

L'en-tête se compose de deux champs qui précisent l'algorithme de signature et le format du jeton. Les deux champs sont obligatoires, et chaque champ n'a qu'une seule valeur. Les comptes de service reposent sur l'algorithme RSA SHA-256 et le format de jeton JWT. Par conséquent, la représentation JSON de l'en-tête est la suivante :

{"alg":"RS256","typ":"JWT"}

La représentation en Base64url est la suivante :

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 — Formation du payload du JWT​

Le payload du JWT contient des informations sur le JWT, notamment les permissions demandées (scopes), le compte demandant l'accès, l'émetteur, l'heure d'émission du jeton et sa durée de vie. La plupart des champs sont obligatoires. Tout comme l'en-tête du JWT, le payload est un objet JSON et est utilisé dans la composition de la signature.

1.3 — Champs obligatoires​

Les champs obligatoires du JWT sont présentés dans le tableau ci-dessous. Ils peuvent apparaître dans n'importe quel ordre dans le payload.

NomDescription
issL'identifiant du compte de service au sein de l'entreprise.
scopeUne liste des permissions demandées par l'application, séparées par des espaces ou par le signe plus (+). Si toutes les permissions du compte sont requises, utilisez le symbole astérisque (*) pour cela.
audL'adresse de la plateforme d'authentification qui émet les jetons d'accès. Cette valeur doit toujours être exactement https://identityhomolog.acesso.io. Problèmes courants qui ne fonctionnent pas : ajouter une barre oblique finale (https://identityhomolog.acesso.io/), ou utiliser HTTP au lieu de HTTPS.
expL'heure d'expiration du jeton, exprimée en secondes depuis 00:00:00 UTC, le 1er janvier 1970. Cette valeur a une durée maximale d'1 heure après l'heure d'émission du JWT. Elle doit être numérique — une valeur entre guillemets comme "1524161193" est une chaîne de caractères et ne fonctionnera pas ; 1524161193 est un nombre et fonctionnera.
iatL'heure d'émission du JWT, exprimée en secondes depuis 00:00:00 UTC, le 1er janvier 1970. Cette valeur doit être numérique, selon la même règle que exp.

Le champ iat doit représenter l'heure actuelle dans le format requis, et le champ exp doit respecter le calcul suivant :

exp = iat + 3600

La représentation des champs JSON obligatoires dans le payload du JWT est la suivante :

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976,
  "iat": 1626293376
}

1.4 — Calcul de la signature​

La spécification **JSON Web Signature (JWS)**² est le mécanisme qui régit le calcul de la signature d'un JWT. Le contenu d'entrée pour le calcul de la signature est le tableau d'octets du contenu suivant :

{En-tête en Base64url}.{Payload en Base64url}

Le même algorithme spécifié dans l'en-tête du JWT doit être utilisé pour le calcul de la signature. Le seul algorithme de signature pris en charge par la plateforme d'authentification OAuth2 est RSA utilisant SHA-256, exprimé par RS256 dans le champ alg de l'en-tête du JWT.

Signez la représentation UTF-8 du contenu d'entrée à l'aide de SHA256withRSA (également connu sous le nom de RSASSA-PKCS1-V1_5-SIGN avec le hachage SHA-256) avec la clé privée créée et associée au compte de service (le fichier .key.pem généré à partir de la demande reçue par e-mail). Le contenu de sortie sera un tableau d'octets.

La signature doit ensuite être encodée en Base64url. L'en-tête, le payload et la signature doivent être concaténés avec un caractère point. Le résultat est le JWT.

Il est également possible d'utiliser des bibliothèques préétablies pour créer le JWT. À titre de référence, vous trouverez une liste de bibliothèques sur le site jwt.io.

2 — Demande d'un jeton d'accès​

Après avoir généré le JWT signé, une application peut l'utiliser pour demander un jeton d'accès. La requête de jeton d'accès est une requête POST HTTPS, et le corps doit être encodé en URL. L'URL est indiquée ci-dessous :

https://identityhomolog.acesso.io/oauth2/token

Les paramètres suivants sont obligatoires dans la requête POST HTTPS :

NomDescription
grant_typeUtilisez le texte suivant, encodé en URL si nécessaire : urn:ietf:params:oauth:grant-type:jwt-bearer
assertionLe JWT, incluant la signature.
POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<jwt>

3 — Traitement de la réponse de la plateforme d'authentification​

Si le JWT et la requête de jeton d'accès sont correctement formés, et si le compte de service dispose des autorisations nécessaires, la plateforme d'authentification renverra un objet JSON contenant un jeton d'accès :

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

Le jeton d'accès renvoyé dans le champ access_token de l'objet JSON est également un jeton JWT qui doit être utilisé dans les API des produits Unico. En cas d'erreur lors de la requête, vérifiez le type d'erreur dans Erreurs d'authentification.

4 — Durée du jeton d'accès​

La durée du jeton d'accès est variable. Sa durée est précisée dans le champ expires_in, renvoyé avec le jeton d'accès. Le même jeton d'accès doit être utilisé pendant toute sa validité pour tous les appels API vers les produits.

Ne demandez pas un nouveau jeton d'accès tant que la validité du jeton actuel n'approche pas de sa fin. Nous recommandons une marge de 600 secondes (10 minutes) :

new Date((token.exp - 600) * 1000)

Où token.exp est l'horodatage de l'expiration du jeton.

remarque

Par défaut, le jeton envoyé à l'entreprise dure 1 heure, mais cela peut être modifié. La recommandation est de toujours utiliser expires_in comme base et d'en soustraire 600 s pour demander un nouveau jeton.

Exemples :

Scénario standard :
expires_in: 3600 (1h) - Jeton généré à 14:42
Demandez un nouveau jeton seulement à 15:32, c'est-à-dire 14:42 + (3600 - 600)
Scénario avec durée modifiée :
expires_in: 7200 (2h) - Jeton généré à 14:42
Demandez un nouveau jeton seulement à 16:32, c'est-à-dire 14:42 + (7200 - 600)
avertissement

N'utilisez pas une heure fixe pour obtenir un nouveau jeton, car la durée du jeton reçu peut être plus courte que le temps établi, ce qui pourrait provoquer des échecs lors de l'utilisation des services.

¹ Selon la RFC 4648 pour l'encodage BaseN, le format Base64url est similaire à Base64, à ceci près que le caractère = est omis, et que les caractères + et / sont remplacés respectivement par - et _. ² JSON Web Signature : https://tools.ietf.org/html/rfc7515.

Dernière mise à jour le