OpenID Connect (OIDC)¶

Pourquoi OIDC ?¶

OpenID Connect est une couche d’identité construite au-dessus d’OAuth 2.0. OAuth décrit comment un client obtient une autorisation d’accès à une ressource. OIDC standardise en plus la manière dont un client apprend qu’un utilisateur s’est authentifié, principalement grâce à l’ID token. Il est adapté aux applications web, mobiles et aux API, à condition d’utiliser une bibliothèque maintenue et une configuration rigoureuse.

Acteurs : l’OpenID Provider (OP) émet les jetons (Keycloak dans nos exemples), le client / Relying Party (RP) demande l’authentification, le Resource Server protège une API et le navigateur transporte les redirections.

OAuth 2.0, autorisation et flux¶

Un flux (grant) décrit comment le client obtient des jetons. Pour la connexion interactive, privilégiez Authorization Code avec PKCE : le navigateur reçoit un code à usage court, puis le client l’échange contre les jetons. PKCE lie la demande initiale à l’échange grâce à code_challenge / code_verifier, réduisant l’impact d’un code intercepté. Il est recommandé pour les clients publics et peut être utilisé aussi avec des clients confidentiels.

Flux	Quand / comment	Recommandation
Authorization Code + PKCE	Utilisateur interactif ; retour avec un code, puis échange au point `/token`	Choix courant pour web, SPA et mobile. Pour une SPA/mobile, client public sans secret durable ; pour serveur web, client confidentiel, secret conservé côté serveur.
Implicit	Jetons directement retournés dans le navigateur via une réponse d’autorisation	Historique ; généralement déconseillé. Préférer Code + PKCE.
Client Credentials	Service à service, sans utilisateur ; client s’authentifie et reçoit un jeton	Réserver aux traitements machine-à-machine ; droits minimaux.
Refresh token	Renouvellement d’un accès avec un refresh token émis auparavant	Ce n’est pas une connexion initiale ; protéger le jeton, appliquer expiration/rotation et règles du fournisseur.

Un client confidentiel peut protéger un secret dans un serveur contrôlé. Une application exécutée dans un navigateur ou sur l’appareil d’un utilisateur ne peut pas garder un secret statique : elle est généralement publique. Le PKCE ne transforme pas un client public en client confidentiel.

Schéma : Code + PKCE¶

sequenceDiagram
    actor U as Utilisateur
    participant C as Client / navigateur
    participant K as Keycloak (OP)
    participant R as API protégée
    C->>C: Génère code_verifier et code_challenge
    C->>K: /authorize (client_id, scope, redirect_uri, challenge)
    K->>U: Authentification / consentement si requis
    U->>K: S'authentifie
    K-->>C: Redirection redirect_uri avec authorization code
    C->>K: POST /token (code, verifier, client auth si confidentiel)
    K-->>C: ID token, access token, éventuellement refresh token
    C->>C: Valide l'ID token et crée une session locale
    C->>R: Appel API avec access token
    R->>K: Peut récupérer / utiliser les clés JWKS pour valider la signature
    R-->>C: Réponse autorisée

L’application doit contrôler les paramètres state (corrélation et protection CSRF) et nonce (liaison de la réponse OIDC à la requête), vérifier la redirection attendue et appliquer les validations OIDC. Ne faites pas confiance à un jeton simplement parce qu’il est décodable.

Endpoints usuels¶

Les URL exactes varient avec le contexte de déploiement et le realm. Pour un serveur local par défaut, la base OIDC est généralement http://localhost:8080/realms/<realm> ; utilisez HTTPS hors développement. Le document de découverte fournit les URL officielles pour l’instance :

/.well-known/openid-configuration (après le chemin du realm) : document de découverte, issuer, endpoints, algorithmes et capacités.
authorization_endpoint (/protocol/openid-connect/auth) : démarre l’autorisation via le navigateur.
token_endpoint (/protocol/openid-connect/token) : échange un code, ou traite d’autres grants activés.
userinfo_endpoint (/protocol/openid-connect/userinfo) : renvoie des claims de l’utilisateur avec un access token autorisé.
jwks_uri (souvent /protocol/openid-connect/certs) : clés publiques utilisées pour vérifier les signatures des jetons.
Point de terminaison de logout : permet selon la configuration de terminer la session OP.

Exemple de découverte (remplacer demo) :

curl -s http://localhost:8080/realms/demo/.well-known/openid-configuration

ID token, access token et claims¶

ID token : jeton destiné au client OIDC, preuve d’authentification et informations associées. Il ne doit pas être utilisé comme jeton d’accès à une API.
Access token : autorise l’accès à une ressource selon son audience, sa portée et la politique de l’API. Sa forme peut être un JWT dans Keycloak, mais le client doit suivre le contrat du fournisseur.
Refresh token : permet éventuellement d’obtenir de nouveaux jetons ; c’est un secret sensible, à protéger comme un justificatif.
Claims : champs tels que iss (émetteur), sub (sujet), aud (audience), exp (expiration), iat (émission), nonce, name, email ou rôles personnalisés. Tous ne sont pas nécessairement présents.

Le serveur qui valide un JWT doit vérifier la signature avec une clé de confiance et contrôler au minimum l’émetteur (iss), l’audience (aud), l’expiration (exp) et les autres paramètres attendus. Une API accepte normalement un access token destiné à elle-même, pas l’ID token d’une application.

Scopes¶

openid est le scope indispensable pour une demande OIDC. profile, email et address demandent des catégories de claims, si le fournisseur les prend en charge et si l’utilisateur / la politique les autorise. Les scopes sont une demande et non une garantie d’attributs. Keycloak peut ajouter des rôles ou claims via les client scopes et protocol mappers ; voir concepts Keycloak.