Skip to Content

Registro dinámico de clientes

Permita que las aplicaciones cliente se registren por sí mismas mediante OAuth 2.0 Dynamic Client Registration, con initial access tokens.

Nota: Disponible con las suscripciones Advanced y Pro. El registro abierto para agentes de IA requiere Pro.

Con el registro dinámico de clientes, una aplicación cliente se registra por sí misma en lugar de crearse manualmente en la Admin Console. Envía sus metadatos (nombre, URIs de redirección, autenticación del cliente) al endpoint de registro y recibe a cambio un client ID y, en el caso de los clientes confidenciales, un client secret. La plataforma implementa OAuth 2.0 Dynamic Client Registration (RFC 7591) y el protocolo de gestión que permite al cliente leer, actualizar y eliminar posteriormente su propio registro (RFC 7592).

De forma predeterminada, cada registro requiere un initial access token que usted emite, de modo que decide quién puede registrar clientes y con qué frecuencia. Para agentes de IA y otros clientes públicos puede permitir además el registro abierto.

Los initial access tokens se gestionan en Integraciones → Aplicaciones → Registros dinámicos en la Admin Console.

Cómo funciona

  1. Usted emite un initial access token y lo entrega a quien registra el cliente, por ejemplo un socio o un pipeline de despliegue.
  2. El cliente envía una solicitud de registro al endpoint de registro, con el initial access token como Bearer token.
  3. La plataforma comprueba los metadatos según las reglas que se describen más abajo, crea la aplicación y responde con las credenciales del cliente, un registration access token y la URL de gestión propia del cliente.
  4. Con el registration access token, el cliente puede leer, actualizar o eliminar su registro. Cada actualización emite un nuevo registration access token e invalida el anterior.

El cliente registrado aparece en la pestaña Registros dinámicos, en Aplicaciones registradas, junto con la forma en que se registró y cuándo se utilizó por última vez. Su página de detalle es la misma que la de cualquier otra aplicación y está marcada como Registrada dinámicamente. Nadie puede iniciar sesión en ella todavía: como con cualquier aplicación nueva, primero hay que asignar el acceso.

Emitir un initial access token

  1. Vaya a Integraciones → Aplicaciones y abra la pestaña Registros dinámicos.
  2. Seleccione Emitir token.
  3. Introduzca un Nombre, por ejemplo el del socio o el sistema al que va destinado el token. Aparece en la lista y en el registro de auditoría.
  4. Establezca la Validez en días (de 1 a 365). El token caduca transcurrido este periodo.
  5. Deje seleccionado Un solo uso si el token debe permitir exactamente un registro. Desmárquelo para permitir cualquier número de registros hasta que el token caduque.
  6. Seleccione Emitir token y copie el token. Solo se muestra una vez y no puede recuperarse más tarde.

La página muestra también el Endpoint de registro que debe comunicar junto con el token. También se publica como registration_endpoint en el documento de discovery de OpenID Connect.

La lista muestra para cada token su tipo de uso, el número de registros realizados con él, su caducidad y quién lo emitió. Revocar impide que un token se utilice para nuevos registros. Las aplicaciones ya registradas con él no se ven afectadas. Los tokens caducados se eliminan automáticamente.

Registro abierto para agentes de IA

Nota: Disponible con la suscripción Pro.

Los agentes de IA, por ejemplo los clientes del Model Context Protocol (MCP), y las herramientas de línea de comandos se registran por sí mismos en el momento en que un usuario los conecta, sin que nadie entregue un token. Normalmente, cada instalación registra su propio cliente. El registro abierto permite exactamente eso para los clientes públicos, que no tienen client secret e inician la sesión de los usuarios con el flujo authorization code y PKCE.

  1. Vaya a Configuración → Avanzado.
  2. En la tarjeta Registro abierto, active Registro abierto para clientes públicos.
  3. En Usuarios que pueden iniciar sesión, seleccione los directorios cuyos usuarios pueden utilizar dichos clientes.
  4. Seleccione Guardar cambios.

Para los clientes registrados de forma abierta:

  • Solo se aceptan clientes públicos. Un registro sin initial access token debe enviar "token_endpoint_auth_method": "none", y el cliente sigue siendo público: una actualización posterior no puede añadir un client secret. Los clientes confidenciales siguen necesitando un initial access token.
  • El acceso se deriva de los directorios. Los usuarios de los directorios seleccionados pueden iniciar sesión después de dar su consentimiento, sin una asignación por aplicación. La selección se aplica a los registros nuevos; las aplicaciones ya registradas conservan los directorios con los que se registraron.
  • Los registros tienen un límite de tasa de 10 por hora por dirección IP de cliente y de 200 por hora en total (20 durante el periodo de prueba).
  • Los registros no utilizados se eliminan. Un cliente en el que nadie ha iniciado sesión se elimina al cabo de 24 horas, y también un cliente sin inicios de sesión ni solicitudes de token durante 90 días. Cada eliminación se registra en el registro de auditoría.
  • No hay propietario. Las aplicaciones registradas de forma abierta no se asignan a ningún administrador.

El endpoint de registro se anuncia en el documento de discovery, que se sirve en /.well-known/openid-configuration y, para los clientes OAuth que lo buscan allí, en /.well-known/oauth-authorization-server. Si un agente solicita un access token para un recurso concreto, como un servidor MCP, registre ese recurso como API.

Al desactivar el registro abierto se detienen los nuevos registros anónimos. Los clientes ya registrados siguen funcionando y pueden seguir gestionando su registro. Sin la suscripción Pro, los usuarios de los directorios dejan de obtener acceso automático a los clientes registrados de forma abierta: asígnelos explícitamente; de lo contrario, los clientes no utilizados se eliminan al cabo de 90 días.

Registrar un cliente

El cliente envía sus metadatos como una solicitud POST en JSON:

curl -X POST https://id.example.com/oidc/register \
  -H "Authorization: Bearer <initial access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Partner Portal",
    "redirect_uris": ["https://portal.partner.example/callback"],
    "post_logout_redirect_uris": ["https://portal.partner.example/"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'

Un registro correcto responde con 201 Created:

{
  "client_id": "V1StGXR8_Z5jdHi6B-myT",
  "client_secret": "...",
  "client_name": "Partner Portal",
  "redirect_uris": ["https://portal.partner.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "registration_client_uri": "https://id.example.com/oidc/register/V1StGXR8_Z5jdHi6B-myT",
  "registration_access_token": "..."
}

El cliente almacena client_secret y registration_access_token de forma segura. Ninguno de los dos puede recuperarse de nuevo.

Gestionar el registro

El cliente gestiona su registro en registration_client_uri, autenticándose con su registration access token actual:

SolicitudEfecto
GETDevuelve el registro actual.
PUTSustituye el registro por los metadatos enviados. El cuerpo debe contener client_id; un campo omitido se elimina. La respuesta incluye un nuevo registration access token.
DELETEElimina la aplicación. Sus usuarios ya no pueden iniciar sesión en ella.

Un administrador puede editar o eliminar una aplicación registrada dinámicamente en la Admin Console como cualquier otra. Tenga en cuenta que el siguiente PUT del cliente sobrescribe los campos que le pertenecen (nombre, URIs de redirección, grant types, autenticación del cliente, client URI y claves del cliente). Las asignaciones, las políticas, los propietarios y la configuración de consentimiento se mantienen tal como los estableció el administrador.

Qué puede ser un cliente registrado

MetadatosRegla
token_endpoint_auth_methodclient_secret_basic (predeterminado), client_secret_post, private_key_jwt o none.
Tipo de aplicaciónSe deriva de la autenticación del cliente: none crea una aplicación de página única, o una aplicación nativa cuando se envía "application_type": "native" o cuando cada URI de redirección es una dirección de loopback (http://127.0.0.1, http://[::1], http://localhost) o un esquema propio de la aplicación. Una redirección de loopback nativa coincide con cualquier puerto. Cualquier otro método crea una aplicación web. Un cliente nativo debe utilizar none.
grant_typesDebe contener authorization_code y puede añadir refresh_token. Se rechazan los grants implicit, client credentials, device y token exchange.
response_typesSolo code.
redirect_uris, post_logout_redirect_urisSin comodines y sin URIs en el dominio propio del proveedor de identidad.
client_uriDebe utilizar https.
jwksSolo claves públicas, RSA de al menos 2048 bits o EC en la curva P-256. Necesario para private_key_jwt.
jwks_uri, sector_identifier_uri, backchannel_logout_uri, request_urisSe rechazan, porque la plataforma tendría que llamar a estas URLs por sí misma. Un administrador puede establecer después las opciones correspondientes en la aplicación.
client_nameOpcional. Sin nombre, la aplicación se llama "Dynamic client" seguido de su client ID. A un nombre que ya está en uso se le añade una parte del client ID.
default_max_ageSe acepta.

Cualquier otro metadato se ignora y no forma parte de la respuesta.

Algunas opciones las decide siempre la plataforma, independientemente del contenido de la solicitud:

  • Requerir el consentimiento del usuario está activado. Los usuarios confirman el acceso solicitado en el primer inicio de sesión, y los refresh tokens solo se emiten cuando el cliente solicita el scope offline_access.
  • No se aplica ningún perfil de seguridad. Un administrador puede establecer uno después; consulte Financial-grade API security.
  • La aplicación no aparece en el portal de aplicaciones de los usuarios.
  • El administrador que emitió el initial access token se convierte en propietario de la aplicación. Las aplicaciones registradas de forma abierta no tienen propietario.

Los registros cuentan para el límite de aplicaciones de su suscripción.

Registro de auditoría

EventoSe registra cuando
INITIAL_ACCESS_TOKEN_CREATEDUn administrador emite un initial access token.
INITIAL_ACCESS_TOKEN_REVOKEDUn administrador revoca un initial access token.
CONFIGURATION_UPDATEDUn administrador activa o desactiva el registro abierto o cambia sus directorios.
APPLICATION_REGISTEREDUn cliente se registra. El cliente que se registra queda registrado como actor.
APPLICATION_UPDATEDUn cliente actualiza su registro.
APPLICATION_DEREGISTEREDUn cliente elimina su registro, un administrador elimina la aplicación o se elimina un registro abierto no utilizado.

Consulte Tipos de eventos de auditoría para ver la lista completa.

Solución de problemas

  • invalid_token en el registro: el initial access token es desconocido, ha caducado, se ha revocado o un token de un solo uso ya se ha utilizado. Emita uno nuevo. Sin token, el registro abierto está desactivado.
  • 429 en un registro anónimo: se ha alcanzado el límite de tasa del registro abierto. Vuelva a intentarlo más tarde.
  • invalid_token al leer, actualizar o eliminar: el registration access token se sustituyó por uno más reciente en la última actualización, o la aplicación se eliminó.
  • invalid_client_metadata con "dynamic client registration is not available": la suscripción no incluye la función. Los registros y las actualizaciones se rechazan; la lectura y la eliminación de un registro existente siguen funcionando.
  • invalid_client_metadata: los metadatos infringen una de las reglas anteriores. El error_description indica el campo. Una solicitud rechazada no consume un token de un solo uso.
  • Los usuarios no pueden iniciar sesión tras el registro: la aplicación aún no tiene asignaciones. Asigne usuarios, grupos o directorios en la pestaña Asignaciones de la aplicación. En el caso de un cliente registrado de forma abierta, compruebe que el usuario pertenece a uno de sus directorios.

Véase también

En esta página