Déconnexion OIDC par canal arrière

Décrit la fonctionnalité de déconnexion OIDC par canal arrière d’Auth0.

Auth0 prend en charge la spécification OpenID Connect Back-Channel Logout 1.0 dans tous les locataires dotés d’un abonnement Enterprise.

Cette spécification s’appuie sur l’identifiant de session (sid) inclus dans les jetons d’identité et sur les jetons de déconnexion pour coordonner la fin de session au moyen d’une communication par canal arrière. Des identifiants de session différents représentent des sessions distinctes d’un agent utilisateur ou d’un appareil dans votre locataire. Les jetons de déconnexion identifient l’utilisateur final et la session à déconnecter.

​

Communications en canal arrière

Pour utiliser Back-Channel Logout, une application doit exposer une URI de Back-Channel Logout, accessible depuis le serveur du locataire, à laquelle l’application s’attend à recevoir des requêtes avec le jeton de déconnexion. Lorsqu’une application reçoit cette requête, elle doit effacer l’état de la session locale correspondant aux claims du jeton.

Pour que la déconnexion canal arrière fonctionne, les applications doivent être en mesure de recevoir des communications en canal arrière.

​

Jetons dans les communications de déconnexion OIDC par canal arrière

Les applications ne peuvent pas se fier aux cookies de session pour déterminer quelle session terminer lorsque les communications passent par le canal arrière. Le service s’appuie plutôt sur un identifiant de session partagé (sid) dans les jetons d’identité et de déconnexion.

Lorsque les utilisateurs finaux s’authentifient avec succès auprès d’Auth0 lors de la connexion, le serveur d’autorisation émet des jetons d’accès et d’identité. Des jetons de déconnexion sont générés lorsqu’une session est détruite, par exemple à la suite d’une action de déconnexion ou d’une révocation de session. Les jetons d’identité et de déconnexion contiennent tous deux les claims dont votre application a besoin pour prendre en charge le flux de déconnexion par canal arrière. Pour en savoir plus sur les claims, consultez JSON Web Token Claims.

1. Connexion - Pendant l’authentification de l’utilisateur, le locataire Auth0 ajoute le sid au jeton d’identité.
2. Connexion - L’application stocke l’identifiant de session reçu dans son propre magasin de sessions et l’associe à la session propre à l’application.
3. Déconnexion - L’IdP appelle l’URL de rappel de déconnexion préenregistrée et envoie le jeton de déconnexion à ce point de terminaison. Le jeton contient le user_id (sub) et le sid, ainsi que d’autres paramètres.
4. Déconnexion - Le backend de l’application doit valider le jeton de déconnexion conformément à la spécification OIDC et extraire le sid. Il peut ensuite utiliser ce jeton pour trouver la session associée à cet identifiant et y mettre fin au besoin.

La réponse attendue est HTTP 200 pour une déconnexion réussie. Si vous recevez un HTTP 400, indiquant une requête incorrecte ou mal interprétée, vous pouvez utiliser nos conseils de dépannage. Pour en savoir plus, consultez Configure Back-Channel Logout.

​

Fonctionnement

Cet exemple de cas d’utilisation montre comment la déconnexion par canal arrière fonctionne avec plus d’une application :

1. Pendant la configuration de l’application, l’application A enregistre un URI de déconnexion par canal arrière auprès d’Auth0.

2. Pendant la configuration de l’application, l’application B enregistre un URI de déconnexion par canal arrière auprès d’Auth0.

   Les URL de déconnexion par canal arrière OIDC doivent :

   • Être accessibles depuis l’IdP
   • Utiliser des points de terminaison protégés par le chiffrement TLS
   • Valider les jetons de déconnexion

3. Lors de la connexion de l’utilisateur final, un utilisateur s’authentifie auprès d’Auth0 pour accéder à l’application A.

4. Auth0 envoie un jeton d’identité avec sid à l’application A. Pour en savoir plus, consultez Structure de l’ID Token.

5. L’utilisateur s’authentifie auprès d’Auth0 pour accéder à l’application B.

6. Auth0 envoie un jeton d’identité avec le même sid à l’application B. Votre application doit stocker les informations de session.

7. Lors de la déconnexion, l’application A ou d’autres entités lancent la déconnexion sur le canal frontal.

8. Auth0 met fin à la couche de session d’Auth0 au moyen du témoin de session.

9. Auth0 appelle l’URI de déconnexion par canal arrière de l’application A et envoie le jeton de déconnexion.

10. L’application A valide le jeton de déconnexion et met fin à la session.

11. Auth0 appelle l’URI de déconnexion par canal arrière de l’application B et envoie le jeton de déconnexion.

12. L’application B valide le jeton de déconnexion et met fin à la session.

Les demandes de déconnexion par canal arrière sont placées dans une file d’attente asynchrone et traitées aussi rapidement que possible. En situation de charge élevée, il peut y avoir un léger délai avant l’exécution de la demande de déconnexion; concevez donc vos applications de façon à gérer cette cohérence à terme.

​

Exemple de jeton

Votre application doit pouvoir analyser et valider les JWTs afin de les utiliser comme jetons de déconnexion avec Auth0. Pour en savoir plus, consultez Valider les JSON Web Tokens.

Une fois que votre application a validé et décodé votre jeton, son contenu ressemble à l’exemple ci-dessous :

JSON

{
  "iss": "https://artex-dev.eu.auth0.com/",
  "sub": "auth0|602e93db83fa6f00749a23e6",
  "aud": "TuhNLv7ulXD3RfyLlSMbOvszzwJJFPpO",
  "iat": 1698160928,
  "exp": 1698161048,
  "jti": "44a91215-dfb4-4dfe-a1eb-fcafa911deba",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  },
  "trace_id": "81b336a94a4a5707",
  "sid": "375UIp_ID5mCTClIeBEHpXfGwq51tF_L"
}

​

SDKs Auth0

Un exemple complet ainsi que du code de production sont déjà inclus dans la section Exemple de déconnexion par canal arrière de notre SDK express-openid-connect.

​

Exemples d’implémentation

​

Stockage des sessions

Cet exemple de stockage des sessions est implémenté avec Node.js (Express) et s’appuie sur l’exemple d’application Web Express OpenID Connect.

Dans l’onglet Sessions de votre application, exposez la route que vous avez configurée pour recevoir le jeton de déconnexion. Validez-le et mettez fin à la session de l’utilisateur.

Cet exemple utilise un stockage de sessions en mémoire à des fins de démonstration.

routes/index.js

const express = require('express');
const router = express.Router();
const { requiresAuth } = require('express-openid-connect');

// intergiciel pour valider le jeton de déconnexion
const requiresValidLogoutToken = require('../middlewares/validateLogoutToken');

// fonction utilitaire pour supprimer les sessions utilisateur
const deleteUserSessions = require('../utils/sessions');

// nouvelle route pour recevoir les jetons de déconnexion par canal arrière
// doit être configurée dans l'onglet Application -> Sessions
// dans le tableau de bord de gestion Auth0
router.post(
  '/backchannel-logout',
  requiresValidLogoutToken,
  function (req, res, next) {
    // à ce stade, le jeton de déconnexion est valide, vérifié par l'intergiciel requiresValidLogoutToken
    // vous pouvez y accéder depuis l'objet de requête : req.logoutToken

    // supprimer la session utilisateur pour déconnecter l'utilisateur
    deleteUserSessions(
      req.app.locals.sessionStore,
      req.logoutToken.sub,
      req.logoutToken.sid
    );

    res.sendStatus(200);
  }
);

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Auth0 Webapp sample Nodejs',
    isAuthenticated: req.oidc.isAuthenticated(),
    headline: process.env.APP_NAME,
    backgroundColor: process.env.BACKGROUND_COLOR,
    baseURL: process.env.BASE_URL,
  });
});

router.get('/profile', requiresAuth(), function (req, res, next) {
  res.render('profile', {
    userProfile: JSON.stringify(req.oidc.user, null, 2),
    title: 'Profile page',
    headline: process.env.APP_NAME,
    backgroundColor: process.env.BACKGROUND_COLOR,
    baseURL: process.env.BASE_URL,
  });
});

module.exports = router;

middlewares/validateLogoutToken.js

// Ce middleware valide le jeton de déconnexion tel que défini ici :
// https://openid.net/specs/openid-connect-backchannel-1_0.html#Validation

const jose = require('jose');

async function requiresValidLogoutToken(req, res, next) {

  // récupérer l'ensemble de clés distant pour la vérification du jeton
  const JWKS = jose.createRemoteJWKSet(
    new URL(process.env.ISSUER_BASE_URL + '/.well-known/jwks.json')
  );

  const logoutToken = req.body.logout_token;

  if (!logoutToken) {
    res.status(400).send('Need logout token');
  }

  try {
    const { payload, protectedHeader } = await jose.jwtVerify(
      logoutToken,
      JWKS,
      {
        issuer: process.env.ISSUER_BASE_URL + '/',
        audience: process.env.CLIENT_ID,
        typ: 'JWT',
        maxTokenAge: '2 minutes',
      }
    );

    // Vérifier que le jeton de déconnexion contient une revendication sub, une revendication sid, ou les deux
    if (!payload.sub && !payload.sid) {
      res
        .status(400)
        .send(
          'Error: Logout token must contain either sub claim or sid claim, or both'
        );
    }

    // Vérifier que le jeton de déconnexion contient une revendication events
    // dont la valeur est un objet JSON contenant le nom de membre http://schemas.openid.net/event/backchannel-logout
    if (!payload.events['http://schemas.openid.net/event/backchannel-logout']) {
      res
        .status(400)
        .send(
          'Error: Logout token must contain events claim with correct schema'
        );
    }

    // Vérifier que le jeton de déconnexion ne contient pas de revendication nonce.
    if (payload.nonce) {
      res
        .status(400)
        .send('Error: Logout token must not contain a nonce claim');
    }

    // associer le jeton de déconnexion valide à l'objet de requête
    req.logoutToken = payload;

    // le jeton est valide, appeler le middleware suivant
    next();
  } catch (error) {
    res.status(400).send(`Error:  ${error.message}`);
  }
}

module.exports = requiresValidLogoutToken;

​

Stockage des jetons de déconnexion

Une approche courante pour le stockage des jetons consiste à définir un stockage des jetons de déconnexion comme solution de rechange au modèle de stockage des sessions. Votre ou vos applications conservent une collection de jetons de déconnexion au niveau de la persistance.

Chaque fois que l’application veut vérifier son état d’authentification, elle interroge le stockage des jetons de déconnexion pour déterminer si sa session est toujours active. Le stockage des jetons de déconnexion purge régulièrement les données obsolètes afin de ne conserver que les renseignements nécessaires.

​

Considérations de sécurité

Les jetons de déconnexion par canal arrière sont transmis sur Internet; les points de terminaison de rappel qui les reçoivent doivent donc suivre les pratiques exemplaires afin d’assurer un fonctionnement fiable et sécuritaire. La liste de recommandations ci-dessous n’est pas exhaustive, et vous devez toujours tenir compte du contexte particulier de déploiement et d’exploitation pour l’adapter en conséquence. Dans la liste ci-dessous, les applications qui traitent les jetons de déconnexion par canal arrière sont appelées « applications ».

• Les applications doivent pouvoir stocker l’ID de session (revendication sid) reçu lors de la connexion de l’utilisateur afin de le récupérer plus tard à la réception d’un jeton de déconnexion par canal arrière.
• Les applications doivent vérifier tous les jetons reçus conformément aux pratiques exemplaires de validation des JWT.
• Les applications doivent accepter uniquement les jetons émis par des locataires de confiance. Un acteur malveillant peut tenter d’envoyer des jetons émis par d’autres locataires Auth0; ces tentatives doivent être rejetées.
• Les applications doivent accepter les jetons uniquement s’ils contiennent une valeur sid (ID de session) reconnue par l’application. Les jetons contenant un ID de session invalide (qu’il soit expiré ou non reconnu) doivent être rejetés.
• Les applications doivent exposer les points de terminaison de rappel uniquement au moyen de TLS. Les canaux de communication non chiffrés ne sont pas autorisés.
• Il est recommandé que les applications acceptent uniquement les requêtes provenant de la liste publiée des adresses IP sortantes.
• Il est recommandé que les applications suivent les pratiques exemplaires générales en matière de surveillance, de journalisation et de limitation du débit; toutefois, les détails à ce sujet dépassent la portée du présent document.
• Il est recommandé que les applications suppriment régulièrement les sessions obsolètes ou expirées.
• Toute modification de l’adresse du point de terminaison doit être synchronisée avec la configuration du locataire afin de garantir que les jetons de déconnexion sont toujours transmis à la bonne URL de rappel de déconnexion par canal arrière.