Utiliser les noms d’organisation dans l’Authentication API

Configuration, considérations relatives à la sécurité et pratiques exemplaires pour utiliser les noms d’organisation dans l’Authentication API.

Par défaut, l’Authentication API utilise les ID d’organisation pour identifier des organizations précises. Au besoin, vous pouvez configurer votre tenant pour qu’il utilise aussi les noms d’organisation comme identifiant. Cependant, l’activation de cette fonctionnalité a des implications sur le plan de l’ergonomie et de la sécurité dont vous devez tenir compte. Pour mieux comprendre les répercussions possibles, consultez la section considérations et recommandations.

​

Comment ça fonctionne

La configuration de votre tenant pour prendre en charge les noms d’organisation dans l’Authentication API a les effets suivants :

• Le paramètre organization dans les points de terminaison /authorize et SAML peut accepter à la fois les noms d’organisation et les ID.
• Les jetons d’accès et les jetons ID incluent automatiquement les claims org_name et org_id.

• Les Organizations peuvent être configurées avec deux noms : une valeur Name obligatoire qui sert d’identifiant logique unique, et une valeur Display Name facultative, plus conviviale. Le paramètre org_name accepte uniquement la valeur Name obligatoire et ne prend pas en charge les valeurs Display Name.
• Cette fonctionnalité est gérée au niveau du tenant. Elle ne peut pas être activée individuellement pour certaines Organizations.

Vous pouvez activer cette fonctionnalité dans votre Auth0 Dashboard ou au moyen de la Management API :

• Auth0 Dashboard : Sélectionnez Settings dans le menu de gauche, puis choisissez l’onglet Advanced. Dans la section Settings, activez la bascule Allow Organization Names in Authentication API.
• Management API : Utilisez le point de terminaison PATCH /api/v2/tenants/settings pour définir allow_organization_name_in_authentication_api à true. Pour en savoir plus, consultez la documentation de la Management API.

​

Exemple de flux

L’exemple suivant illustre un flux du code d’autorisation qui utilise des noms d’organisation.

1. Effectuez une requête vers le point de terminaison /authorize en indiquant le nom de votre organisation dans le paramètre organization :

2. Après avoir obtenu le code d’autorisation, appelez le point de terminaison POST /oauth/token pour récupérer les jetons d’accès et les jetons ID :

3. Les jetons décodés renvoyés comprennent à la fois les claims org_id et org_name :

{
    "sub": "google-oauth2|10...17",
    "aud": [
        "https://yourApp"
    ],
    "iat": 1686840988,
    "exp": 1686927388,
    "azp": "Suo...qTd",
    "scope": "openid profile",
    "org_id": "{yourOrganizationId}",
    "org_name": "{yourOrganizationName}"
}

​

Considérations et recommandations

Avant d’utiliser des noms d’organisation dans l’Authentication API, il est important de comprendre les principales différences entre les noms d’organisation et les ID.

Contrairement aux ID d’organisation (qui restent statiques), vous pouvez modifier le nom d’une organisation à tout moment après sa création initiale. De plus, vous pouvez réutiliser des noms d’organisation dans un même tenant, à condition qu’un nom donné soit attribué à exactement une organisation à la fois. En pratique, cela signifie que vous pouvez changer le nom de l’une de vos organisations et réutiliser son nom d’origine pour une autre organisation de votre tenant. Les noms d’organisation sont uniques uniquement au sein d’un même tenant; un même nom peut être utilisé pour deux organisations ou plus dans plusieurs tenants.

En général, il est recommandé d’utiliser les ID d’organisation lors de la validation des jetons. Toutefois, si l’utilisation de noms d’organisation convient mieux à votre cas d’utilisation, tenez compte des implications ci-dessous lors de la mise en œuvre de cette fonctionnalité.

​

Considérations relatives à la facilité d’utilisation et à la sécurité

Tenez compte des impacts potentiels ci-dessous lorsque vous utilisez des noms d’organisation pour demander et valider des jetons :

• Les noms d’organisation peuvent être réutilisés : Les jetons de longue durée n’expirent pas lorsqu’une organisation change de nom, et les claims org_name dans ces jetons conservent leur valeur d’origine. Si le nom d’origine est réutilisé plus tard par une autre organisation, ces jetons peuvent accorder aux utilisateurs un accès non autorisé aux données et aux ressources gérées par la nouvelle organisation.
• Les noms d’organisation ne sont uniques qu’au sein d’un même tenant : Si votre API ne vérifie pas les claims iss (issuer) dans les jetons, une organisation portant le même nom dans un autre tenant pourrait générer des jetons qui seraient acceptés à tort par votre API.
• Les noms d’organisation peuvent être modifiés : Si vous modifiez le nom d’une organisation, vos applications doivent fournir le nouveau nom d’organisation dans les requêtes à l’Authentication API. Comme les jetons peuvent être de longue durée, le claim org_name dans un jeton peut ne plus correspondre au nom actuel de l’organisation, ce qui pourrait empêcher les applications d’accorder l’accès à l’organisation appropriée.

​

Pratiques exemplaires recommandées

En raison des répercussions possibles sur la sécurité et la convivialité, il est recommandé d’utiliser des IDs plutôt que des noms pour valider les jetons lorsque vous travaillez avec des organisations. Si vous choisissez d’utiliser des noms d’organisation, suivez les pratiques exemplaires ci-dessous pour une expérience optimale :

• Validez toujours la claim iss pour vous assurer qu’un jeton a été émis par votre tenant Auth0.
• Évitez de réutiliser des noms d’organisation qui ont déjà existé dans votre tenant. Pour éviter leur réutilisation et vous assurer que des jetons émis auparavant ne puissent pas servir à accéder à d’autres organisations, tenez un registre exact et à jour des anciens noms d’organisation.
• Évitez de renommer des organisations une fois qu’elles sont utilisées, sauf en cas de nécessité absolue. Si vous choisissez de renommer une organisation, sachez que les jetons d’accès et les jetons ID existants n’incluent pas automatiquement le nouveau nom de l’organisation. Après avoir renommé une organisation, assurez-vous de demander aux utilisateurs de se connecter de nouveau.