Utiliser les jetons et les Organizations

Découvrez comment les jetons fonctionnent avec la fonctionnalité Organizations d’Auth0 et comment authentifier les utilisateurs appartenant à une organisation.

La disponibilité varie selon le plan Auth0

La disponibilité de cette fonctionnalité dépend de votre plan Auth0 ou de votre entente personnalisée. Pour en savoir plus, consultez Tarification.

La plupart des jetons d’identité (ID) et des jetons d’accès renvoyés par Auth0 sont des JSON Web Tokens (JWTs) qui contiennent diverses claims, c’est-à-dire des renseignements déclarés au sujet d’un sujet. Par exemple, un jeton d’ID (qui est toujours un JWT) peut contenir une claim appelée name indiquant que le nom de l’utilisateur qui s’authentifie est “John Doe”.

Il existe deux types de claims JWT :

• Registered : claims définies par la spécification JWT afin d’assurer l’interopérabilité avec des applications tierces, ou externes. Les claims standard OpenID Connect (OIDC) sont des claims réservées.
• Custom : claims que vous définissez vous-même. Ces claims peuvent être des claims publiques non enregistrées et résistantes aux collisions, ou des claims privées non enregistrées et non publiques sujettes aux collisions. Nommez ces claims avec soin, par exemple au moyen de l’espace de noms, afin d’éviter les collisions avec des claims réservées ou d’autres claims personnalisées. Il peut être difficile de gérer deux claims portant le même nom, mais contenant des renseignements différents.

Pour en savoir plus sur les claims, consultez Claims JSON Web Token.

​

Authentifier les utilisateurs par l’intermédiaire d’une organisation

Pour authentifier un utilisateur par l’intermédiaire d’une organisation, vous transmettez un paramètre organization dans une requête vers le point de terminaison /authorize. Les exemples suivants montrent les jetons renvoyés lorsqu’un utilisateur se connecte par l’intermédiaire d’Organizations.

Par défaut, les jetons d’ID et d’accès incluent uniquement les ID d’organisation. Vous pouvez toutefois configurer votre tenant pour permettre l’utilisation des noms d’organisation dans l’API d’authentification. Une fois cette option configurée, les jetons d’ID et d’accès contiennent à la fois les claims org_id et org_name. Pour en savoir plus, consultez Utiliser les noms d’organisation dans l’API d’authentification.

Les applications tierces ne reçoivent pas de jetons d’ID. Les jetons d’accès incluent toujours le claim org_id indiqué ci-dessous. Pour en savoir plus, consultez Contrôles de sécurité pour les applications tierces.

​

jeton d’ID

Dans l’exemple suivant, notez que https://marketplace/roles et https://namespace.exampleco.com/ sont des claims personnalisés ajoutés au jeton, tandis que les autres claims inclus sont standards.

{
  "https://marketplace/roles": [
    "marketplace-administrator"
  ],
  "https://namespace.exampleco.com": "my custom claim",
  "nickname": "firstName.lastName",
  "name": "[e-mail]",
  "picture": "https://s.gravatar.com/avatar/638",
  "updated_at": "2021-03-23T11:34:14.566z",
  "email": "[e-mail]",
  "email_verified": true,
  "sub": "auth0|602c0dcab993d10073daf680",
  "org_id": "org_9ybsU1dN2dKfDkBi"
}

​

Jeton d’accès

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "auth0|602c0dcab993d10073daf680",
  "aud": [
    "https://example-api/",
    "https://exampleco.auth0.com/userinfo"  
  ],
  "iat": 1616499255,
  "exp": 1616585655,
  "azp": "ENDmmAJsbwI1hOG1KPJddQ8LHjV6kLkV",
  "scope": "openid profile email",
  "org_id": "org_9ybsU1dN2dKfDkBi",
  "permissions": [
    "delete:stuff",
    "read:stuff",
    "write:stuff"  
  ]
}

​

Autorisations des rôles d’organisation

Lorsqu’un utilisateur s’authentifie par l’intermédiaire d’une organisation et possède des rôles d’organisation, le jeton d’accès inclut les autorisations associées à ces rôles dans la claim permissions. Les autorisations reflètent uniquement les rôles attribués au sein de l’organisation active pour cette session.

Si aucun contexte d’organisation n’est présent dans la requête d’authentification, les rôles du tenant restent actifs et le comportement du jeton demeure inchangé.

L’exemple suivant montre un jeton d’accès pour un utilisateur qui possède un rôle d’organisation associé aux autorisations read:reports et write:reports au sein de l’organisation active :

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "auth0|602c0dcab993d10073daf680",
  "aud": [
    "https://example-api/",
    "https://exampleco.auth0.com/userinfo"
  ],
  "iat": 1616499255,
  "exp": 1616585655,
  "azp": "ENDmmAJsbwI1hOG1KPJddQ8LHjV6kLkV",
  "scope": "openid profile email",
  "org_id": "org_9ybsU1dN2dKfDkBi",
  "permissions": [
    "read:reports",
    "write:reports"
  ]
}

Pour en savoir plus sur les rôles d’organisation, consultez Organization Roles.

​

Accès machine à machine à une Organisation

Dans les cas d’utilisation machine à machine, vous ajoutez un paramètre organization à la requête Client Credentials envoyée au point de terminaison /oauth/token afin qu’une application puisse obtenir un jeton d’accès pour elle-même plutôt que pour un utilisateur.

Par défaut, les jetons d’ID et d’accès incluent seulement les ID d’organisation. Cependant, vous pouvez configurer votre tenant pour autoriser l’utilisation des noms d’organisation dans l’API d’authentification. Une fois cette option configurée, les jetons d’ID et d’accès contiennent à la fois les claims org_id et org_name. Pour en savoir plus, consultez Utiliser les noms d’organisation dans l’API d’authentification.

L’exemple de code suivant présente un jeton d’accès renvoyé dans les cas d’utilisation machine à machine :

{
  "iss": "https://exampleco.auth0.com/",
  "sub": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP@clients",
  "aud": "https://example-api",
  "iat": 1727782196,
  "exp": 1727868596,
  "scope": "scope1 scope2",
  "org_id": "org_vIK75NKFvaozQsFy",
  "org_name": "acme",
  "gty": "client-credentials",
  "azp": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP"
}

​

Valider les jetons

Lorsque le paramètre organization est ajouté à une requête envoyée au point de terminaison /authorize ou /oauth/token, les Auth0 SDKs valident automatiquement le claim org_id, qui est renvoyé dans tous les jetons générés. Toutefois, pour des raisons de sécurité, vous devez effectuer une validation supplémentaire à la réception des jetons.

Si vous avez configuré votre tenant pour autoriser l’utilisation des noms d’organisation dans l’API d’authentification, les jetons d’ID et d’accès contiennent à la fois les claims org_id et org_name. Le cas échéant, validez le claim org_name en plus de org_id afin de vous assurer que les valeurs reçues correspondent à une entité de confiance.

En règle générale, l’utilisation des ID d’organisation est la méthode privilégiée pour valider les jetons. Toutefois, les noms d’organisation peuvent être utilisés si cela convient mieux à votre cas d’utilisation. Pour comprendre les implications possibles de l’utilisation des noms d’organisation pour valider les jetons, consultez Use Organization Names in API d’authentification.

Pour les applications web :

Si aucun paramètre organization n’a été transmis au point de terminaison /authorize, mais qu’un claim org_id est présent dans le jeton d’ID, votre application doit valider ce claim pour s’assurer que la valeur reçue est attendue ou connue, et qu’elle correspond à une entité à laquelle votre application fait confiance, comme un client payant. Si ce claim ne peut pas être validé, l’application doit considérer le jeton comme invalide.

Pour les API :

Si un claim org_id est présent dans le jeton d’accès, votre API doit valider ce claim pour s’assurer que la valeur reçue est attendue ou connue, et qu’elle correspond à une entité à laquelle votre API fait confiance, comme un client payant. Si ce claim ne peut pas être validé, l’API doit considérer le jeton comme invalide.

En particulier :

• Vérifiez le claim iss (émetteur) pour vous assurer que le jeton a été émis par Auth0.
• Vérifiez le claim org_id pour vous assurer qu’il s’agit d’une valeur déjà connue de l’application. Validez-le au moyen d’une liste connue d’ID d’organisation, ou vérifiez-le conjointement avec l’URL de la requête en cours. Par exemple, le sous-domaine peut indiquer quelle organisation utiliser lors de la validation du jeton d’ID.

Normalement, le fait de valider uniquement l’émetteur suffirait à garantir que le jeton a bien été émis par Auth0. Dans le cas des organisations, toutefois, des vérifications supplémentaires doivent être effectuées pour s’assurer que l’organisation au sein de votre tenant Auth0 est bien celle attendue.

Vos serveurs d’API doivent également segmenter l’accès aux données et aux ressources en fonction de org_id. Cela garantit que seules les informations concernant une organisation donnée peuvent être consultées ou modifiées lorsque la valeur org_id correspondant à cette organisation est reçue dans le jeton d’accès.

​

En savoir plus

• Comprendre le fonctionnement d’Auth0 Organizations
• Créer votre première organisation
• Développement personnalisé avec les Organizations
• Configurer les Organizations