Authentification OAuth 2.0 d'une API provider

Ce document décrit la configuration permettant à API-Gateway de consommer une API provider sécurisée par une authentification OAuth 2.0.

L'objectif est de permettre à OKAPI de récupérer automatiquement un token OAuth 2.0, de le mettre en cache dans Redis, puis de l'injecter dans les appels vers l'API provider via le header HTTP Authorization.

Cas d'usage

• API provider nécessitant une authentification OAuth 2.0.
• API nécessitant un token Bearer pour chaque appel.
• API consommée par API-Gateway avec le flow OAuth 2.0 client_credentials ou password.
• API nécessitant éventuellement un scope pour définir les permissions associées au token OAuth 2.0.

Principe de fonctionnement

L'API déclare dans son raccordement les informations nécessaires à l'authentification OAuth 2.0 dans le bloc extra.oauth2.

Lorsqu'un appel est effectué vers l'API provider, OKAPI récupère un token OAuth 2.0 auprès du tokenEndpoint configuré, puis appelle l'API provider en ajoutant le header HTTP suivant :

Authorization: Bearer <access_token>

Le token est récupéré à partir des informations déclarées dans la configuration OAuth 2.0 de l'API.

Flow OAuth 2.0 utilisé

La configuration OAuth 2.0 permet à OKAPI de récupérer un token auprès du tokenEndpoint configuré.

Deux flows peuvent être utilisés selon le besoin du provider :

• client_credentials : flow Machine-to-Machine, recommandé pour les appels entre OKAPI et une API provider.
• password : flow utilisant un nom d'utilisateur et un mot de passe.

Flow client credentials

Le flow client_credentials est adapté aux échanges Machine-to-Machine, lorsque l'appel à l'API provider est effectué par OKAPI sans contexte utilisateur final.

L'appel au token endpoint est réalisé avec les paramètres suivants :

grant_type=client_credentials
client_id=<CLIENT_ID>
client_secret=<CLIENT_SECRET>
scope=<SCOPE>

Le paramètre scope est facultatif et peut être omis si le serveur d'autorisation OAuth 2.0 ne l'exige pas.

Flow password

Le flow password peut être utilisé si le serveur d'autorisation OAuth 2.0 du provider le nécessite.

L'appel au token endpoint est réalisé avec les paramètres suivants :

grant_type=password
client_id=<CLIENT_ID>
client_secret=<CLIENT_SECRET>
username=<USERNAME>
password=<PASSWORD>
scope=<SCOPE>

Le paramètre scope est facultatif et peut être omis si le serveur d'autorisation OAuth 2.0 ne l'exige pas.

Le serveur OAuth 2.0 doit retourner une réponse contenant au minimum les informations suivantes :

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600
}

Le champ access_token est ensuite utilisé comme token Bearer pour appeler l'API provider.

Schéma du parcours pour le flow client_credentials

Configuration dans le raccordement de l'API

La configuration OAuth 2.0 se fait dans le champ extra.oauth2 du raccordement de l'API.

Attributs disponibles

• grantType (string) : type de grant OAuth 2.0 utilisé.

  • Valeurs possibles :
    • client_credentials : flow Machine-to-Machine recommandé.
    • password : flow utilisant un nom d'utilisateur et un mot de passe.

• tokenEndpoint (string) : URL du endpoint OAuth 2.0 permettant de récupérer le token.

• clientId (string) : identifiant du client OAuth 2.0.

• clientSecret (string) : secret du client OAuth 2.0.

• username (string, facultatif) : nom d'utilisateur utilisé uniquement avec le flow password.

• password (string, facultatif) : mot de passe utilisé uniquement avec le flow password.

• scope (string, facultatif) : permissions, ou droits d'accès, que le token OAuth 2.0 devra posséder.

• durationBeforeRefresh (integer) : durée, en secondes, utilisée pour anticiper le renouvellement du token avant son expiration.

  • Exemple : 10

Exemple de configuration avec le flow client_credentials

- type: api
  value:
    name: My Api
    urlContext: monapi
    version: '1'
    ...
    extra:
      oauth2:
        grantType: client_credentials
        tokenEndpoint: <TOKEN_ENDPOINT_URL>
        clientId: <CLIENT_ID>
        clientSecret: <CLIENT_SECRET>
        scope: <SCOPE>
        durationBeforeRefresh: 10

Le champ scope est facultatif et peut être supprimé si aucun scope n'est attendu par le serveur d'autorisation OAuth 2.0.

Exemple minimal

extra:
  oauth2:
    grantType: client_credentials
    tokenEndpoint: <TOKEN_ENDPOINT_URL>
    clientId: <CLIENT_ID>
    clientSecret: <CLIENT_SECRET>
    scope: <SCOPE>
    durationBeforeRefresh: 10

Le champ scope est facultatif.

Configuration pour un endpoint sandbox

Si l'API dispose d'un endpoint sandbox, la configuration OAuth 2.0 peut être déclarée dans le bloc extra.sandbox.oauth2.

- type: api
  value:
    name: My Api
    urlContext: monapi
    version: '1'
    ...
    extra:
      sandbox:
        oauth2:
          grantType: client_credentials
          tokenEndpoint: <SANDBOX_TOKEN_ENDPOINT_URL>
          clientId: <SANDBOX_CLIENT_ID>
          clientSecret: <SANDBOX_CLIENT_SECRET>
          scope: <SANDBOX_SCOPE>
          durationBeforeRefresh: 10

Le champ scope est facultatif et peut être supprimé si aucun scope n'est attendu pour l'environnement sandbox.

Header injecté vers l'API provider

Une fois le token récupéré, OKAPI injecte automatiquement le header suivant dans la requête envoyée à l'API provider :

Authorization: Bearer <access_token>

Exemple :

Authorization: Bearer abc123

Flux complet

1. OKAPI / Service vérifie si un token OAuth 2.0 est présent dans Redis.

2. Si aucun token n'est présent, ou si le token est expiré, OKAPI appelle le tokenEndpoint configuré.

3. L'appel au token endpoint est effectué avec les paramètres suivants :

   • grant_type=client_credentials ou grant_type=password
   • client_id
   • client_secret
   • username, uniquement pour le flow password
   • password, uniquement pour le flow password
   • scope, facultatif

4. Le serveur OAuth 2.0 retourne :

   • access_token
   • expires_in

5. OKAPI stocke le token dans Redis.

6. OKAPI récupère le token depuis Redis.

7. OKAPI appelle l'API provider avec le header :

   Authorization: Bearer <access_token>

8. L'API provider est appelée avec le token OAuth 2.0.