Façade d'authentification
La façade d'authentification permet d'exposer de manière uniforme au sein de l'API gateway d'Okapi des services d'authentification tiers basés sur les standard OAuth2.
Contexte
Les APIs exposées sur la plateforme Okapi peuvent nécessiter l'utilisation d'une autorisation basée sur un access token, issue de l'authentification de l'utilisateur final.
Par ailleurs, la plateforme Okapi authentifie naturellement les appels au travers de la clé d'app, fournie dans un entête X-Okapi-Key.
Le but de la façade d'authentification est de supporter l'utilisation d'un access token délivré lors de l'authentification de l'utilisateur final via un serveur OAuth2 (ou OIDC), comme autorisation de l'application à consommer l'API, se substituant à l'entête X-Okapi-Key afin d'éviter au développeur la nécessité d'une double autorisation.
Le serveur d'autorisation et d'authentification massivement utilisé dans le cadre des API BNum est celui de MonCompte.
Remarques :
- Le besoin de la plateforme Okapi est d'authentifier le client consommateur des API (le développeur).
- Un serveur d'autorisation OAuth2 ou OIDC a plutôt vocation à identifier et authentifier le Resource Owner, même si cela inclut l'identification du consommateur (l'application).
- Le serveur d'autorisation MonCompte se base principalement, en v2, sur une implémentation OAuth2 avec une partie d'OIDC (OpenID Connect), tandis qu'en v3 il se base sur une implémentation OIDC incluant des aspects de OAuth2.
Rôles {#rôles}
Significations des rôles et correspondance avec la terminologie OAuth :
- User (utilisateur) : Resource Owner
- Browser (navigateur) : User Agent
- App (appli consommant la ressource API) : Client (ou Relying Party pour OIDC)
- Okapi (API management) : API Gateway
- AS (implémentation OAuth2) : Authorization Server (ou OIDC Provider)
- RS (référentiel personnes physiques) : Resource Server
- API (api) : Resource Server
Demande d'authorisation
La vocation de cette route est de :
- retourner une redirection web vers l'URL authorize configurée pour l'API
L'activation de la fonctionnalité se fait en déclarant le plugin de pré-traitement authorize sur la route, aucun endpoint n'est nécessaire
Exemple de requête :
$ curl -XPOST https://api.laposte.fr/auth/myapi/v2/authorize \
# Autorisation par clé d'app Okapi
-H "X-Okapi-Key: myappkey" \
# Données (OAuth)
-d "client_id=mycliendid" \
-d "redirect_uri=http://myapp.io/mycallback"
Exemple de réponse :
{
"url": "https://integration.compte.laposte.fr/v2/authorize?client_id=mycliendid&redirect_uri=http://myapp.io/mycallback"
}
L'attribut url obtenu dans la réponse JSON est ensuite utilisé par l'application pour lancer un user agent afin d'initier le parcours web.
La différence entre la requête authorize reçue par le serveur d'autorization et celle reçue par Okapi réside en l'ajout des informations suivantes :
- Méthode POST ou GET
- Paramètre d'URI url_context : contient le contexte d'URL de l'API souhaitée, tel que défini lors de la création de l'API sur la plateforme Okapi
- Paramètre d'URI version : contient la version de l'API souhaitée, telle que définie lors de la création de l'API sur la plateforme Okapi
- Entête X-Okapi-Key : clé d'app permettant d'authentifier le consommateur Okapi
Ces informations sont requises par Okapi pour vérifier la souscription.
Séquence :
Remarque : les étapes en pointillés sont mentionnées afin de faciliter la compréhension, mais ne participent pas directement au fonctionnement de la façade.
Obtention du token
L'objectif est de permettre à l'app de récupérer le token à partir du code d'autorisation.
La vocation de cette route est de :
- vérifier les autorisations de la requête : une clé d'app Okapi est fournie, une API est mentionnée, et une souscription existe
- relayer la demande au serveur d'autorisation
- associer l'access token généré dans la réponse du serveur d'autorisation avec la clé d'app du développeur, avec le TTL fourni
L'activation de la fonctionnalité se fait en déclarant le plugin de pré/post-traitement token sur la route, aucun endpoint n'est nécessaire
Exemple de requête :
$ curl -XPOST https://api.laposte.fr/auth/myapi/v2/token \
# Autorisation par clé d'app Okapi
-H "X-Okapi-Key: myappkey" \
# Données (OAuth)
...
Séquence :
Configuration
Exemple de configuration d'API, avec la déclaration des endpoints OAuth2 :
name: 'My Api',
urlContext: 'myapi',
version: '2',
published: true,
endpoint: https://myapiendpoint.com/myapirootpath
extra:
auth:
authorizeParams:
client_id: myclientid
scope: myscope
authorizeUrl: https://myauthserver.com/oauth/authorize
tokenUrl: https://myauthserver.com/oauth/token
Remarques :
- L'attribut optionnel authorizeParams permet d'ajouter des paramètres (constantes) au payload de la requête authorize.
- Les attributs authorizeUrl et tokenUrl sont obligatoires car ils indiquent les URLs absolues du serveur d'autorisation OAuth2 nécessaires au bon fonctionnement de la façade.
Exemple de configuration de resource pour la route POST authorize :
method: post
name: 'Post /authorize'
plugins:
- authorize
published: true
route: '/authorize'
Exemple de configuration de resource pour la route POST token :
method: post
name: 'Post /token'
plugins:
- token
published: true
route: '/token'
Vérification du token (non prévu, à définir ultérieurement) {#vérification-du-token-non-prévu-à-définir-ultérieurement}
La façade peut exposer une route permettant la vérification du token, et éventuellement la fourniture de données en réponse.
Séquence :
Consommation API
L'appli consomme l'API avec son token, il n'y a plus besoin de fournir de clé d'app.
Optionnellement, il est possible de demander à la façade de vérifier pour le compte de l'API la validité du token.
Séquence :
Séquence alternative (non prévu, à définir ultérieurement) : vérification du token par la façade
Refresh token (non prévu, à définir ultérieurement) {#refresh-token-non-prévu-à-définir-ultérieurement}
L'appli demande une régénération du token.
Séquence :
Serveur de démo {#serveur-de-démo}
Références {#références}
Ressources utiles :
