Grant Types

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 (RFC 8628)#

Pour les appareils sans navigateur (TV, IoT, CLI). L’appareil affiche un code court, l’utilisateur le valide sur un autre appareil.

1. POST /oauth2/{realm}/device/code
   client_id=mon-client&scope=openid

   → Retourne : device_code, user_code, verification_uri, expires_in, interval

2. Afficher à l'utilisateur l'adresse verification_uri et le code :
   "Allez sur <verification_uri> et entrez : ABCD-1234"

3. L'appareil poll toutes les {interval} secondes :
   POST /oauth2/{realm}/access_token
   grant_type=http://oauth.net/grant_type/device/1.0
   &device_code=DEVICE_CODE
   &client_id=mon-client

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 : indiquez une valeur déclarée dans la table de correspondance ACR du fournisseur OAuth2, sinon aucune authentification n’est lancée. 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 un token existant contre un token d’une autre forme ou pour un autre sujet (délégation, impersonation, cross-service).

http

POST /oauth2/{realm}/access_token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=SUBJECT_TOKEN
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&requested_token_type=urn:ietf:params:oauth:token-type:access_token
&scope=api:read
&audience=https://api.example.com

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