API My Organization et Embeddable UI Components

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

API My Organization et Embeddable UI Components est actuellement offerte en Early Access à tous les clients. En utilisant cette fonctionnalité, vous acceptez les conditions applicables de l’essai gratuit figurant dans le Master Subscription Agreement d’Okta. Pour en savoir plus sur le cycle de publication des produits d’Auth0, consultez Product Release Stages.

Les clients sont responsables de s’assurer que leur utilisation de l’API My Organization et d’Embeddable UI Components est conforme à leurs politiques de sécurité et aux lois applicables, y compris toute permission accordée à leurs utilisateurs finaux.

L’API Auth0 My Organization fournit une interface sécurisée, limitée à une organisation, qui permet à vos clients commerciaux de gérer leurs propres organisations dans votre tenant Auth0. Cette API sert de fondement technique à l’administration déléguée intégrée et aux intégrations API-first.

​

Capacités principales

À l’heure actuelle, l’API permet de gérer les éléments suivants :

• les détails de Auth0 Organization (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 Home Realm Discovery (HRD)

API My Organization vous donne un contrôle technique poussé sur votre intégration. Pour accélérer au maximum le déploiement, nous vous recommandons fortement de commencer par les Embeddable UI Components, les SDK et les applications d’exemple. Les Embeddable UI Components et les applications d’exemple 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 My Organization API

​

Activer API My Organization dans Auth0 Dashboard

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

Une fois API My Organization activée :

• Auth0 désactive l’API par défaut pour toutes les applications client.
• Vous devez accorder l’accès aux applications et aux rôles à l’aide des client grants ou des politiques RBAC.
• Vos clients d’affaires peuvent récupérer les détails de l’organisation ou configurer des IdPs au nom de leurs propres organisations.

​

Paramètres par défaut

Domaine Auth0 ou domaine personnalisé

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

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

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

Politiques d’accès

Par défaut, My Organization API s’active avec les politiques d’accès des applications à l’API suivantes :

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

Pour qu’une application puisse accéder à My Organization API au nom de l’utilisateur, créez un client grant pour cette application afin de définir les scopes maximaux que l’application peut demander. Vous pouvez aussi autoriser n’importe quelle application de votre tenant à demander n’importe quel scope en définissant les flux d’accès utilisateur sur allow_all.

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

Les permissions finales accordées à l’application seront déterminées par l’intersection des scopes autorisés par la politique d’accès des applications à l’API, des permissions RBAC (Role-Based Access Control) 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 politiques d’accès des applications à l’API et des client grants qui y sont associés, consultez Accès des applications aux API : Client Grants.

Durée de vie des jetons

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

My Organization API restera toujours à activation explicite 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, en incluant les scopes que vous souhaitez 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 Connection Profile. ID du Connection Profile utilisé avec l’application lors de l’utilisation de l’API My Organization. S’il n’est pas fourni, les fonctionnalités de l’API My Organization qui nécessitent la présence d’un Connection Profile ne fonctionneront pas. Cet ID doit faire référence à un Connection Profile valide dans le même tenant.
user_attribute_profile_id	ID du User Attribute Profile. ID du User Attribute Profile utilisé avec l’application lors de l’utilisation de l’API My Organization. S’il n’est pas fourni, les fonctionnalités de l’API My Organization qui nécessitent la présence d’un User Attribute Profile ne fonctionneront pas. Cet ID doit faire référence à un User Attribute Profile valide dans le même tenant.
allowed_strategies	Tableau de chaînes de caractères. Chaque chaîne est unique et fait référence à 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 à partir de 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 provenant 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 de API My Organization :

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

2. Sélectionnez l’onglet Application Access.

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

4. Configurez les paramètres suivants :
   A. Facultatif. Configurez le Connection Profile.
   

   1. Sélectionnez un Connection Profile existant ou créez-en un nouveau. Pour un nouveau Connection Profile :
      a. Ajoutez un nom.
      b. Passez en revue les mappages pour vous assurer que les attributs de la connexion reflètent les paramètres souhaités pour les nouvelles connexions.
      

   B. Facultatif. Configurez le User Attribute Profile.
   

   1. Ajoutez un nom.
      
   2. Passez en revue les mappages pour vous assurer que les attributs du profil correspondent aux attributs Auth0 de votre choix.
      

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

   1. Activez un ou plusieurs fournisseurs d’identité. Les administrateurs du client 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 s’il n’y a aucun utilisateur dans la connexion. Si des utilisateurs sont présents, API My Organization renverra une erreur et ne procédera pas à la suppression.
      

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

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

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

   1. Unauthorized. Aucune permission n’est accordée.
      
   2. Authorized. Sélectionnez les permissions souhaitées.
      
   3. All. Inclut toutes les permissions 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 points de terminaison 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 peut uniquement être appelée à l’aide d’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 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 multifactorielle (MFA).

​

Exemple avec le flux de code d’autorisation

Utilisez le flux de code d’autorisation pour les applications Web confidentielles avec 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 clé de preuve pour l’échange de code (PKCE) 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 provenant d’autres API (comme /me ou /api/v2/) ne fonctionneront pas.

​

Scopes

Scope	Description
read:my_org:configuration	Consulter la configuration de l’organisation pour un client
read:my_org:details	Consulter les détails de l’organisation pour un client
update:my_org:details	Mettre à jour les détails de l’organisation pour un client
create:my_org:identity_providers	Créer un fournisseur d’identité pour l’organisation
read:my_org:identity_providers	Consulter 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	Détacher 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	Lister les jetons SCIM de provisionnement pour ce fournisseur d’identité
create:my_org:identity_providers_scim_tokens	Créer un jeton SCIM de provisionnement pour ce fournisseur d’identité
delete:my_org:identity_providers_scim_tokens	Supprimer la configuration d’un jeton SCIM de provisionnement pour un fournisseur d’identité
create:my_org:identity_providers_provisioning	Créer une configuration de provisionnement pour le fournisseur d’identité
read:my_org:identity_providers_provisioning	Consulter la configuration de provisionnement du fournisseur d’identité
update:my_org:identity_providers_provisioning	Mettre à jour la configuration de provisionnement du fournisseur d’identité
delete:my_org:identity_providers_provisioning	Supprimer la configuration de provisionnement du fournisseur d’identité
read:my_org:domains	Consulter 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 la référence complète de ces points de terminaison, y compris les schémas, les codes d’erreur, etc., reportez-vous à notre API Explorer.

​

Référence du SDK

L’API est offerte sous forme de SDK pour TypeScript, Java, .NET, Go et Python. Pour en savoir plus sur chaque implémentation du SDK et consulter des exemples d’utilisation du SDK, reportez-vous à notre documentation du SDK.

​

Profils utilisateur

L’API My Organization utilise les Connection Profiles et les User Attribute Profiles pour définir la structure, les restrictions et les règles des configurations créées par des clients tiers.

​

Connection Profile (CP)

Le Connection Profile 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 Connection Profile, ses mappages d’attributs et ses remplacements, voir des exemples et apprendre à en configurer un, consultez Connection Profiles.

​

User Attribute Profile (UAP)

Le User Attribute Profile (UAP) offre une manière uniforme de définir, de gérer et de mapper les attributs utilisateur à travers des protocoles comme SCIM, SAML et OIDC. Pour en savoir plus sur le fonctionnement du UAP, ses mappages d’attributs et ses overrides, voir des exemples et apprendre à en configurer un, consultez User Attribute Profiles.

​

Limites de débit

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

Niveau	Lecture (RPS)	Écriture (RPS)
Free	4	2
Public Self-Service	8	4
Public Enterprise	40	20
Private Basic	40	20
Private Performance	160	80

​

Limites de débit par organisation

En plus des limites de débit du niveau de service, la My Organization API applique aussi des limites de débit par organisation. Ces limites visent à assurer une répartition équitable des ressources et à empêcher qu’une seule organisation nuise aux performances globales de votre tenant. En appliquant ces limites, nous atténuons l’effet du « voisin bruyant », de sorte qu’une hausse soudaine de l’activité d’une organisation ne monopolise pas les ressources partagées et n’ait pas 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, tant 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 interorigines

Si vous prévoyez effectuer une requête directement à l’API My Organization à partir d’une application navigateur (comme une application monopage) exécutée sur un domaine différent de celui de votre tenant Auth0, vous serez confronté aux politiques de sécurité des navigateurs appelées Cross-Origin Resource Sharing (CORS). Par défaut, les navigateurs bloquent ces requêtes interorigines.

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

1. Accédez à Auth0 Dashboard > Applications. Sélectionnez l’application à afficher.
2. Sous Cross-Origin Authentication, activez la bascule Allow Cross-Origin Authentication.
3. Repérez Allowed Origins (CORS), puis entrez l’URL d’origine de votre application.
4. Sélectionnez Save.

Si vous n’avez pas besoin d’utiliser CORS pour votre application, assurez-vous que la bascule Allow Cross-Origin Authentication est désactivée. En ajoutant l’URL de votre application à cette liste, vous indiquez à Auth0 qu’il peut faire confiance aux requêtes provenant de cette origine, ce qui permet à votre application client-side d’accéder à l’API.

​

Événements de journalisation

Pour faciliter l’audit granulaire et la surveillance, l’API My Organization génère un ensemble précis d’événements de journalisation propres à cette API. Bien que votre tenant 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 pour toutes les ressources gérées par l’API, plus précisément : la configuration, les détails de l’organisation, les IdPs et les domaines. Si vous souhaitez en savoir plus sur les schémas des événements de journalisation, vous pouvez consulter notre dépôt GitHub.

Code d’événement	Événement	Description de l’événement
my_organization_api_config_failed	Configuration de My Organization API Failed	appel d’API ayant échoué vers la ressource de configuration du service My Organization API
my_organization_api_org_details_succeeded	Détails de l’organisation de My Organization API réussis	appel d’API réussi vers la ressource des détails de l’organisation du service My Organization API
my_organization_api_org_details_failed	Détails de l’organisation de My Organization API Failed	appel d’API ayant échoué vers la ressource des détails de l’organisation du service My Organization API
my_organization_api_idp_succeeded	Fournisseur d’identité de My Organization API réussi	appel d’API réussi vers la ressource de fournisseur d’identité du service My Organization API
my_organization_api_idp_failed	Fournisseur d’identité de My Organization API Failed	appel d’API ayant échoué vers la ressource de fournisseur d’identité du service My Organization API
my_organization_api_domain_succeeded	Domaine de My Organization API réussi	appel d’API réussi vers la ressource de domaine du service My Organization API
my_organization_api_domain_failed	Domaine de My Organization API Failed	appel d’API ayant échoué vers la ressource de domaine du service My Organization API

​

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 de tenant et celles autogérées par l’organisation. Cette gestion est contrôlée 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 de tenant. Cette connexion ne peut pas être consultée ni modifiée au moyen de la My Organization API.
readonly	Association attribuée par l’administrateur de tenant. Elle peut être consultée, mais ne peut pas être modifiée au moyen de la My Organization API.
limited	Association attribuée par l’administrateur de tenant. Des renseignements et des modifications limités sont permis au moyen de la My Organization API, plus précisément les attributs show_as_button et is_enabled.
full	Association attribuée par l’administrateur de tenant. Les utilisateurs de la My Organization API 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 supplémentaires du schéma :

Propriété	Description
is_enabled	Boolean. Active ou désactive une connexion pour une organisation. En désactivant la connexion, il sera possible de conserver les valeurs de l’objet de connexion enregistrées 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 la My Organization API : 1. null 2. none - Association attribuée par l’administrateur de tenant. Cette connexion ne peut pas être consultée ni modifiée au moyen de la My Organization API. 3. readonly - Association attribuée par l’administrateur de tenant. Cette connexion peut être consultée, mais ne peut pas être modifiée au moyen de la My Organization API. 4. limited - Association attribuée par l’administrateur de tenant. Des renseignements et des modifications limités sont permis au moyen de la My Organization API. 5. full - Association attribuée par l’administrateur de tenant. Les utilisateurs de la My Organization API pourront modifier la connexion sans restrictions supplémentaires lorsqu’ils utilisent la My Organization API. Remarque : Peu importe organization_access_level, les modifications effectuées par la My Organization API sont toujours soumises aux restrictions appliquées par le Connection Profile.
organization_connection_name	String. Stocke le nom fourni lors de la création de la connexion. Ce champ est calculé par la My Organization API en évaluant le connection_name_prefix_template du Connection Profile. Ce champ est visible et modifiable uniquement au moyen de 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 précisée.
• organization_access_level ne peut être modifié qu’au moyen de la Management API.
• Si l’attribut name n’est pas défini, il doit être renseigné au moyen de la Management API avant de changer organization_access_level de none à toute autre valeur.

​

Auth0 Universal Components

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