Le raccordement des applications

Raccorder une application, c’est choisir un protocole, un type de client, un flux, une façon d’authentifier le client et une stratégie de déconnexion. Ces choix se répètent pour chaque application du périmètre : ils méritent une grille plutôt qu’une décision au cas par cas. Ce cours couvre OIDC, SAML, la déconnexion et le cas des applications qui ne parlent aucun des deux. Les flux OAuth 2.0 et les échanges SAML eux-mêmes sont supposés connus (voir les fondations).

Client public ou confidentiel

Dans Keycloak, un client OIDC est confidentiel quand l’option « Client authentication » est activée : il doit s’authentifier pour obtenir des jetons. Il est public quand elle est désactivée : application monopage, application mobile ou native, qui ne peut pas garder de secret.

Les flux s’activent case par case dans « Capability config » :

Désactivez tout ce qui ne sert pas. Les valeurs par défaut diffèrent selon que le client est créé dans la console ou par l’API : vérifiez-les plutôt que de les supposer. Les client policies (executors reject-ropc-grant, reject-implicit-grant) permettent de les interdire pour tout un realm.

Code d’autorisation avec PKCE

PKCE lie la demande d’autorisation à l’échange du code : le client envoie code_challenge (empreinte SHA-256 d’un secret aléatoire), puis présente ce secret (code_verifier) au token endpoint. Un code intercepté devient inutilisable.

Keycloak accepte PKCE dès que le client l’envoie. Pour l’exiger, réglez « PKCE Method » à S256 dans les paramètres avancés du client, ou appliquez l’executor pkce-enforcer par client policy. Sans code_challenge, Keycloak renvoie alors l’erreur suivante vers la redirect URI :

http://localhost:3000/callback?error=invalid_request&error_description=Missing+parameter%3A+code_challenge_method

RFC 9700 recommande PKCE pour tous les clients, confidentiels compris. Ajoutez aux exigences du guide d’intégration : redirect URIs exactes (pas de joker en production), state ou PKCE contre le CSRF, nonce pour le jeton d’identité.

kcadm.sh create clients -r agents -s clientId=portail-usagers -s publicClient=true \
  -s 'redirectUris=["https://portail.example.org/callback"]' \
  -s 'webOrigins=["https://portail.example.org"]' \
  -s 'attributes."pkce.code.challenge.method"=S256' \
  -s directAccessGrantsEnabled=false

Client credentials

Le flux client credentials sert quand une application agit en son nom propre. Keycloak crée pour le client un service account, un utilisateur technique nommé service-account-<clientId>. On attribue des rôles à ce compte comme à un utilisateur (onglet « Service accounts roles »), et ils apparaissent dans le jeton :

{
  "iss": "http://localhost:8080/realms/lab-apps",
  "aud": "account",
  "sub": "c9095298-80f4-4df7-9a39-dfaf5813ef5a",
  "azp": "batch-export",
  "realm_access": { "roles": ["offline_access", "uma_authorization", "default-roles-lab-apps"] },
  "scope": "email profile",
  "preferred_username": "service-account-batch-export",
  "client_id": "batch-export",
  "clientHost": "10.20.8.1",
  "clientAddress": "10.20.8.1"
}

Par défaut, Keycloak ne délivre pas de refresh token dans ce flux : le client redemande un jeton à expiration. Retirez les rôles par défaut inutiles du service account et appliquez le moindre privilège, surtout s’il appelle l’Admin REST API (sujet traité dans le cours sur l’API d’administration).

Authentifier le client

Un client confidentiel prouve son identité au token endpoint. Keycloak propose quatre client authenticators (onglet Credentials, champ « Client Authenticator ») :

RFC 9700 privilégie les méthodes asymétriques (private_key_jwt, mTLS). Le choix dépend surtout de ce que l’équipe applicative sait opérer :

# Signed Jwt avec clé publique publiée par l'application
kcadm.sh update clients/$ID -r agents -s clientAuthenticatorType=client-jwt \
  -s 'attributes."use.jwks.url"=true' \
  -s 'attributes."jwks.url"=https://batch.example.org/.well-known/jwks.json'

# X509 : Keycloak vérifie le DN du certificat présenté
kcadm.sh update clients/$ID -r agents -s clientAuthenticatorType=client-x509 \
  -s 'attributes."x509.subjectdn"=CN=batch-export,OU=Applications,O=Exemple'

SAML : métadonnées, signature, NameID, mappers

Pour SAML, Keycloak est l’IdP. Le client SAML a pour identifiant l’entityID du fournisseur de services (SP).

Métadonnées. Le SP récupère les métadonnées de l’IdP à l’adresse /realms/<realm>/protocol/saml/descriptor : entityID, certificat de signature, endpoints SSO et SLO. Dans l’autre sens, la console importe le fichier de métadonnées du SP (Clients, « Import client ») et en déduit l’ACS, les URLs de logout et le certificat.

Signature et chiffrement. Les options principales du client :

• « Sign documents » signe la réponse SAML entière ; « Sign assertions » signe l’assertion. Activer les deux est fréquent ; certains SP n’acceptent que l’un des deux, à tester.
• « Signature algorithm » : RSA_SHA256 au minimum.
• « Client signature required » : Keycloak exige que les requêtes du SP soient signées et vérifie la signature avec le certificat du SP (onglet Keys).
• « Encrypt assertions » : l’assertion est chiffrée avec la clé publique du SP. Utile si l’assertion transite par des composants non maîtrisés ; sinon le TLS suffit souvent.

NameID. Le champ « Name ID format » propose username, email, transient et persistent. « Force name ID format » ignore le format demandé par le SP. Préférez persistent pour un identifiant stable et opaque ; email est pratique mais change quand l’adresse change, ce qui casse le rattachement au compte applicatif.

Mappers. Les attributs de l’assertion sont produits par des mappers SAML : User Property (email, firstName), User Attribute, Role list, Group list, Hardcoded attribute. Chacun fixe le nom de l’attribut et son « Name format » (Basic, URI Reference, Unspecified). Le SP impose souvent des noms précis (mail, ou un OID urn:oid:0.9.2342.19200300.100.1.3) : relevez-les dans la fiche de l’application.

<saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue>alice@academy.local</saml:AttributeValue>
</saml:Attribute>

La déconnexion : ce qui marche réellement

La déconnexion est le point où les promesses des éditeurs et la réalité divergent le plus. Il faut distinguer deux questions : l’application sait-elle demander une déconnexion, et sait-elle recevoir une déconnexion déclenchée ailleurs ?

Demander. En OIDC, l’application redirige vers l’end_session_endpoint avec id_token_hint (ou client_id) et post_logout_redirect_uri, qui doit être déclarée dans le client (« Valid post logout redirect URIs »). Keycloak ferme la session SSO puis notifie les autres clients.

Recevoir. Keycloak notifie chaque client de la session selon sa configuration :

• Front channel logout activé : Keycloak affiche une page qui charge en iframe la « Front-channel logout URL » de chaque client. Simple, mais dépend du navigateur : le blocage des cookies tiers empêche souvent l’application de retrouver sa session dans l’iframe.
• Front channel logout désactivé et « Backchannel logout URL » renseignée : Keycloak envoie un logout_token (JWT signé) de serveur à serveur. Fiable, mais l’application doit être joignable par Keycloak et savoir retrouver sa session locale à partir du sid (« Backchannel logout session required ») ou du sub.

Selon la façon dont le client est créé (console ou API), la valeur par défaut de « Front channel logout » diffère : dans le lab, un client créé par kcadm.sh l’a désactivée. Fixez-la explicitement.

En SAML, le SLO passe par les URLs « Logout Service » du client, en binding Redirect ou POST (par le navigateur) ou SOAP (de serveur à serveur), selon ce que le SP déclare dans ses métadonnées.

Pour chaque application, la fiche doit dire ce qui se passe quand l’utilisateur se déconnecte ailleurs. « Rien jusqu’à expiration de la session locale » est une réponse acceptable si elle est connue et que la durée est courte.

Applications sans OIDC ni SAML : le reverse proxy

Une application qui ne sait lire qu’un utilisateur dans un en-tête HTTP (REMOTE_USER, X-Forwarded-User) peut être placée derrière un reverse proxy qui fait le travail OIDC. Pour Keycloak, le proxy est un client confidentiel ordinaire.

Avec mod_auth_openidc (module Apache) :

OIDCProviderMetadataURL https://sso.example.org/realms/agents/.well-known/openid-configuration
OIDCClientID appli-legacy
OIDCClientSecret "exec:/usr/local/bin/lire-secret appli-legacy"
OIDCRedirectURI https://appli.example.org/redirect_uri
OIDCCryptoPassphrase "exec:/usr/local/bin/lire-secret passphrase"
OIDCPKCEMethod S256
OIDCRemoteUserClaim preferred_username
OIDCPassClaimsAs headers

<Location />
  AuthType openid-connect
  Require claim roles:utilisateur
</Location>

Ici, un mapper « User Client Role » du client appli-legacy écrit ses rôles dans un claim plat roles, plus simple à tester qu’un chemin imbriqué. D’après sa documentation, mod_auth_openidc accepte aussi le back-channel logout sur son redirect URI (https://appli.example.org/redirect_uri?logout=backchannel), à renseigner comme « Backchannel logout URL » du client.

Avec oauth2-proxy (provider keycloak-oidc) :

oauth2-proxy \
  --provider=keycloak-oidc \
  --oidc-issuer-url=https://sso.example.org/realms/agents \
  --client-id=appli-legacy --client-secret-file=/run/secrets/appli-legacy \
  --redirect-url=https://appli.example.org/oauth2/callback \
  --code-challenge-method=S256 \
  --allowed-role=appli-legacy:utilisateur \
  --email-domain='*' \
  --upstream=http://127.0.0.1:8081

oauth2-proxy vérifie que son client-id figure dans aud : ajoutez un mapper Audience au client (voir le cours sur les jetons).

Les limites du modèle, à écrire noir sur blanc dans le guide d’intégration :

• Confiance dans l’en-tête. L’application croit tout en-tête reçu. Elle ne doit être joignable que par le proxy (réseau, pare-feu, écoute sur 127.0.0.1), et le proxy doit écraser les en-têtes entrants du même nom.
• Autorisation grossière. Le proxy filtre l’accès ; les droits fins restent dans l’application, souvent dans sa propre base de comptes, qu’il faut alors provisionner.
• Déconnexion. Le proxy ferme sa propre session ; si l’application garde une session à elle, elle ne le sait pas.
• API et clients lourds. Un client non navigateur (client lourd, script) ne suit pas les redirections OIDC.

Grille de catégorisation

KC="docker compose exec -T keycloak /opt/keycloak/bin/kcadm.sh"
$KC config credentials --server http://localhost:8080 --realm master --user admin --password admin
$KC create realms -s realm=lab-apps -s enabled=true
$KC create users -r lab-apps -s username=alice -s enabled=true -s email=alice@academy.local \
  -s firstName=Alice -s lastName=Martin -s emailVerified=true
$KC set-password -r lab-apps --username alice --new-password password

$KC create clients -r lab-apps -s clientId=spa-demo -s publicClient=true \
  -s 'redirectUris=["http://localhost:3000/callback"]' -s 'webOrigins=["http://localhost:3000"]' \
  -s 'attributes."pkce.code.challenge.method"=S256'

http://localhost:8080/realms/lab-apps/protocol/openid-connect/auth?client_id=spa-demo&response_type=code&scope=openid&redirect_uri=http://localhost:3000/callback

VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
echo "http://localhost:8080/realms/lab-apps/protocol/openid-connect/auth?client_id=spa-demo&response_type=code&scope=openid&redirect_uri=http://localhost:3000/callback&state=xyz&code_challenge=$CHALLENGE&code_challenge_method=S256"

curl -s http://localhost:8080/realms/lab-apps/protocol/openid-connect/token \
  -d grant_type=authorization_code -d client_id=spa-demo -d redirect_uri=http://localhost:3000/callback \
  -d code_verifier=$VERIFIER -d code=<code copié> | python3 -m json.tool

$KC create clients -r lab-apps -s clientId=batch-export -s secret=batch-secret \
  -s standardFlowEnabled=false -s directAccessGrantsEnabled=false -s serviceAccountsEnabled=true
curl -s http://localhost:8080/realms/lab-apps/protocol/openid-connect/token \
  -u batch-export:batch-secret -d grant_type=client_credentials | python3 -m json.tool

$KC create clients -r lab-apps -s clientId=https://sp.academy.local/saml -s protocol=saml \
  -s 'redirectUris=["https://sp.academy.local/*"]' \
  -s 'attributes."saml_assertion_consumer_url_post"=https://sp.academy.local/saml/acs' \
  -s 'attributes."saml_name_id_format"=email' -s 'attributes."saml.force.name.id.format"=true'
SP=$($KC get clients -r lab-apps -q clientId=https://sp.academy.local/saml --fields id --format csv --noquotes)
$KC create clients/$SP/protocol-mappers/models -r lab-apps -s name=mail -s protocol=saml \
  -s protocolMapper=saml-user-property-mapper -s 'config."user.attribute"=email' \
  -s 'config."attribute.name"=mail' -s 'config."attribute.nameformat"=Basic'
curl -s http://localhost:8080/realms/lab-apps/protocol/saml/descriptor

À retenir

• Client public + code + PKCE pour tout ce qui a un utilisateur ; client credentials pour le machine à machine ; ni implicit ni grant password.
• Préférez une authentification de client asymétrique (Signed Jwt) quand l’équipe sait l’opérer ; le mTLS est aussi un sujet d’architecture réseau.
• En SAML, relevez dans la fiche : entityID, ACS, signature attendue, format du NameID, noms d’attributs.
• La déconnexion se teste application par application : back-channel quand c’est possible, sessions locales courtes sinon.
• Le reverse proxy raccorde ce qui ne parle aucun protocole, à condition que l’application ne soit joignable que par lui.