Grant Types
Sur cette page
TOSIAM supporte neuf grant types OAuth 2.0. Chaque grant type correspond à un scénario d’utilisation précis.
Authorization Code (+ PKCE)#
Le flux standard pour les applications web et mobiles. Le client redirige l’utilisateur vers TOSIAM, reçoit un code d’autorisation, puis l’échange contre un access token.
1. GET /oauth2/{realm}/authorize
?response_type=code
&client_id=mon-client
&redirect_uri=https://app.example.com/callback
&scope=openid email
&code_challenge=... ← PKCE (recommandé)
&code_challenge_method=S256
2. POST /oauth2/{realm}/access_token
grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://app.example.com/callback
&code_verifier=... ← PKCEPKCE (RFC 7636) est recommandé pour tous les clients, obligatoire pour les clients publics (SPA, mobile).
Client Credentials#
Pour les appels machine-to-machine (M2M) sans utilisateur. Le client s’authentifie directement avec ses propres credentials.
POST /oauth2/{realm}/access_token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=api:readResource Owner Password (ROPC)#
L’utilisateur transmet directement ses credentials au client, qui les envoie à TOSIAM. Déprécié dans OAuth 2.1, à éviter pour les nouveaux projets.
POST /oauth2/{realm}/access_token
grant_type=password
&username=alice
&password=Secret1234!
&client_id=mon-client
&scope=openidRefresh Token#
Renouveler un access token expiré sans ré-authentification de l’utilisateur.
POST /oauth2/{realm}/access_token
grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=mon-clientDevice Authorization#
Pour les appareils sans navigateur (TV, IoT, CLI). L’appareil affiche un code court, l’utilisateur le valide sur un autre appareil.
TOSIAM implémente l’ancien brouillon de ce flux (draft-ietf-oauth-v2-05), pas la RFC 8628 qui l’a normalisé ensuite : les bibliothèques clientes conformes à la RFC 8628 ne fonctionnent donc pas telles quelles. Le grant type est http://oauth.net/grant_type/device/1.0, et non urn:ietf:params:oauth:grant-type:device_code, et d’autres paramètres diffèrent :
| TOSIAM | RFC 8628 | |
|---|---|---|
| Code à l’attente | code | device_code |
| Adresse renvoyée | verification_url | verification_uri |
response_type | obligatoire | absent |
La découverte (/.well-known/openid-configuration) n’annonce pas non plus l’endpoint device/code.
1. POST /oauth2/{realm}/device/code
client_id=mon-client&scope=openid&response_type=token
→ Retourne : device_code, user_code, verification_url,
expires_in (300 s par défaut), interval (5 s par défaut)
2. Afficher à l'utilisateur l'adresse verification_url et le code :
"Allez sur <verification_url> et entrez : CZ7F4XBS"
(lien direct : <verification_url>?user_code=CZ7F4XBS)
3. L'appareil interroge l'endpoint de jeton toutes les {interval} secondes :
POST /oauth2/{realm}/access_token
grant_type=http://oauth.net/grant_type/device/1.0
&code=DEVICE_CODE
&client_id=mon-client
→ 400 authorization_pending tant que l'utilisateur n'a pas validé,
400 slow_down si l'appareil interroge plus vite que l'intervalle,
puis 200 avec access_token et refresh_token une fois le code validé
(et id_token avec le scope openid),
400 access_denied si l'utilisateur a refusé,
400 expired_token une fois le code expiré,
400 invalid_grant pour un code inconnu ou déjà échangéLe client doit avoir le grant http://oauth.net/grant_type/device/1.0 dans sa liste, et le response_type demandé dans ses types de réponse (token pour un client OAuth2, code avec le scope openid). La durée de vie du code et l’intervalle d’interrogation se règlent dans le fournisseur OAuth2 (« Durée de vie du code d’appareil (secondes) », « Intervalle d’interrogation des appareils »).
verification_url est la page du royaume du client, /oauth2/{realm}/device/user. L’utilisateur s’y connecte, saisit le code (sans tenir compte de la casse) puis accepte sur l’écran de consentement ; avec ?user_code= dans l’adresse, il passe directement de la connexion au consentement. Le réglage « URL de vérification » du fournisseur OAuth2 remplace l’adresse renvoyée, par exemple pour une page à vous.
À partir de la 3.38.0 :
device/codevérifie la demande. Un type de réponse inconnu, absent de la fiche du client, outokenseul avec le scopeopenid(règle OpenID Connect) est refusé par400 unsupported_response_type; un scope que le client n’a pas, par400 invalid_scope. Aucun code n’est créé. Avant, l’erreur n’apparaissait que sur la page de l’utilisateur, pendant que l’appareil attendait l’expiration.- Les erreurs de l’attente répondent 400, comme le prévoient la RFC 6749 (section 5.2) et la RFC 8628 :
authorization_pendinget le refus répondaient 403,expired_token401. Il en va de même pour CIBA. - Un refus se distingue d’un code inconnu.
access_denied(avant la 3.38.0,authorization_declined) signifie que l’utilisateur a refusé, et l’appareil le reçoit à chaque interrogation jusqu’à l’expiration du code. Un code inconnu, ou déjà échangé contre des jetons, répondinvalid_grant. - Un ID token avec le scope
openid. L’appareil le reçoit avec l’access token et le refresh token. Sonsubest l’utilisateur, sonnoncecelui de la demande àdevice/code, sonauth_timela date à laquelle l’utilisateur s’est authentifié sur la page. Le type de réponse doit alors êtrecode, puisquetokenseul est refusé avecopenid. - Une validation n’est plus perdue. Si l’appareil interrogeait à l’instant où l’utilisateur validait, la validation pouvait être effacée : la page affichait « Done! » et l’appareil attendait jusqu’à l’expiration du code.
- Des pages en français, dans l’ancienne interface comme dans la nouvelle : saisie du code, code introuvable, et une page de fin qui dit « Terminé » après un accord et « Accès refusé » après un refus.
Le tutoriel Connecter un appareil (device flow) construit un appareil complet, avec les captures de chaque page.
CIBA (Client-Initiated Backchannel Authentication, OpenID Connect)#
Authentification asynchrone : le client demande l’authentification d’un utilisateur, TOSIAM la mène sans redirection du navigateur (par exemple par une notification sur son téléphone), puis le client récupère les jetons. TOSIAM implémente le mode poll : le client interroge l’endpoint de jeton jusqu’à la décision de l’utilisateur.
La demande est obligatoirement transmise dans un request object signé avec les clés du client (paramètre request), et le client s’authentifie comme sur l’endpoint de jeton.
1. POST /oauth2/{realm}/bc-authorize
Authorization: Basic base64(client_id:client_secret)
request=JWT_SIGNÉ
Claims du JWT :
{
"iss": "mon-client", ← doit être le client_id
"exp": 1790499600, ← obligatoire
"scope": "openid", ← doit contenir openid
"login_hint": "alice", ← un seul indice : login_hint, login_hint_token ou id_token_hint
"acr_values": "push", ← valeur présente dans la correspondance ACR du fournisseur
"binding_message": "Connexion depuis l'app MonApp"
}
→ Retourne : auth_req_id, expires_in, interval
2. Interroger l'endpoint de jeton toutes les {interval} secondes :
POST /oauth2/{realm}/access_token
Authorization: Basic base64(client_id:client_secret)
grant_type=urn:openid:params:grant-type:ciba
&auth_req_id=AUTH_REQ_ID
→ authorization_pending tant que l'utilisateur n'a pas répondu, puis les jetonsLa valeur acr_values choisit le service d’authentification exécuté pour l’utilisateur, par la table de correspondance ACR du fournisseur OAuth2. Sans acr_values, ou avec une valeur absente de la table, c’est l’authentification par défaut du royaume qui est exécutée (avant la version 3.38.0, aucune authentification n’était lancée dans le premier cas, et le second donnait une erreur 500). Le client doit être confidentiel et avoir le grant CIBA dans sa liste. Les modes ping et push, et donc le paramètre client_notification_token, ne sont pas pris en charge.
Token Exchange (RFC 8693)#
Échanger le jeton d’un utilisateur contre un nouveau jeton pour le même utilisateur : une API qui en appelle une autre en son nom (délégation), avec le scope que l’API suivante attend.
Le client qui échange doit :
- être confidentiel et s’authentifier ;
- avoir le grant
urn:ietf:params:oauth:grant-type:token-exchange; - figurer dans la liste des acteurs autorisés du fournisseur OAuth2 (
authorizedActors), sous la formeclt|<identifiant du client>. Sinon :invalid_grant« This client is not authorized as actor for token-exchange ».
POST /oauth2/{realm}/access_token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_id=api-commandes&client_secret=…
&subject_token=JETON_DE_L_UTILISATEUR
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&scope=stock.lecture
&actor_token=JETON_DU_SERVICE ← facultatif
&actor_token_type=urn:ietf:params:oauth:token-type:access_tokenLe jeton émis a pour sujet (sub) l’utilisateur du jeton échangé, pour client le client qui échange, et un refresh token l’accompagne. La réponse porte issued_token_type, le type du jeton émis.
| Paramètre | Règle |
|---|---|
scope | Borné par les scopes du client qui échange (sinon invalid_scope). Un scope du client absent du jeton échangé est accordé : c’est le scope que l’API suivante attend. Sans scope, le jeton garde le scope du jeton échangé, limité aux scopes du client. openid n’est accordé que si le jeton échangé le porte. |
actor_token | Qui agit pour l’utilisateur : un utilisateur (usr|), un membre d’un groupe (grp|) ou un service avec son jeton client_credentials (clt|), déclarés dans les acteurs autorisés ; sinon invalid_grant. Le jeton émis porte alors act : {"sub": "<acteur>"}, imbriqué pour une chaîne d’acteurs. |
requested_token_type | urn:ietf:params:oauth:token-type:access_token, ou …:jwt pour un client dont les access tokens sont des JWT ; tout autre type : invalid_request. |
audience | Non pris en charge : invalid_target. |
L’API qui reçoit le jeton échangé le vérifie comme tout autre jeton, par exemple par introspection : la réponse donne sub, client_id, scope et, avec un acteur, act. Pour introspecter des jetons émis à d’autres clients, son propre client doit avoir le scope am-introspect-all-tokens.
Le tutoriel Délégation entre API avec le token exchange construit une API qui échange le jeton de l’utilisateur pour appeler la suivante, en se déclarant acteur.
SAML2 Bearer (RFC 7522)#
Échange une assertion SAML2 contre un access token OAuth2. Utile pour les migrations SAML → OAuth2 ou les architectures hybrides.
POST /oauth2/{realm}/access_token
grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer
&assertion=BASE64_SAML_ASSERTION
&scope=openidJWT Bearer (RFC 7523)#
Échange une assertion JWT signée par le client contre un access token, sans interaction de l’utilisateur. Utile pour les échanges de serveur à serveur où le client prouve son identité et le sujet de la demande avec sa propre clé.
POST /oauth2/{realm}/access_token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=JWT_SIGNÉ
&scope=api:readL’assertion doit être signée avec une clé asymétrique (les algorithmes HS* et none sont refusés). Son claim iss est le client_id, sub désigne le sujet, aud contient l’adresse de l’endpoint de jeton et exp est obligatoire. Le grant doit figurer dans la liste des grants autorisés du client.
Introspection et révocation#
# Vérifier un token (RFC 7662)
POST /oauth2/{realm}/introspect
Authorization: Basic base64(client_id:client_secret)
token=ACCESS_TOKEN
# Révoquer un token (RFC 7009)
POST /oauth2/{realm}/token/revoke
token=ACCESS_TOKEN&token_type_hint=access_tokenMis à jour le