Control API - aplicaciones y métodos de autenticación

Utilice FoxIDs Control API para configurar las aplicaciones en las que confía FoxIDs y los métodos de autenticación en los que confía FoxIDs. En Control API rutas y esquemas, el registro de una aplicación se denomina downparty y un método de autenticación se denomina upparty.

Antes de llamar a estas operaciones, configure Control API autenticación y derechos de acceso. Swagger sigue siendo la referencia exacta para propiedades específicas del protocolo, reglas de validación, operaciones auxiliares y esquemas de respuesta:

• Swagger (OpenAPI) JSON
• Swagger UI

Base de endpoints y derechos de acceso

Los ejemplos utilizan FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Reemplace {tenant_name} y {track_name} con tenant y los nombres técnicos del entorno. Cambie el host para una implementación autohospedada. Envíe el token de acceso Control API en el encabezado Authorization: Bearer {access_token}.

Estas operaciones requieren un derecho de acceso party para el entorno de destino. Conceda solo la operación read, create, update o delete requerida a través de la Control API jerarquía de derechos de acceso.

Listar e identificar registros

Utilice estos puntos finales para descubrir registros antes de llamar a un punto final de tipo específico:

Las respuestas de la lista contienen resúmenes seguros, el tipo de registro y un token de paginación opaco. Utilice la operación get específica del tipo para obtener la representación editable completa. Repita una solicitud paginada con los mismos filtros y el token devuelto hasta que no se devuelva ningún token.

El name técnico es el identificador estable utilizado por las operaciones de obtención, actualización, eliminación, secreto, clave y relación. Los nombres están en minúsculas. Proporcione un nombre al crear cuando una integración requiera un identificador predecible, o deje que FoxIDs genere uno. Utilice el asistente !newpartyname cuando necesite un nombre único antes de crear un recurso.

Operaciones específicas de tipo

Cada tipo de recurso tiene su propio punto final porque la configuración del protocolo es diferente. Los principales criterios de valoración son:

Las operaciones habituales son GET ?name={name}, POST para crear, PUT para actualizar y DELETE ?name={name}. Agregue el punto final a la base del punto final. Consultar Swagger para las operaciones soportadas por cada tipo.

La creación de aplicaciones o métodos de autenticación está sujeta al entorno y a los límites del plan tenant. Algunas operaciones de creación simultáneas limitadas por el plan pueden devolver 423 Locked; Vuelva a intentarlo después de un breve retraso.

Actualiza y cambia el nombre de forma segura

Las operaciones del grupo PUT son actualizaciones completas, no parches. Utilice este flujo de trabajo:

1. Enumere los recursos u obtenga el recurso conocido por nombre técnico.
2. Obtenga su representación completa específica del tipo.
3. Preservar las propiedades que deben permanecer sin cambios y aplicar los cambios previstos.
4. Envíe la representación editable completa al punto final PUT específico del tipo coincidente.

Utilice newName cuando el nombre técnico deba cambiar. Las referencias se actualizan como parte del flujo de cambio de nombre. El método de autenticación de inicio de sesión predeterminado denominado login no se puede cambiar ni eliminar.

Los secretos de cliente, las claves de cliente y algunos secretos API externos se administran mediante puntos finales dedicados. Deliberadamente no se devuelven como texto sin formato en la representación general del partido y no deben copiarse en una solicitud de actualización normal.

Conecte aplicaciones a métodos de autenticación

La colección allowUpParties de una aplicación controla qué métodos de autenticación se pueden utilizar para iniciar sesión en esa aplicación. Los métodos de autenticación a los que se hace referencia deben existir en el mismo entorno y ser compatibles con la configuración.

Trate esta relación como parte de la configuración completa de la aplicación al actualizarla. Eliminar un método de autenticación puede cambiar el enrutamiento de inicio de sesión para las aplicaciones que hacen referencia a él; Verifique las aplicaciones dependientes antes de eliminarlas. Utilice un Environment Link cuando la aplicación o el método de autenticación se conecte intencionalmente en entornos FoxIDs.

Administrar secretos y claves

Las aplicaciones OAuth 2.0 y OpenID Connect proporcionan operaciones secretas de cliente dedicadas. Un secreto se acepta cuando se crea, se almacena como un hash y no se devuelve en texto sin formato. La respuesta de la lista contiene los identificadores y la información segura necesarios para gestionar los secretos existentes.

Utilice credenciales superpuestas para la rotación:

1. Genere un nuevo secreto de cliente y guárdelo de forma segura.
2. Cree el secreto del cliente en FoxIDs e implemente el mismo valor en la aplicación consumidora.
3. Verifique que la aplicación utilice el nuevo secreto.
4. Elimine el antiguo secreto por su aplicación y sus identificadores secretos.

Los métodos de autenticación OpenID Connect y OAuth 2.0 pueden utilizar operaciones dedicadas de secreto de cliente o de clave de cliente, según el método de autenticación de cliente seleccionado. Una operación de clave privada acepta certificados y material de clave privada. External Login tiene un punto final secreto dedicado. Utilice el punto final exacto y el esquema de solicitud que se muestran en Swagger para el tipo de registro seleccionado.

Los secretos, las claves privadas y las cargas útiles completas de los certificados son confidenciales. Utilice TLS, otorgue acceso solo a clientes de automatización confiables, proteja los valores en reposo y no registre los cuerpos de solicitud o respuesta.

Ayudantes de metadatos y descubrimiento

Las operaciones auxiliares de protocolo reducen la configuración manual pero no reemplazan la validación del recurso resultante:

• Los métodos de autenticación OpenID Connect y OAuth 2.0 pueden leer metadatos de descubrimiento y completar configuraciones compatibles.
• SAML 2.0 registros de aplicaciones y métodos de autenticación pueden leer metadatos.
• WS-Federation registros de aplicaciones y métodos de autenticación pueden leer metadatos.
• WS-Federation los métodos de autenticación incluyen un asistente de sincronización de ID de Microsoft Entra.

Después de usar un asistente, inspeccione la configuración devuelta, aplique la política local y la configuración de reclamo, y guárdela a través del punto final de creación o actualización específico del tipo. Los metadatos pueden cambiar con el tiempo, así que defina si la sincronización es una acción administrativa explícita o un proceso recurrente controlado.

Eliminación y efectos de dependencia.

La eliminación de una aplicación detiene las solicitudes de nuevos protocolos para esa aplicación. Eliminar un método de autenticación puede impedir que las aplicaciones completen el inicio de sesión y puede alterar Home Realm Discovery opciones. Primero elimine o actualice las dependencias y trate ambas operaciones como cambios de configuración permanentes.

Las solicitudes de creación, actualización, secreto/clave, ayuda y eliminación se incluyen en el registro de auditoría de Control. Las operaciones de lectura no se escriben como eventos de auditoría.

Respuestas de error comunes

• 400 Bad Request cuando la configuración del protocolo, las referencias, los metadatos, los secretos, las claves o los nombres no son válidos o se alcanza un límite del plan.
• 401 Unauthorized cuando falta el token de acceso o no es válido.
• 403 Forbidden cuando la persona que llama carece del derecho de acceso requerido.
• 404 Not Found cuando el registro, secreto o clave seleccionados no existe.
• 409 Conflict cuando ya existe un nombre técnico o un identificador secreto.
• 423 Locked cuando una operación de creación limitada al plan está bloqueada temporalmente.

Utilice el cuerpo de la respuesta para los detalles de validación y Swagger UI para las respuestas declaradas por cada operación.

Documentación relacionada

• Control API derechos de autenticación y acceso
• Aplicaciones
• Métodos de autenticación
• Environment Link
• Reclamaciones y transformaciones de reclamaciones