OAuth2 & OIDC

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=...           ← PKCE

PKCE (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.

http
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:read

Resource 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.

http
POST /oauth2/{realm}/access_token
grant_type=password
&username=alice
&password=Secret1234!
&client_id=mon-client
&scope=openid

Refresh Token#

Renouveler un access token expiré sans ré-authentification de l’utilisateur.

http
POST /oauth2/{realm}/access_token
grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=mon-client

Device 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 :

Faites défiler le tableau
TOSIAMRFC 8628
Code à l’attentecodedevice_code
Adresse renvoyéeverification_urlverification_uri
response_typeobligatoireabsent

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/code vérifie la demande. Un type de réponse inconnu, absent de la fiche du client, ou token seul avec le scope openid (règle OpenID Connect) est refusé par 400 unsupported_response_type ; un scope que le client n’a pas, par 400 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_pending et le refus répondaient 403, expired_token 401. 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épond invalid_grant.
  • Un ID token avec le scope openid. L’appareil le reçoit avec l’access token et le refresh token. Son sub est l’utilisateur, son nonce celui de la demande à device/code, son auth_time la date à laquelle l’utilisateur s’est authentifié sur la page. Le type de réponse doit alors être code, puisque token seul est refusé avec openid.
  • 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 jetons

La 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 forme clt|<identifiant du client>. Sinon : invalid_grant « This client is not authorized as actor for token-exchange ».
http
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_token

Le 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.

Faites défiler le tableau
ParamètreRègle
scopeBorné 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_tokenQui 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_typeurn:ietf:params:oauth:token-type:access_token, ou …:jwt pour un client dont les access tokens sont des JWT ; tout autre type : invalid_request.
audienceNon 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.

http
POST /oauth2/{realm}/access_token
grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer
&assertion=BASE64_SAML_ASSERTION
&scope=openid

JWT 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é.

http
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:read

L’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#

http
# 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_token

Mis à jour le