My Organization API y componentes de UI integrables

Usa My Organization API para permitir que los administradores de Organización de Auth0 administren sus propios proveedores de identidad y dominios verificados desde dentro de tu aplicación.

My Organization API y los componentes de UI integrables están disponibles actualmente en acceso anticipado para todos los clientes. Al usar esta función, aceptas los términos aplicables de la prueba gratuita del Acuerdo maestro de suscripción de Okta. Para obtener más información sobre el ciclo de lanzamiento de productos de Auth0, consulta Etapas de lanzamiento del producto.

Los clientes son responsables de garantizar que su uso de My Organization API y de los componentes de UI integrables cumpla sus políticas de seguridad y la legislación aplicable, incluidos los permisos concedidos a sus usuarios finales.

La My Organization API de Auth0 proporciona una interfaz segura con ámbito de Organización que permite a tus clientes empresariales administrar sus propias Organizaciones dentro de tu inquilino de Auth0. Esta API es la base técnica de la administración delegada integrada y de las integraciones con un enfoque API-first.

​

Capacidades principales

Actualmente, la API admite la gestión de lo siguiente:

• Detalles de la Organización de Auth0 (nombre, marca, nombre para mostrar)
• Configuración, titularidad y relaciones específicas de la organización
• Proveedores de identidad (IdP) y aprovisionamiento de SCIM
• Configuración de dominios y de Home Realm Discovery (HRD)

La API My Organization permite un control técnico detallado de su integración. Para una implementación más rápida, le recomendamos encarecidamente que empiece con los componentes de UI integrables, los SDK y las aplicaciones de ejemplo. Los componentes de UI integrables y las aplicaciones de ejemplo reducen significativamente el tiempo y el esfuerzo necesarios para ofrecer una experiencia de autoservicio a sus clientes y usuarios finales.

​

Configurar la API My Organization

​

Activar la API My Organization en Auth0 Dashboard

1. Vaya a Auth0 Dashboard > Applications > APIs.
2. Busque el banner de la API My Organization.
3. Seleccione Activate.
   
4. La API aparece en la lista Applications > APIs como My Organization API.

Una vez que active la API My Organization:

• Auth0 deshabilita la API para todas las aplicaciones cliente de forma predeterminada.
• Debe conceder acceso a las aplicaciones y a los roles mediante client grants o políticas de RBAC.
• Sus clientes empresariales pueden consultar los detalles de la Organización o configurar IdP en nombre de sus propias Organizaciones.

​

Configuración predeterminada

Dominio de Auth0 frente a dominio personalizado

La API My Organization admite el uso de su dominio canónico de Auth0 o de su dominio personalizado, pero debe usar el mismo durante todo el proceso, que incluye lo siguiente:

• Solicitar un token de acceso
• Establecer la audiencia o el valor de aud
• Llamar al endpoint de la API My Organization

Para obtener más información sobre cómo usar dominios personalizados en Auth0, consulte Custom Domains.

Políticas de acceso

De forma predeterminada, la API My Organization se activa con las siguientes políticas de acceso a API de la aplicación:

• require_client_grant para flujos de usuario
• deny-all para flujos de máquina a máquina

Para que una aplicación acceda a la API My Organization en nombre del usuario, cree un client grant para esa aplicación a fin de definir los alcances máximos que puede solicitar. Como alternativa, puede permitir que cualquier aplicación de su inquilino solicite cualquier scope cambiando los flujos de acceso de usuario a allow_all.

Auth0 no recomienda usar allow_all para los flujos de acceso de usuario porque la API My Organization expone información y operaciones sensibles. Debe seguir el principio de privilegio mínimo para garantizar que las aplicaciones obtengan acceso únicamente a lo que realmente necesitan, lo que minimiza los posibles riesgos de seguridad.

Los permisos finales otorgados a la aplicación estarán determinados por la intersección entre los alcances permitidos por la política de acceso a API de la aplicación, los permisos de control de acceso basado en roles (RBAC) asignados al usuario final y el consentimiento del usuario otorgado (si corresponde).

Para obtener más información sobre cómo administrar las políticas de acceso a API de la aplicación y sus client grants asociados, consulte Application Access to APIs: Client Grants.

Duración de los tokens

La API My Organization emite tokens de acceso con una duración fija de 600 segundos (10 minutos). Esta corta duración es una medida de seguridad deliberada diseñada para proteger su inquilino y sus recursos.

La API My Organization siempre requerirá habilitación explícita por razones de seguridad. Si deshabilita la API, se eliminará el acceso para todas las aplicaciones conectadas hasta que vuelva a habilitarla.

​

Configurar atributos de la aplicación cliente

Cree una aplicación en Auth0 para usarla con la API My Organization. Una vez creada, vaya a Auth0 Dashboard > Applications > APIs y autorice la API My Organization, incluidos los alcances que quiere que la aplicación use.

La aplicación debe proporcionar el objeto my_organization_configuration; de lo contrario, la API My Organization devolverá un error y rechazará la solicitud. Puede usar las siguientes propiedades con el objeto my_organization_configuration:

Propiedad	Descripción
connection_profile_id	ID del perfil de conexión. ID del Perfil de conexión usado con la aplicación al utilizar la API My Organization. Si no se proporciona, las funciones de la API My Organization que requieren un perfil de conexión no funcionarán. Este ID debe hacer referencia a un perfil de conexión válido en el mismo inquilino.
user_attribute_profile_id	ID del perfil de atributos de usuario. ID del Perfil de atributos de usuario usado con la aplicación al utilizar la API My Organization. Si no se proporciona, las funciones de la API My Organization que requieren un perfil de atributos de usuario no funcionarán. Este ID debe hacer referencia a un perfil de atributos de usuario válido en el mismo inquilino.
allowed_strategies	Array de cadenas. Cada cadena es única y hace referencia a una estrategia compatible. Las estrategias compatibles —los valores de la enumeración— son las siguientes: pingfederate, ad, adfs, waad, google-apps, okta, oidc y samlp.
connection_deletion_behavior	Enum (allow, allow_if_empty). Describe cómo se comporta la API My Organization cuando un usuario final intenta eliminar una conexión mediante la API My Organization desde esta aplicación. Los valores y la descripción de la enumeración son los siguientes: 1. allow: Si el usuario tiene el scope correcto, puede eliminar la conexión, lo que provoca que se eliminen todos los usuarios originados en esa conexión. 2.allow_if_empty: Si el usuario tiene el scope correcto, solo puede eliminar la conexión si no hay usuarios en ella. Si hay usuarios, la API My Organization devolverá un error y no continuará con la eliminación.

​

Configurar los atributos de la aplicación cliente

Auth0 Dashboard

Para configurar los atributos obligatorios de My Organization API:

1. Vaya a Dashboard > Applications > APIs y seleccione My Organization API.

2. Seleccione la pestaña Acceso de la aplicación.

3. Elija la aplicación que quiere configurar y seleccione Editar.

4. Configure los siguientes ajustes:
   A. Opcional. Configure el Perfil de conexión.
   

   1. Seleccione un Perfil de conexión existente o cree uno nuevo. Para un Perfil de conexión nuevo:
      a. Agregue un nombre.
      b. Revise las asignaciones para asegurarse de que los atributos de la conexión reflejen la configuración deseada para las conexiones nuevas.
      

   B. Opcional. Configure el Perfil de atributos de usuario.
   

   1. Agregue un nombre.
      
   2. Revise las asignaciones para asegurarse de que los atributos del perfil se correspondan con los atributos de Auth0 que prefiera.
      

   C. Configure los Proveedores de identidad compatibles.
   

   1. Habilite uno o más proveedores de identidad. Los administradores del cliente pueden seleccionar la opción que prefieran de la lista de proveedores habilitados.
      

   D. Configure el Comportamiento de eliminación de conexiones como Permitir o Permitir si está vacía.
   

   1. Permitir: Si el usuario tiene el scope correcto, puede eliminar la conexión, lo que hará que se eliminen todos los usuarios originados en esa conexión.
      
   2. Permitir si está vacía: Si el usuario tiene el scope correcto, solo puede eliminar la conexión si no hay usuarios en ella. Si hay usuarios, My Organization API devolverá un error y no continuará con la eliminación.
      

   E. Configure la Autorización de acceso de usuario como No autorizado, Autorizado o Todos.
   

   1. No autorizado. No se permite ningún permiso.
      
   2. Autorizado. Seleccione los permisos deseados.
      
   3. Todos. Incluye todos los permisos existentes y futuros.
      

   F. Configure la Autorización de acceso para credenciales de cliente como No autorizado, Autorizado o Todos.
   

   1. No autorizado. No se permite ningún permiso.
      
   2. Autorizado. Seleccione los permisos deseados.
      
   3. Todos. Incluye todos los permisos existentes y futuros.
      

5. Seleccione Guardar.

Management API

Para configurar mediante programación los atributos de la aplicación cliente en lugar de usar Auth0 Dashboard, utilice los endpoints disponibles de Management API. Para usar Management API, debe obtener un token de acceso de Management API.

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

​

Generar un Token de acceso

La API My Organization solo puede invocarse con un token de acceso asociado a un usuario, obtenido mediante uno de los flujos de OAuth 2.0.

Si va a permitir que la API My Organization realice operaciones sensibles, le recomendamos encarecidamente que utilice la autenticación reforzada para aplicar políticas de seguridad adicionales mediante autenticación multifactor (MFA).

​

Ejemplo con el flujo de código de autorización

Utilice el flujo de código de autorización para aplicaciones web confidenciales con un Secreto del cliente.

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/'

Respuesta de ejemplo

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

​

Ejemplo con el flujo de código de autorización con PKCE

Utilice el flujo de código de autorización con Proof Key for Code Exchange (PKCE) en aplicaciones públicas sin un Secreto del cliente, aplicaciones de una sola página, aplicaciones móviles o nativas y herramientas de línea de comandos.

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/'

​

Audiencia

La audiencia y la URL base de la API My Organization son https://{yourDomain}/my-org/. Los tokens deben incluir la audiencia https://YOUR_DOMAIN/my-org/. Los tokens de otras API (como /me o /api/v2/) no funcionarán.

​

Alcances

Alcance	Descripción
read:my_org:configuration	Leer la configuración de la organización de un cliente
read:my_org:details	Leer los detalles de la organización de un cliente
update:my_org:details	Actualizar los detalles de la organización de un cliente
create:my_org:identity_providers	Crear un proveedor de identidad para la organización
read:my_org:identity_providers	Leer los proveedores de identidad de la organización
update:my_org:identity_providers	Actualizar los proveedores de identidad de la organización
delete:my_org:identity_providers	Eliminar los proveedores de identidad de la organización
update:my_org:identity_providers_detach	Desvincular un proveedor de identidad de la organización
create:my_org:identity_providers_domains	Asociar el dominio de la organización a un proveedor de identidad
delete:my_org:identity_providers_domains	Quitar el dominio de la organización de un proveedor de identidad
read:my_org:identity_providers_scim_tokens	Listar los tokens SCIM de aprovisionamiento de este proveedor de identidad
create:my_org:identity_providers_scim_tokens	Crear un token SCIM de aprovisionamiento para este proveedor de identidad
delete:my_org:identity_providers_scim_tokens	Eliminar la configuración de un token SCIM de aprovisionamiento de un proveedor de identidad
create:my_org:identity_providers_provisioning	Crear la configuración de aprovisionamiento para un proveedor de identidad
read:my_org:identity_providers_provisioning	Leer la configuración de aprovisionamiento de un proveedor de identidad
update:my_org:identity_providers_provisioning	Actualizar la configuración de aprovisionamiento de un proveedor de identidad
delete:my_org:identity_providers_provisioning	Eliminar la configuración de aprovisionamiento de un proveedor de identidad
read:my_org:domains	Leer los dominios de la organización
delete:my_org:domains	Eliminar un dominio de la organización
create:my_org:domains	Crear un dominio para la organización
update:my_org:domains	Actualizar un dominio de la organización

​

Referencia de endpoints

La API My Organization admite endpoints para la configuración, los detalles de la Organización, los proveedores de identidad, los dominios, las configuraciones de aprovisionamiento y los tokens de SCIM. Para consultar una guía de referencia completa de los endpoints, incluidos los esquemas, los códigos de error, etc., consulta nuestro API Explorer.

​

Referencia del SDK

La API está disponible en formato SDK para TypeScript, Java, .NET, Go y Python. Para obtener información detallada sobre cada implementación del SDK y ejemplos de cómo usarlo, consulta nuestra documentación del SDK.

​

Perfiles de usuario

La API My Organization utiliza Perfiles de conexión y Perfiles de atributos de usuario para definir la estructura, las restricciones y las reglas de las configuraciones creadas por terceros.

​

Perfil de Conexión (CP)

El Perfil de Conexión permite a los desarrolladores de Auth0 especificar cómo debe configurarse la configuración privada de una conexión de Auth0 cuando la crean terceros. Para obtener más información sobre cómo funciona el Perfil de Conexión, sus asignaciones y sobrescrituras de atributos, ejemplos y cómo configurar uno, consulta Perfiles de Conexión.

​

Perfil de atributos de usuario (UAP)

El Perfil de atributos de usuario (UAP) proporciona una forma coherente de definir, gestionar y asignar atributos de usuario entre protocolos como SCIM, SAML y OIDC. Para obtener más información sobre cómo funciona el UAP, sus asignaciones y sustituciones de atributos, ejemplos y cómo configurarlo, consulte User Attribute Profiles.

​

Límites de velocidad

Los límites de velocidad se aplican según su plan de servicio:

Plan	Lectura (RPS)	Escritura (RPS)
Free	4	2
Public Self-Service	8	4
Public Enterprise	40	20
Private Basic	40	20
Private Performance	160	80

​

Límites de tasa por Organización

Además de los límites de tasa del nivel de servicio, la API My Organization también aplica límites de tasa por Organización. Estos límites están diseñados para garantizar una asignación equitativa de los recursos y evitar que una sola Organización afecte al rendimiento general de tu inquilino. Al aplicar estos límites, mitigamos el efecto del «vecino ruidoso», lo que garantiza que un aumento repentino de la actividad de una Organización no consuma recursos compartidos ni afecte a otra dentro del mismo entorno. A cada Organización se le asigna un número específico de solicitudes por segundo (RPS) tanto para operaciones de lectura como de escritura.

Nivel	Lectura por Organización (RPS)	Escritura por Organización (RPS)
Free	4	2
Public Self-Service	4	2
Public Enterprise	8	4
Private Basic	8	4
Private Performance	16	8

​

Solicitudes de origen cruzado

Si tiene previsto llamar a My Organization API directamente desde una aplicación basada en navegador (como una Single Page Application) que se ejecuta en un dominio distinto del de su inquilino de Auth0, se encontrará con políticas de seguridad del navegador conocidas como Cross-Origin Resource Sharing (CORS). De forma predeterminada, los navegadores bloquean estas solicitudes de origen cruzado.

Para permitir que su aplicación realice correctamente solicitudes a la API, debe agregar el dominio de su aplicación (su «origen») a la configuración de su cliente:

1. Vaya a Auth0 Dashboard > Applications. Seleccione la aplicación para verla.
2. En Cross-Origin Authentication, active Allow Cross-Origin Authentication.
3. Busque Allowed Origins (CORS) e introduzca la URL de origen de su aplicación.
4. Seleccione Save.

Si no necesita usar CORS en su aplicación, asegúrese de que Allow Cross-Origin Authentication esté desactivado. Al agregar la URL de su aplicación a esta lista, le indica a Auth0 que confíe en las solicitudes procedentes de ese origen, lo que permite que su aplicación del lado del cliente acceda a la API.

​

Eventos de registro

Para facilitar una auditoría y supervisión detalladas, la API My Organization genera un conjunto específico de eventos de registro exclusivos de esta API. Aunque su inquilino seguirá emitiendo registros estándar del sistema, la siguiente tabla muestra la lista completa de tipos de eventos activados específicamente por la actividad de la API My Organization.

Estos códigos de evento le permiten rastrear la actividad en todos los recursos administrados por la API, en concreto: configuración, detalles de la Organización, IdP y dominios. Si desea obtener más información sobre los esquemas de eventos de registro, puede consultar nuestro repositorio de GitHub.

Código de evento	Evento	Descripción del evento
my_organization_api_config_failed	Error de configuración de la API My Organization	Llamada a la API fallida al recurso de configuración del servicio de la API My Organization
my_organization_api_org_details_succeeded	Detalles de la organización de la API My Organization correctos	Llamada a la API correcta al recurso de detalles de la Organización del servicio de la API My Organization
my_organization_api_org_details_failed	Error en los detalles de la organización de la API My Organization	Llamada a la API fallida al recurso de detalles de la Organización del servicio de la API My Organization
my_organization_api_idp_succeeded	Proveedor de identidad de la API My Organization correcto	Llamada a la API correcta al recurso de proveedor de identidad del servicio de la API My Organization
my_organization_api_idp_failed	Error del proveedor de identidad de la API My Organization	Llamada a la API fallida al recurso de proveedor de identidad del servicio de la API My Organization
my_organization_api_domain_succeeded	Dominio de la API My Organization correcto	Llamada a la API correcta al recurso de dominio del servicio de la API My Organization
my_organization_api_domain_failed	Error del dominio de la API My Organization	Llamada a la API fallida al recurso de dominio del servicio de la API My Organization

​

Titularidad de las conexiones de la organización

La API introduce un modelo de titularidad para distinguir entre las conexiones administradas por el administrador del inquilino y las autoadministradas por la Organización. Esto se controla mediante la propiedad organization_access_level.

Propiedad clave: organization_access_level

Valor de enumeración	Descripción
none	Asociación asignada por el administrador del inquilino. Esta conexión no se puede ver ni editar mediante la My Organization API.
readonly	Asociación asignada por el administrador del inquilino. Se puede ver, pero no editar, mediante la My Organization API.
limited	Asociación asignada por el administrador del inquilino. Se permiten información y modificaciones limitadas mediante la My Organization API, específicamente en los atributos show_as_button e is_enabled.
full	Asociación asignada por el administrador del inquilino. Los usuarios de la My Organization API podrán modificar atributos de la Conexión específicos de la Organización sin restricciones adicionales, específicamente los atributos show_as_button, is_enabled, options, display_name y domains.

Endpoints de Management API para conexiones:

• 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}

Cuando llame a los endpoints /connections, use los mismos alcances que usaría para los endpoints /enabled_connections:

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

Revise los atributos adicionales del esquema:

Propiedad	Descripción
is_enabled	Booleano. Habilita o deshabilita una conexión para una Organización. Al deshabilitar la conexión, es posible conservar los valores del objeto de la conexión mientras esta permanece deshabilitada.
organization_access_level	Enum (null, none, readonly, limited, full). Determina el tipo de acceso que tendrá un usuario al usar la My Organization API: 1. null 2. none - Asociación asignada por el administrador del inquilino. Esta conexión no se puede ver ni editar mediante la My Organization API. 3. readonly - Asociación asignada por el administrador del inquilino. Esta conexión se puede ver, pero no editar, mediante la My Organization API. 4. limited - Asociación asignada por el administrador del inquilino. Se permiten información y modificaciones limitadas mediante la My Organization API. 5. full - Asociación asignada por el administrador del inquilino. Los usuarios de la My Organization API podrán modificar la Conexión sin restricciones adicionales al usar la My Organization API. Nota: Independientemente de organization_access_level, las modificaciones realizadas mediante la My Organization API siempre están sujetas a las restricciones impuestas por el perfil de la Conexión.
organization_connection_name	Cadena. Almacena el nombre proporcionado al crear la Conexión. La My Organization API calcula este campo al evaluar connection_name_prefix_template del perfil de la Conexión. Este campo solo es visible y modificable mediante la Management API.

Notas:

• Estos endpoints aceptan un parámetro de consulta opcional is_enabled=true/false y, si está presente, solo muestran las conexiones que tienen el valor especificado de is_enabled.
• organization_access_level solo se puede cambiar mediante la Management API.
• Si el atributo name no está establecido, debe completarse mediante la Management API antes de cambiar organization_access_level de none a cualquier otro valor.

​

Auth0 Universal Components

Recomendamos encarecidamente empezar con nuestros componentes de interfaz de usuario integrables, Auth0 Universal Components, en lugar de utilizar una integración centrada en API. Estos recursos deberían reducir significativamente el tiempo de desarrollo y ofrecer rápidamente una experiencia de autoservicio a sus clientes.