Referencia de la API My Organization

Versión: 1.0 (Actual)

Acceso anticipado

API My Organization y los componentes de interfaz de usuario integrables están disponibles actualmente en Acceso anticipado para todos los clientes. Al usar esta funcionalidad, acepta los términos aplicables de la prueba gratuita del Master Subscription Agreement de Okta. Para obtener más información sobre el ciclo de lanzamiento de productos de Auth0, consulte Fases de lanzamiento del producto. El Cliente es responsable de garantizar que el uso que haga de API My Organization y de los componentes de interfaz de usuario integrables cumpla con sus políticas de seguridad y la legislación aplicable, incluidos los permisos concedidos a sus usuarios finales.

La API My Organization de Auth0 proporciona una interfaz segura delimitada por organización que permite a sus clientes empresariales administrar sus propias Organizaciones dentro de su inquilino de Auth0. Esta API sirve como base técnica para la administración delegada integrada y las integraciones con enfoque API-first. La documentación de API My Organization se ajusta al esquema OpenAPI v3.1 de API My Organization. Tenga en cuenta que la compatibilidad con el esquema OpenAPI v3.1 se encuentra actualmente en Beta.

Uso del dominio de Auth0 frente a un dominio personalizado

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, lo que incluye:

Obtener un token de acceso
Establecer el valor de audience
Llamar al endpoint de API My Organization

Para obtener más información, consulte Dominios personalizados.

Activa la API My Organization en Auth0 Dashboard

Ve a Auth0 Dashboard > Applications > APIs.
Busca el banner de la API My Organization.
Selecciona Activate.
La API aparece en tu lista de Applications > APIs como My Organization API.

Una vez que actives la API My Organization:

La API está deshabilitada de forma predeterminada para todas las aplicaciones cliente.
Debes conceder acceso a aplicaciones y roles mediante client grants o políticas de RBAC.
Tus clientes empresariales pueden recuperar detalles de la Organización o configurar Proveedores de identidad (IdP) en nombre de sus propias Organizaciones.

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 cliente (máquina a máquina) Para que una aplicación acceda a la API My Organization en nombre del usuario, debes crear explícitamente un client grant para esa aplicación, lo que te permite definir los alcances máximos que puede solicitar. Como alternativa, puedes cambiar la política de los flujos de acceso de usuario a allow_all, lo que permite que cualquier aplicación de tu inquilino solicite cualquier alcance de la API My Organization. Dado que la API My Organization expone información y operaciones sensibles, Auth0 no recomienda usar allow_all para los flujos de acceso de usuario. Debes aplicar el principio de privilegio mínimo con la API My Organization para garantizar que las aplicaciones solo obtengan acceso a lo que realmente necesitan y así minimizar los posibles riesgos de seguridad. Los permisos finales concedidos 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 cualquier consentimiento otorgado por el usuario (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, consulta Application Access to APIs: Client Grants.

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 pueda realizar. La aplicación cliente debe proporcionar un objeto de configuración específico (my_organization_configuration) que contenga las siguientes propiedades:

Propiedad	Descripción
`my_organization_configuration`	Objeto. La aplicación debe proporcionar este objeto con la configuración que utilizará la API My Organization. Si la aplicación no define este objeto, la API My Organization devolverá un error y rechazará la solicitud.
`my_organization_configuration.connection_profile_id`	ID del perfil de conexión. ID del perfil de conexión usado con la aplicación al usar 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.
`my_organization_configuration.user_attribute_profile_id`	ID del perfil de atributos de usuario. ID del perfil de atributos de usuario usado con la aplicación al usar 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.
`my_organization_configuration.allowed_strategies`	Array de cadenas. Cada cadena es única y hace referencia a una estrategia compatible. Las estrategias compatibles, es decir, los valores de la enumeración, son las siguientes: `pingfederate`, `ad`, `adfs`, `waad`, `google-apps`, `okta`, `oidc` y `samlp`.
`my_organization_configuration.connection_deletion_behavior`	Enumeración (allow, allow_if_empty). Describe cómo se comporta la API My Organization cuando un usuario final intenta eliminar una conexión a través de 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 la eliminación de todos los usuarios que provienen de 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 la conexión. Si hay usuarios, la API My Organization devolverá un error y no continuará con la eliminación.

Obtener un token de acceso

Puedes obtener un token de acceso para la API My Organization del mismo modo que obtendrías un token de acceso para una de tus propias API.

Operaciones sensibles

Si vas a permitir que la API My Organization realice operaciones sensibles (como inscribir un método de autenticación), te recomendamos encarecidamente que uses autenticación step-up para aplicar políticas de seguridad adicionales mediante autenticación multifactor (MFA).

Ejemplos

Ejemplo del 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": 900,
  "scope": "read:my_org:details update:my_org:identity_providers"
}

Ejemplo de 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) para aplicaciones públicas sin un Secreto del cliente, aplicaciones de una sola página, aplicaciones móviles o nativas y herramientas de 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/'

Perfiles

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 clientes.

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 de atributos, sobrescrituras, ejemplos y cómo configurarlo, consulte perfil de conexión.

Perfil de atributos de usuario (UAP)

El Perfil de atributos de usuario (UAP) proporciona una forma coherente de definir, administrar y asignar atributos de usuario en protocolos como SCIM, SAML y OIDC. Para obtener más información sobre cómo funciona el UAP, sus asignaciones de atributos y sobrescrituras, ver ejemplos y cómo configurar uno, consulte Perfiles de atributos de usuario.

Límites de tasa

Los límites de tasa se aplican en función de tu nivel de servicio:

Nivel	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 impone límites de tasa por Organización. Estos límites están diseñados para garantizar una distribución equitativa de los recursos y evitar que una sola Organización afecte al rendimiento general de tu inquilino. Al aplicar estas restricciones, mitigamos el efecto de «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 una cantidad específica 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

Autenticación

HTTP: autenticación mediante Bearer

Se admiten tokens Bearer y DPoP, según la configuración de la API.


Tipo de esquema de seguridad:	http
Esquema de autorización HTTP:	bearer

​Activa la API My Organization en Auth0 Dashboard

​Atributos de la aplicación cliente

​Obtener un token de acceso

​Ejemplos

​Ejemplo del Flujo de código de autorización

​Ejemplo de Flujo de código de autorización con PKCE

​Perfiles

​Perfil de conexión (CP)

​Perfil de atributos de usuario (UAP)

​Límites de tasa

​Límites de tasa por Organización

​Autenticación