API My Organization et composants d’interface utilisateur intégrables

Utilisez l’API My Organization pour permettre aux administrateurs d’Organisation Auth0 de gérer leurs propres fournisseurs d’identité et domaines vérifiés depuis votre application.

L’API My Organization et les composants d’interface utilisateur intégrables sont actuellement offerts en Accès anticipé à tous les clients. En utilisant cette fonctionnalité, vous acceptez les conditions applicables de l’essai gratuit énoncées dans le Master Subscription Agreement d’Okta. Pour en savoir plus sur le cycle de publication des produits d’Auth0, consultez Étapes de publication des produits.

Il incombe aux clients de s’assurer que leur utilisation de l’API My Organization et des composants d’interface utilisateur intégrables est conforme à leurs politiques de sécurité et aux lois applicables, y compris en ce qui concerne les autorisations accordées à leurs utilisateurs finaux.

L’API My Organization d’Auth0 fournit une interface sécurisée, à portée d’Organisation, qui permet à vos entreprises clientes de gérer leurs propres Organisations dans votre locataire Auth0. Cette API constitue la base technique de l’administration déléguée intégrée et des intégrations API-first.

​

Fonctionnalités principales

À l’heure actuelle, l’API prend en charge la gestion des éléments suivants :

• les détails d’une Organisation Auth0 (nom, image de marque, nom d’affichage)
• la configuration, la propriété et les relations propres à l’organisation
• les fournisseurs d’identité (IdP) et le provisionnement SCIM
• la configuration des domaines et de la détection du domaine d’origine (HRD)

L’API My Organization permet un contrôle technique poussé de votre intégration. Pour accélérer le déploiement, nous vous recommandons vivement de commencer par les composants d’interface utilisateur intégrables, les SDK et les applications exemples. Les composants d’interface utilisateur intégrables et les applications exemples réduisent considérablement le temps et les efforts nécessaires pour offrir une expérience en libre-service à vos clients et à vos utilisateurs finaux.

​

Configurer l’API My Organization

​

Activer l’API My Organization dans Auth0 Dashboard

1. Accédez à Auth0 Dashboard > Applications > APIs.
2. Repérez la bannière My Organization API.
3. Sélectionnez Activate.
   
4. L’API s’affiche dans votre liste Applications > APIs sous le nom My Organization API.

Une fois l’API My Organization activée :

• Auth0 désactive l’API par défaut pour toutes les applications clientes.
• Vous devez accorder l’accès aux applications et aux rôles à l’aide d’autorisations d’application ou de politiques RBAC.
• Vos clients d’entreprise peuvent récupérer les détails de leur organisation ou configurer des fournisseurs d’identité (IdP) au nom de leurs propres organisations.

​

Paramètres par défaut

Domaine Auth0 ou domaine personnalisé

L’API My Organization prend en charge votre domaine Auth0 canonique ou votre domaine personnalisé, mais vous devez utiliser le même domaine pendant tout le processus, ce qui comprend notamment les éléments suivants :

• Demander un jeton d’accès
• Définir la valeur de l’audience ou de aud
• Appeler le point de terminaison de l’API My Organization

Pour en savoir plus sur l’utilisation des domaines personnalisés dans Auth0, consultez Custom Domains.

Stratégies d’accès

Par défaut, l’API My Organization est activée avec les stratégies d’accès à l’API d’application suivantes :

• require_client_grant pour les flux utilisateur
• deny-all pour les flux machine-to-machine

Pour qu’une application puisse accéder à l’API My Organization au nom de l’utilisateur, créez une autorisation d’application pour cette application afin de définir les scopes maximums qu’elle peut demander. Vous pouvez aussi permettre à n’importe quelle application de votre locataire de demander n’importe quel scope en modifiant les flux d’accès utilisateur à allow_all.

Auth0 ne recommande pas d’utiliser allow_all pour les flux d’accès utilisateur, car l’API My Organization expose des informations et des opérations sensibles. Vous devriez suivre le principe du moindre privilège afin de vous assurer que les applications obtiennent uniquement l’accès dont elles ont réellement besoin, tout en réduisant au minimum les risques potentiels pour la sécurité.

Les autorisations finales accordées à l’application seront déterminées par l’intersection des scopes autorisés par la stratégie d’accès à l’API de l’application, des autorisations de Contrôle d’accès basé sur les rôles (RBAC) attribuées à l’utilisateur final et de tout consentement donné par l’utilisateur (le cas échéant).

Pour en savoir plus sur la gestion des stratégies d’accès à l’API d’application et de leurs autorisations d’application associées, consultez Application Access to APIs: Client Grants.

Durée de vie des jetons

L’API My Organization émet des jetons d’accès avec une durée de vie fixe de 600 secondes (10 minutes). Cette courte durée est une mesure de sécurité délibérée conçue pour protéger votre locataire et ses ressources.

L’API My Organization restera toujours facultative pour des raisons de sécurité. La désactivation de l’API supprime l’accès pour toutes les applications connectées jusqu’à sa réactivation.

​

Configurer les attributs de l’application cliente

Créez une application dans Auth0 pour l’utiliser avec l’API My Organization. Une fois l’application créée, accédez à Auth0 Dashboard > Applications > APIs et autorisez l’API My Organization, y compris les scopes que vous voulez accorder à l’application.

Votre application doit fournir l’objet my_organization_configuration, sinon l’API My Organization renverra une erreur et rejettera la requête. Vous pouvez utiliser les propriétés suivantes avec l’objet my_organization_configuration :

Propriété	Description
connection_profile_id	ID du profil de connexion. ID du profil de connexion utilisé avec l’application dans le cadre de l’API My Organization. S’il n’est pas fourni, les fonctionnalités de l’API My Organization qui exigent la présence d’un profil de connexion ne fonctionneront pas. Cet ID doit faire référence à un profil de connexion valide dans le même locataire.
user_attribute_profile_id	ID du profil d’attributs utilisateur. ID du profil d’attributs utilisateur utilisé avec l’application dans le cadre de l’API My Organization. S’il n’est pas fourni, les fonctionnalités de l’API My Organization qui exigent la présence d’un profil d’attributs utilisateur ne fonctionneront pas. Cet ID doit faire référence à un profil d’attributs utilisateur valide dans le même locataire.
allowed_strategies	Tableau de chaînes. Chaque chaîne est unique et renvoie à une stratégie prise en charge. Les stratégies prises en charge — c’est-à-dire les valeurs de l’énumération — sont les suivantes : pingfederate, ad, adfs, waad, google-apps, okta, oidc et samlp.
connection_deletion_behavior	Énumération (allow, allow_if_empty). Décrit le comportement de l’API My Organization lorsqu’un utilisateur final tente de supprimer une connexion au moyen de l’API My Organization depuis cette application. Les valeurs et la description de l’énumération sont les suivantes : 1. allow : Si l’utilisateur possède le scope approprié, il peut supprimer la connexion, ce qui entraîne la suppression de tous les utilisateurs issus de cette connexion. 2.allow_if_empty : Si l’utilisateur possède le scope approprié, il peut supprimer la connexion seulement s’il n’y a aucun utilisateur dans la connexion. Si des utilisateurs sont présents, l’API My Organization renverra une erreur et ne procédera pas à la suppression.

​

Configurer les attributs de l’application cliente

Auth0 Dashboard

Pour configurer les attributs requis pour l’API My Organization :

1. Accédez à Dashboard > Applications > APIs et sélectionnez My Organization API.

2. Sélectionnez l’onglet Application Access.

3. Choisissez l’application que vous voulez configurer, puis sélectionnez Edit.

4. Configurez les paramètres suivants :
   A. Facultatif. Configurez le profil de connexion.
   

   1. Sélectionnez un profil de connexion existant ou créez-en un nouveau. Pour créer un nouveau profil de connexion :
      a. Ajoutez un nom.
      b. Vérifiez les mappages pour vous assurer que les attributs de la connexion correspondent aux paramètres souhaités pour les nouvelles connexions.
      

   B. Facultatif. Configurez le profil d’attributs utilisateur.
   

   1. Ajoutez un nom.
      
   2. Vérifiez les mappages pour vous assurer que les attributs du profil correspondent aux attributs Auth0 souhaités.
      

   C. Configurez les fournisseurs d’identité pris en charge.
   

   1. Activez un ou plusieurs fournisseurs d’identité. Les administrateurs des clients peuvent sélectionner l’option de leur choix dans la liste des fournisseurs activés.
      

   D. Configurez le comportement de suppression de la connexion sur Allow ou Allow if Empty.
   

   1. Allow : si l’utilisateur dispose du scope approprié, il peut supprimer la connexion, ce qui entraîne la suppression de tous les utilisateurs provenant de cette connexion.
      
   2. Allow if Empty : si l’utilisateur dispose du scope approprié, il peut supprimer la connexion seulement si elle ne contient aucun utilisateur. Si des utilisateurs sont présents, l’API My Organization retourne une erreur et ne supprime pas la connexion.
      

   E. Configurez l’autorisation d’accès des utilisateurs sur Unauthorized, Authorized ou All.
   

   1. Unauthorized. Aucune autorisation n’est accordée.
      
   2. Authorized. Sélectionnez les autorisations souhaitées.
      
   3. All. Inclut toutes les autorisations existantes et futures.
      

   F. Configurez l’autorisation d’accès des identifiants client sur Unauthorized, Authorized ou All.
   

   1. Unauthorized. Aucune autorisation n’est accordée.
      
   2. Authorized. Sélectionnez les autorisations souhaitées.
      
   3. All. Inclut toutes les autorisations existantes et futures.
      

5. Sélectionnez Save.

Management API

Pour configurer les attributs de l’application cliente par programmation plutôt qu’au moyen d’Auth0 Dashboard, utilisez les endpoints disponibles de la Management API. Pour utiliser la Management API, vous devez obtenir un jeton d’accès de la Management API.

• GET /api/v2/clients
• POST /api/v2/clients
• GET /api/v2/clients/{id}
• PATCH /api/v2/clients/{id}

​

Générer un Jeton d’accès

L’API My Organization ne peut être appelée qu’avec un jeton d’accès associé à un utilisateur, obtenu au moyen de l’un des flux OAuth 2.0 pris en charge.

Si vous prévoyez d’autoriser l’API My Organization à effectuer des opérations sensibles, nous vous recommandons fortement d’utiliser l’authentification renforcée afin d’appliquer des politiques de sécurité supplémentaires au moyen de l’authentification multifacteur (MFA).

​

Exemple avec le flux de code d’autorisation

Utilisez le flux de code d’autorisation pour des applications Web confidentielles dotées d’un Secret client.

curl --request POST \
--url 'https://YOUR_DOMAIN/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET' \
--data 'code=AUTH_CODE' \
--data 'redirect_uri=https://yourapp/callback' \
--data 'audience=https://YOUR_DOMAIN/my-org/'

Exemple de réponse

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "read:my_org:details update:my_org:identity_providers"
}

​

Exemple avec le flux de code d’autorisation avec PKCE

Utilisez le flux de code d’autorisation avec PKCE (Proof Key for Code Exchange) pour les applications publiques sans Secret client, les applications monopages, les applications mobiles ou natives et les outils CLI.

curl --request POST \
--url 'https://YOUR_DOMAIN/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'code=AUTH_CODE' \
--data 'code_verifier=CODE_VERIFIER' \
--data 'redirect_uri=https://yourapp/callback' \
--data 'audience=https://YOUR_DOMAIN/my-org/'

​

Audience

L’audience et l’URL de base de l’API My Organization sont https://{yourDomain}/my-org/. Les jetons doivent inclure l’audience https://YOUR_DOMAIN/my-org/. Les jetons émis pour d’autres API (comme /me ou /api/v2/) ne fonctionneront pas.

​

Scopes

Scope	Description
read:my_org:configuration	Lire la configuration de l’organisation associée à une application
read:my_org:details	Lire les détails de l’organisation associés à une application
update:my_org:details	Mettre à jour les détails de l’organisation associés à une application
create:my_org:identity_providers	Créer un fournisseur d’identité pour l’organisation
read:my_org:identity_providers	Lire les fournisseurs d’identité de l’organisation
update:my_org:identity_providers	Mettre à jour les fournisseurs d’identité de l’organisation
delete:my_org:identity_providers	Supprimer les fournisseurs d’identité de l’organisation
update:my_org:identity_providers_detach	Dissocier le fournisseur d’identité de l’organisation
create:my_org:identity_providers_domains	Associer le domaine de l’organisation au fournisseur d’identité
delete:my_org:identity_providers_domains	Retirer le domaine de l’organisation du fournisseur d’identité
read:my_org:identity_providers_scim_tokens	Répertorier les jetons SCIM de Provisioning pour ce fournisseur d’identité
create:my_org:identity_providers_scim_tokens	Créer un jeton SCIM de Provisioning pour ce fournisseur d’identité
delete:my_org:identity_providers_scim_tokens	Supprimer une configuration de jeton SCIM de Provisioning pour un fournisseur d’identité
create:my_org:identity_providers_provisioning	Créer une configuration de Provisioning pour le fournisseur d’identité
read:my_org:identity_providers_provisioning	Lire la configuration de Provisioning pour le fournisseur d’identité
update:my_org:identity_providers_provisioning	Mettre à jour la configuration de Provisioning pour le fournisseur d’identité
delete:my_org:identity_providers_provisioning	Supprimer la configuration de Provisioning pour le fournisseur d’identité
read:my_org:domains	Lire les domaines de l’organisation
delete:my_org:domains	Supprimer le domaine de l’organisation
create:my_org:domains	Créer un domaine pour l’organisation
update:my_org:domains	Mettre à jour le domaine de l’organisation

​

Référence des points de terminaison

L’API My Organization prend en charge des points de terminaison pour la configuration, les détails de l’organisation, les fournisseurs d’identité, les domaines, les configurations de provisionnement et les jetons SCIM. Pour consulter un guide de référence complet sur les points de terminaison, y compris les schémas, les codes d’erreur, etc., consultez notre API Explorer.

​

Référence des SDK

L’API est offerte sous forme de SDK pour TypeScript, Java, .NET, Go et Python. Pour en savoir plus sur l’implémentation de chaque SDK et voir des exemples d’utilisation, consultez notre documentation des SDK.

​

Profils utilisateur

L’API My Organization utilise les profils de connexion et les profils d’attributs utilisateur pour définir la structure, les restrictions et les règles des configurations créées par des tiers.

​

Profil de connexion (CP)

Le profil de connexion permet aux développeurs Auth0 de préciser comment les paramètres privés d’une connexion Auth0 doivent être configurés lorsqu’elle est créée par des tiers. Pour en savoir plus sur le fonctionnement du profil de connexion, ses correspondances d’attributs et ses remplacements personnalisés, voir des exemples et apprendre à en configurer un, consultez Profils de connexion.

​

Profil d’attributs utilisateur (UAP)

Le profil d’attributs utilisateur (UAP) fournit une façon cohérente de définir, de gérer et de mapper les attributs utilisateur dans des protocoles comme SCIM, SAML et OIDC. Pour en savoir plus sur le fonctionnement de l’UAP, ses mappages d’attributs et ses remplacements, voir des exemples et apprendre à en configurer un, consultez Profils d’attributs utilisateur.

​

Limites de débit

Les limites de débit s’appliquent selon votre niveau de service :

Niveau de service	Lecture (RPS)	Écriture (RPS)
Gratuit	4	2
Libre-service public	8	4
Entreprise publique	40	20
Privé de base	40	20
Privé performance	160	80

​

Limites de débit par organisation

En plus des limites de débit du niveau de service, l’API My Organization applique aussi des limites de débit par organisation. Ces limites visent à assurer une répartition équitable des ressources et à éviter qu’une seule organisation nuise aux performances globales de votre locataire. En imposant ces seuils, nous atténuons l’effet de « voisin bruyant », afin qu’une hausse soudaine d’activité dans une organisation ne monopolise pas les ressources partagées ni n’ait d’incidence sur une autre au sein du même environnement. Un nombre précis de requêtes par seconde (RPS) est attribué à chaque organisation, autant pour les opérations de lecture que d’écriture.

Niveau	Lecture par organisation (RPS)	Écriture par organisation (RPS)
Free	4	2
Public Self-Service	4	2
Public Enterprise	8	4
Private Basic	8	4
Private Performance	16	8

​

Requêtes inter-origine

Si vous comptez appeler directement l’API My Organization depuis une application web exécutée dans le navigateur (comme une application monopage) sur un domaine différent de celui de votre locataire Auth0, vous vous heurterez aux politiques de sécurité du navigateur appelées Cross-Origin Resource Sharing (CORS). Par défaut, les navigateurs bloquent ces requêtes inter-origine.

Pour permettre à votre application d’envoyer des requêtes à l’API, vous devez ajouter le domaine de votre application (son « origine ») à la configuration de votre application :

1. Accédez à Auth0 Dashboard > Applications. Sélectionnez l’application à consulter.
2. Sous Authentification inter-origine, activez l’option Autoriser l’authentification inter-origine.
3. Repérez Origines autorisées (CORS), puis saisissez l’URL d’origine de votre application.
4. Sélectionnez Enregistrer.

Si vous n’avez pas besoin d’utiliser CORS pour votre application, assurez-vous que l’option Autoriser l’authentification inter-origine est désactivée. En ajoutant l’URL de votre application à cette liste, vous indiquez à Auth0 de faire confiance aux requêtes provenant de cette origine, ce qui permet à votre application côté client d’accéder à l’API.

​

Événements du journal

Pour faciliter l’audit et la surveillance granulaires, l’API My Organization génère un ensemble précis d’événements du journal propres à cette API. Bien que votre locataire continue d’émettre les journaux système standard, le tableau ci-dessous présente la liste complète des types d’événements déclenchés spécifiquement par l’activité de l’API My Organization.

Ces codes d’événement vous permettent de suivre les activités sur toutes les ressources gérées par l’API, plus précisément : la configuration, les détails de l’Organisation, les IdP et les domaines. Si vous souhaitez en savoir plus sur les schémas des événements du journal, vous pouvez consulter notre dépôt GitHub.

Code d’événement	Événement	Description de l’événement
my_organization_api_config_failed	Échec de la configuration de l’API My Organization	Échec d’un appel d’API vers la ressource de configuration du service API My Organization
my_organization_api_org_details_succeeded	Succès des détails de l’organisation de l’API My Organization	Appel d’API réussi vers la ressource de détails de l’Organisation du service API My Organization
my_organization_api_org_details_failed	Échec des détails de l’organisation de l’API My Organization	Échec d’un appel d’API vers la ressource de détails de l’Organisation du service API My Organization
my_organization_api_idp_succeeded	Succès du fournisseur d’identité de l’API My Organization	Appel d’API réussi vers la ressource de fournisseur d’identité du service API My Organization
my_organization_api_idp_failed	Échec du fournisseur d’identité de l’API My Organization	Échec d’un appel d’API vers la ressource de fournisseur d’identité du service API My Organization
my_organization_api_domain_succeeded	Succès du domaine de l’API My Organization	Appel d’API réussi vers la ressource de domaine du service API My Organization
my_organization_api_domain_failed	Échec du domaine de l’API My Organization	Échec d’un appel d’API vers la ressource de domaine du service API My Organization

​

Propriété des connexions d’organisation

L’API introduit un modèle de propriété pour distinguer les connexions gérées par l’Administrateur du locataire de celles autogérées par l’Organisation. Ce comportement est contrôlé par la propriété organization_access_level.

Propriété clé : organization_access_level

Valeur d’énumération	Description
none	Association attribuée par l’Administrateur du locataire. Cette connexion ne peut être ni consultée ni modifiée via l’API My Organization.
readonly	Association attribuée par l’Administrateur du locataire. Elle peut être consultée, mais ne peut pas être modifiée via l’API My Organization.
limited	Association attribuée par l’Administrateur du locataire. Des renseignements et des modifications limités sont permis via l’API My Organization, plus précisément pour les attributs show_as_button et is_enabled.
full	Association attribuée par l’Administrateur du locataire. Les utilisateurs de l’API My Organization pourront modifier les attributs de Connexion propres à l’Organisation sans restrictions supplémentaires, plus précisément les attributs show_as_button, is_enabled, options, display_name et domains.

Points de terminaison de la Management API pour les connexions :

• GET /api/v2/organizations/{id}/connections
• POST /api/v2/organizations/{id}/connections
• PATCH /api/v2/organizations/{id}/connections/{id}
• DELETE /api/v2/organizations/{id}/connections/{id}

Lorsque vous appelez les points de terminaison /connections, utilisez les mêmes scopes que pour les points de terminaison /enabled_connections :

• create:organization_connections
• read:organization_connections
• delete:organization_connections
• update:organization_connections

Examinez les attributs de schéma supplémentaires :

Propriété	Description
is_enabled	Boolean. Active ou désactive une connexion pour une Organisation. En désactivant la connexion, il reste possible de conserver les valeurs de l’objet de connexion de façon persistante tout en gardant la connexion désactivée.
organization_access_level	Énumération (null, none, readonly, limited, full). Détermine le type d’accès qu’un utilisateur aura lorsqu’il utilise l’API My Organization : 1. null 2. none - Association attribuée par l’Administrateur du locataire. Cette connexion ne peut être ni consultée ni modifiée via l’API My Organization. 3. readonly - Association attribuée par l’Administrateur du locataire. Cette connexion peut être consultée, mais ne peut pas être modifiée via l’API My Organization. 4. limited - Association attribuée par l’Administrateur du locataire. Des renseignements et des modifications limités sont permis via l’API My Organization. 5. full - Association attribuée par l’Administrateur du locataire. Les utilisateurs de l’API My Organization pourront modifier la Connexion sans restrictions supplémentaires lorsqu’ils utilisent l’API My Organization. Remarque : indépendamment de organization_access_level, les modifications effectuées via l’API My Organization demeurent toujours assujetties aux restrictions appliquées par le profil de connexion.
organization_connection_name	String. Stocke le nom fourni lors de la création de la Connexion. Ce champ est calculé par l’API My Organization en évaluant connection_name_prefix_template du profil de connexion. Ce champ est visible et modifiable uniquement via la Management API.

Remarques :

• Ces points de terminaison acceptent un paramètre de requête facultatif is_enabled=true/false et, s’il est présent, n’affichent que les connexions ayant la valeur is_enabled spécifiée.
• organization_access_level peut seulement être modifié via la Management API.
• Si l’attribut name n’est pas défini, il doit être renseigné via la Management API avant de changer organization_access_level de none à toute autre valeur.

​

Auth0 Universal Components

Nous vous recommandons fortement de commencer avec nos composants d’interface utilisateur intégrables, Auth0 Universal Components, plutôt que d’opter pour une intégration de type API-first. Ces ressources devraient réduire considérablement votre temps de développement et vous permettre d’offrir rapidement une expérience en libre-service à vos clients.