Utiliser des noms d’organisation dans les API Authentication

Par défaut, Authentication API utilise les identifiants d’organisation pour identifier des organisations spécifiques. Si nécessaire, vous pouvez configurer votre locataire pour qu’il utilise également les noms des organisations comme identifiant. Toutefois, avant d’activer cette fonction, il convient de prendre en compte les implications en termes d’utilisation et de sécurité. Pour mieux comprendre l’impact potentiel, consultez la section Considérations et recommandations.

La configuration de votre locataire pour prendre en charge les noms d’organisation dans l’Authentication API donne les résultats suivants :

• Le paramètre organization dans les points de terminaison /authorize et SAML peut accepter à la fois les noms d’organisation et les identifiants.

• Les jetons d’accès et d’ID incluent automatiquement les demandes org_name et org_id.

Vous pouvez activer cette fonctionnalité via votre Auth0 Dashboard (Tableau de bord Auth0) ou Management API :

• Auth0 Dashboard : Sélectionnez Paramètres dans le menu de gauche et choisissez l’onglet Avancé. Dans la section Réglages, activez la bascule Autoriser les noms d’organisation dans Authentication API.

• Management API : Utilisez le point de terminaison PATCH /api/v2/tenants/settings pour définir allow_organization_name_in_authentication_api sur true. Pour plus d’informations, consultez la documentation Management API.

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

1. Appelez le point de terminaison /authorize en indiquant le nom de votre organisation comme paramètre organization :

https://{yourDomain}/authorize?
    response_type=code&
    client_id={yourClientId}&
    redirect_uri={https://yourApp/callback}&
    scope={scope}&
    state={state}&
    organization={yourOrganizationName}

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

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data 'code=yourAuthorizationCode}' \
  --data 'redirect_uri={https://yourApp/callback}'

3. Les jetons décodés renvoyés contiennent à la fois les revendications 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}"
}

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

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

En général, il est recommandé d’utiliser les identifiants des organisations lors de la validation des jetons. Toutefois, si l’utilisation de noms d’organisations est plus appropriée pour votre cas d’utilisation, tenez compte des implications ci-dessous lors de la implémentation de la fonctionnalité.

Tenez compte des incidences potentielles ci-dessous lorsque vous utilisez des noms d’organisations pour demander et valider des jetons :

• Les noms d’organisation peuvent être réutilisés : Les jetons à longue durée de vie n’expirent pas lorsqu’une organisation change de nom, et les revendications org_name de ces jetons conservent leur valeur initiale. Si le nom d’origine est réutilisé par la suite par une autre organisation, ces jetons peuvent donner 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 locataire : Si votre API ne vérifie pas les revendications iss (émetteur) dans les jetons, une organisation portant le même nom dans un autre locataire pourrait générer des jetons qui seraient incorrectement acceptés par votre API.

• Les noms des organisations peuvent être modifiés : Si vous changez le nom d’une organisation, vos applications doivent fournir le nouveau nom de l’organisation dans les demandes à l’Authentication API. Comme les jetons peuvent avoir une longue durée de vie, la demande org_name d’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.

En raison de l’impact possible sur la sécurité et la facilité d’utilisation, il est recommandé d’utiliser des identifiants plutôt que des noms pour valider les jetons lorsque l’on travaille avec des organisations. Si vous choisissez d’utiliser des noms d’organisations, suivez les bonnes pratiques ci-dessous pour une expérience optimale :

• Validez toujours la demande iss pour vous assurer qu’un jeton a été émis par votre locataire Auth0.

• Évitez de réutiliser des noms d’organisations qui existaient déjà dans votre locataire. Afin d’éviter la réutilisation et de garantir que les jetons précédemment émis ne puissent pas être utilisés pour accéder à différentes organisations, il convient de conserver un registre précis et actualisé des noms des organisations historiques.

• Évitez de renommer les organisations une fois qu’elles sont utilisées, sauf en cas d’absolue nécessité. Si vous décidez de renommer une organisation, sachez que les jetons d’accès et d’ID existants ne contiennent pas automatiquement le nouveau nom de l’organisation. Après avoir renommé une organisation, veillez à inviter les utilisateurs à se reconnecter.