Gestión del inicio de sesión único
El inicio de sesión único (SSO) permite a los usuarios iniciar sesión en DJI FlightHub 2 con sus cuentas empresariales. El proveedor de identidad (IdP) empresarial autentica a los usuarios, y FlightHub 2 utiliza la información de identidad y las asignaciones de roles recibidas para establecer una sesión de inicio de sesión y conceder los permisos correspondientes. El sistema de identidad empresarial gestiona las contraseñas de las cuentas empresariales.
Esta función está disponible en el paquete Enterprise de la nube pública y en la versión local. Esta guía está dirigida a los administradores de la organización y a los administradores del sistema de identidad empresarial. Abarca la configuración de fuentes de identidad, la gestión de autorizaciones, las pruebas y la habilitación, y la gestión del inicio de sesión con cuentas locales.
Descripción general
Fuentes de identidad y proceso de inicio de sesión
Un Realm es una configuración independiente de una fuente de identidad SSO en FlightHub 2. Cada Realm utiliza un protocolo y relaciona las solicitudes de inicio de sesión según el dominio de correo electrónico. La aplicación correspondiente en el IdP empresarial y el Realm de FlightHub 2 deben utilizar protocolos, credenciales de aplicación, URL de devolución de llamada y configuraciones de salida de roles que coincidan.
Cuando un usuario inicia sesión mediante SSO desde FlightHub 2, el sistema selecciona una fuente de identidad habilitada según el dominio de la dirección de correo electrónico introducida y redirige al usuario al IdP empresarial para su autenticación. A continuación, FlightHub 2 valida la información de identidad recibida y determina el rol de gestión del usuario mediante las asignaciones. Los usuarios deben volver a autenticarse si la sesión empresarial ha caducado o si el IdP requiere una nueva autenticación.
El dominio de correo electrónico se utiliza únicamente para seleccionar una fuente de identidad. No es un identificador único de usuario y no concede permisos directamente. Los permisos de acceso al proyecto deben configurarse por separado después del inicio de sesión SSO.
Selección de un protocolo
FlightHub 2 admite OIDC, SAML 2.0 y OAuth2.
| Comparación | OIDC | SAML 2.0 | OAuth2 |
|---|---|---|---|
| Fuente de información de identidad | ID Token | Aserción SAML | JSON de información de usuario devuelto por User URL |
| Método de configuración | Discovery URL | IdP Metadata URL o archivo XML de Metadata | Configurar manualmente los puntos de conexión de autorización, Token e información de usuario |
| Configuración de obtención de roles | Role Path | Role Attribute | Role Path (UserInfo) |
| Identificador único de usuario | issuer + sub | IdP Entity ID + persistent NameID | Realm + value identified by USER_ID_KEY |
| Casos de uso adecuados | Sistemas de identidad empresarial que admiten OpenID Connect | Sistemas de identidad empresarial que ya utilizan SAML | Sistemas que ofrecen autorización OAuth2 y una API de información de usuario |
Nota:
- Se recomienda OIDC cuando el IdP empresarial admite varios protocolos. Si la empresa ya utiliza SAML para integrar otras aplicaciones, puede seguir utilizando SAML.
- OAuth2 es un protocolo de autorización. Antes de seleccionar OAuth2, confirme con el administrador del IdP qué campos de la API de información de usuario proporcionan el ID estable del usuario, el nombre de cuenta y la información de roles.
- OIDC y OAuth2 utilizan el flujo de código de autorización con validación PKCE. Obtienen la información de identidad de forma diferente:
- OIDC: Verifica el ID Token para establecer la identidad del usuario.
- OAuth2: Utiliza un Access Token para llamar a User URL y obtener y analizar la información de usuario. No utiliza los mecanismos de validación de identidad ID Token, Discovery ni JWKS de OIDC.
- SAML 2.0 solo admite el inicio de sesión iniciado desde FlightHub 2 (SP-Initiated), no el iniciado directamente desde el portal de aplicaciones del IdP empresarial.
Preparación de la configuración
Debe habilitar HTTPS antes de utilizar SSO en la versión local. Configure HTTPS en el entorno de despliegue y confirme que FlightHub 2 sea accesible mediante HTTPS antes de configurar una fuente de identidad SSO.
Como administrador de la organización, abra Configuración de inicio de sesión SSO de la organización, haga clic en Crear Realm y seleccione un protocolo.

Antes de la configuración, prepare la siguiente información con el administrador del IdP empresarial:
- El protocolo y el Client ID, Client Secret o Metadata de la aplicación correspondiente.
- El dominio de correo electrónico utilizado para seleccionar la fuente de identidad y una cuenta empresarial para la prueba de inicio de sesión.
- El campo de roles y los valores de roles en la información de identidad empresarial, y los roles de gestión de FlightHub 2 que se asignarán.
- Los puntos de conexión HTTPS del IdP y los certificados válidos. Asegúrese de que el backend de FlightHub 2 pueda acceder a los puntos de conexión y validar sus certificados.
Reglas de configuración:
- Se pueden habilitar como máximo 8 Realms al mismo tiempo en una organización. Las configuraciones que no estén habilitadas pueden guardarse como borradores o conservarse en estado deshabilitado.
- Los nombres de Realm deben ser únicos dentro de la organización. Los nombres para mostrar identifican los Realms en la interfaz de administración.
- Al crear un Realm, Login routing email puede contener una dirección de correo electrónico completa y válida o solo un dominio, por ejemplo,
user@example.com. El sistema almacena el dominio para el enrutamiento del inicio de sesión. No se puede asignar el mismo dominio a distintos Realms de una organización. - Las URL de acceso a FlightHub 2 y los puntos de conexión SSO deben utilizar HTTPS. Registre en el IdP la información de devolución de llamada generada por el sistema exactamente como se proporciona. No utilice la URL de la página de configuración en lugar de una URL de devolución de llamada.
Configuración de fuentes de identidad
Cada página de configuración de Realm tiene cuatro pestañas: Configuración básica, Gestión de autorizaciones, Pruebas y habilitación, y Configuración avanzada. Primero complete la configuración básica y guarde un borrador; después configure las asignaciones de roles, ejecute las pruebas y habilite el Realm.
OIDC
Configuración básica
| Campo | Instrucciones de configuración |
|---|---|
| Realm name / Realm display name | Introduzca un nombre para identificar la fuente de identidad, por ejemplo, Enterprise_OIDC |
| Login routing email | Introduzca una dirección de correo electrónico completa. Su dominio se utiliza para seleccionar la fuente de identidad |
| Discovery URL | Introduzca la Discovery URL HTTPS completa proporcionada por el IdP |
| Client ID | Introduzca el identificador de la aplicación registrada en el IdP |
| Client Secret | Introduzca el secreto de la aplicación correspondiente. El valor en texto sin formato no se muestra después de guardarlo |
| Callback URL | Se genera después de guardar el borrador. Regístrela exactamente como se proporciona como URI de redirección válida en el IdP |
| Web Origin URL | La genera el sistema. Regístrela en Web Origins según los requisitos del IdP |
Después de guardar el borrador, copie la información real de devolución de llamada del despliegue y complete la configuración de la aplicación del IdP. Las URL de ejemplo del formulario de creación no se pueden utilizar para la integración. El inicio de sesión normal y Prueba de inicio de sesión pueden utilizar URL de devolución de llamada diferentes. Registre cada URL según el despliegue.
En Gestión de autorizaciones, configure Role Path según la matriz de roles devuelta por el IdP, por ejemplo, roles o claims.roles. Para conocer las reglas de asignación de roles, consulte Gestión de autorizaciones más abajo.
Configuración avanzada
- Identificador único de identidad: Fijado en
issuer + sub. No se puede utilizar una dirección de correo electrónico en su lugar. - Claim del nombre de usuario para mostrar: El valor predeterminado es
name. Se utiliza únicamente para mostrar información y realizar búsquedas, no para relacionar identidades ni asignar permisos. - Actualización de Discovery: La actualización automática está deshabilitada de forma predeterminada después de la obtención inicial. Utilice Actualizar ahora para obtener de nuevo la configuración. Si la actualización falla, se conserva la configuración válida más reciente. La actualización automática y la configuración del intervalo dependen de las opciones disponibles en el despliegue.
- Opciones avanzadas del protocolo: Configure Scope, que debe incluir al menos
openid. Authorization Endpoint, Token Endpoint y JWKS URI se pueden sustituir manualmente. - Sustituciones manuales: Las actualizaciones de Discovery no sobrescriben los campos sustituidos. Haga clic en Restaurar valores automáticos para restaurar los valores detectados. Las sustituciones manuales no reemplazan la obtención y la validación de Discovery al guardar la configuración.
SAML 2.0
Configuración básica
- Introduzca el nombre del Realm, el nombre para mostrar y el correo electrónico de enrutamiento del inicio de sesión.
- Seleccione IdP Metadata URL o Subir XML para importar los Metadata del IdP empresarial. El sistema analiza IdP Entity ID, SSO URL, el certificado de firma y Binding.
- Guarde el borrador para obtener las SP Metadata URL y ACS URL generadas, o descargue el XML de SP Metadata.
- Proporcione los SP Metadata de FlightHub 2 al administrador del IdP para configurar la aplicación SAML correspondiente. Lea el SP Entity ID en los SP Metadata realmente generados; no presuponga que es igual a la Metadata URL.
- En Gestión de autorizaciones, introduzca el nombre del atributo de roles y configure las asignaciones de roles de gestión.
Para importar mediante URL, el backend de FlightHub 2 debe poder acceder a la Metadata URL mediante HTTPS. Para subir un archivo, utilice el XML de Metadata realmente exportado por el IdP empresarial.
Configure Role Attribute con el nombre exacto de <Attribute Name="..."> en la aserción SAML. El valor predeterminado es roles, y el nombre distingue entre mayúsculas y minúsculas. Los roles múltiples deben devolverse como elementos AttributeValue separados, en lugar de combinarse en una sola cadena. Por ejemplo:
<Attribute Name="roles">
<AttributeValue>fh2-member-org</AttributeValue>
</Attribute>
Configuración avanzada
- Identificador único de identidad: Fijado en
IdP Entity ID + persistent NameID. Configure el IdP para utilizar NameID persistente. - Attribute del nombre de usuario para mostrar: El valor predeterminado es
displayName. El IdP debe incluir este atributo en la salida. - Actualizaciones de Metadata: La actualización automática está deshabilitada de forma predeterminada después de la obtención inicial. Para la importación mediante URL, utilice la opción de actualización de la página. Para la carga de XML, vuelva a subir el archivo actualizado. La actualización automática y la configuración del intervalo dependen de las opciones disponibles en el despliegue.
- Opciones avanzadas del protocolo: Sustituya manualmente IdP Entity ID, SSO URL, Binding y el certificado de firma, o restaure los valores automáticos. Las actualizaciones de Metadata no sobrescriben los campos sustituidos manualmente.
- Gestión de certificados: Importe y actualice los certificados de firma mediante Metadata siempre que sea posible. La huella digital de un certificado se utiliza para verificarlo y no puede reemplazar el contenido del certificado X.509.
OAuth2
Configuración básica
OAuth2 no utiliza Discovery. Configure los puntos de conexión y las rutas de los campos de información de usuario según la documentación de la API del IdP.
| Campo | Instrucciones de configuración |
|---|---|
| Realm name / Realm display name | Introduzca un nombre de fuente de identidad, por ejemplo, Enterprise_OAuth2 |
| Login routing email | Introduzca una dirección de correo electrónico completa. Su dominio se utiliza para seleccionar la fuente de identidad |
| Authorization URL | La URL de autorización de usuario proporcionada por el IdP |
| Token URL | La URL de intercambio del código de autorización proporcionada por el IdP |
| User URL | La URL de la API para obtener el JSON de identidad y roles del usuario mediante un Access Token |
| Client ID / Client Secret | El identificador y el secreto de la aplicación del IdP correspondiente |
| USER_ID_KEY | La ruta del campo del ID estable del usuario en la respuesta de información de usuario, por ejemplo, id o data.id |
| USER_ACCOUNT_KEY | La ruta del campo del nombre de cuenta en la respuesta de información de usuario, por ejemplo, username o data.username |
| Scopes | Configure según los requisitos de permisos de la API de información de usuario del IdP |
| Callback URL | Se genera después de guardar el borrador. Regístrela en el IdP exactamente como se proporciona |
En Gestión de autorizaciones, Role Path (UserInfo) debe apuntar a la matriz de cadenas de roles en la respuesta de User URL, por ejemplo, roles o data.roles. FlightHub 2 no obtiene los roles de OAuth2 de un Access Token JWT ni de una API de permisos independiente.
Por ejemplo, si User URL devuelve la siguiente estructura, configure USER_ID_KEY como id, USER_ACCOUNT_KEY como username y Role Path como roles:
{
"id": "user-001",
"username": "sso-user",
"roles": ["fh2-member-org"]
}
Estos campos son solo ejemplos. Las rutas reales de los campos deben coincidir con la respuesta del IdP. Scopes no determina los roles, y no existe un requisito universal de incluir openid; siga los requisitos de la API del IdP. Aunque USER_ID_KEY sea sub o Scopes incluya openid, este Realm sigue analizando la identidad y los roles mediante la API de información de usuario de OAuth2.
Configuración avanzada
Configuración avanzada muestra la regla de identidad estable asociada a USER_ID_KEY y la ruta del campo del nombre de usuario para mostrar. La información para mostrar utiliza USER_ACCOUNT_KEY; no se requiere una segunda ruta de campo.
OAuth2 no ofrece Discovery ni importación o actualización de Metadata. Actualice los puntos de conexión manualmente cuando cambien. Los nuevos Realms no ofrecen las opciones de compatibilidad heredadas USE_REDIRECT_URL o SUPER_ACCOUNT. El comportamiento de compatibilidad de permisos para configuraciones migradas no se aplica a los nuevos Realms.
Gestión de autorizaciones
Obtención de roles y asignaciones de roles de gestión
En Gestión de autorizaciones, configure la ubicación de obtención de roles y asigne los valores externos de Role devueltos por el IdP a los roles de gestión de FlightHub 2.

| Protocolo | Configuración | Requisitos |
|---|---|---|
| OIDC | Role Path | Apunta a la matriz de cadenas de roles en la información de identidad, por ejemplo, roles |
| SAML 2.0 | Role Attribute | Coincide con Attribute Name en la aserción, por ejemplo, roles. Utilice elementos AttributeValue separados para los roles múltiples |
| OAuth2 | Role Path (UserInfo) | Apunta a la matriz de cadenas de roles en la respuesta de User URL, por ejemplo, data.roles |
Los roles de gestión y sus asignaciones predeterminadas se indican a continuación. Configure un valor externo de Role para cada rol de gestión.
| Rol de gestión de FlightHub 2 | Valor externo de Role predeterminado | Prioridad |
|---|---|---|
| Administrador de la organización | fh2-admin-org | 1 (la más alta) |
| Mantenedor de dispositivos | fh2-admin-device | 2 |
| Miembro | fh2-member-org | 3 |
- Los usuarios deben coincidir con al menos un rol de gestión para iniciar sesión mediante un Realm SSO recién creado.
- Si coinciden varios roles de gestión, se utiliza el rol con la prioridad más alta. Se ignoran los valores de Role no reconocidos.
- No se puede asignar el rol de superadministrador a los usuarios externos de SSO.
- Actualmente, la autorización se basa en Roles, no directamente en Groups, Security Groups ni otros atributos. Si la empresa gestiona los usuarios mediante grupos, configure el IdP para convertir la pertenencia a grupos en la lista de roles acordada.
Permisos del proyecto
Los roles de gestión de SSO y los permisos del proyecto son independientes. Después de iniciar sesión correctamente, un administrador debe añadir a los usuarios SSO en la gestión de miembros del proyecto, asignar roles del proyecto y relacionar a los usuarios mediante el identificador único estable del Realm correspondiente. Para configurar los roles del proyecto, consulte Gestión de roles de usuario del proyecto.
Pruebas y habilitación
Procedimiento de pruebas
- Complete Configuración básica y Gestión de autorizaciones y, a continuación, haga clic en Guardar borrador.
- Abra Pruebas y habilitación y ejecute Prueba de conectividad para comprobar los campos obligatorios, HTTPS, los puntos de conexión del protocolo y la configuración aplicable de Discovery, Metadata o certificados.
- Ejecute Prueba de inicio de sesión, autentíquese con una cuenta de prueba en la página del IdP que se abre y vuelva a la página de configuración original.
- Compruebe el identificador estable, el nombre para mostrar, el correo electrónico, la lista de Role y el rol de gestión recibidos. Confirme que la obtención y la asignación de roles funcionen según lo previsto.
- Una vez superadas las pruebas, haga clic en Guardar y aplicar y confirme que la fuente de identidad esté habilitada.

La prueba de conectividad solo valida la configuración y los puntos de conexión. No reemplaza una prueba real de inicio de sesión de usuario. OIDC requiere superar la prueba de conectividad antes de la habilitación. Si no se ha superado Prueba de inicio de sesión, habilitar el Realm tras aceptar los riesgos indicados en la página no significa que se haya superado la validación del inicio de sesión. Se recomienda completar ambas pruebas antes de la habilitación. SAML 2.0 debería habilitarse después de superar ambas pruebas. Los Realms OAuth2 recién creados requieren superar ambas pruebas; la disponibilidad de un botón o un mensaje de confirmación genérico no indica que se hayan superado las pruebas.
Si falla la obtención de Discovery, la importación de Metadata o el intercambio de Token, compruebe la red del backend de FlightHub 2, la confianza en los certificados TLS, las credenciales de la aplicación, las URL de devolución de llamada y los parámetros del protocolo. Corrija la configuración y, a continuación, guarde y vuelva a realizar las pruebas.
Mantenimiento de fuentes de identidad
La lista permite editar o continuar la configuración, realizar pruebas, habilitar, deshabilitar y eliminar fuentes de identidad. Actúe según cada estado como se indica a continuación:
| Estado | Acción |
|---|---|
| Borrador | Complete la configuración, guarde y ejecute las pruebas |
| Se requiere repetir las pruebas | Revise los cambios en los ajustes clave y vuelva a ejecutar las pruebas |
| Prueba fallida | Revise los resultados del fallo, corrija la configuración del IdP o de FlightHub 2 y repita las pruebas |
| Listo para habilitar | Confirme los resultados de las pruebas y habilite el Realm según las condiciones mostradas en la página |
| Habilitado | Disponible para iniciar sesión. Repita las pruebas según se indique tras cambiar los ajustes clave |
| Deshabilitado | La configuración se conserva, pero no está disponible para el inicio de sesión normal |
Después de actualizar los puntos de conexión, los certificados o los ajustes de salida de roles del IdP, actualice el Realm en consecuencia y repita las pruebas. Los campos sustituidos manualmente no se actualizan con los valores obtenidos automáticamente y deben comprobarse por separado.
Gestión del inicio de sesión con cuentas locales
El interruptor Permitir inicio de sesión con contraseña de cuenta local en la página Configuración de inicio de sesión SSO controla si las cuentas locales normales pueden iniciar sesión con una contraseña. Cuando está desactivado, estas cuentas no pueden iniciar sesión con contraseña, y los miembros deben hacerlo mediante una fuente de identidad SSO habilitada que haya superado las pruebas.
Para deshabilitar el inicio de sesión con contraseña de cuenta local:
- Configure, pruebe y habilite al menos un Realm, y confirme que las cuentas empresariales puedan iniciar sesión correctamente.
- Confirme que la cuenta del superadministrador de emergencia y su contraseña local funcionen.
- Desactive Permitir inicio de sesión con contraseña de cuenta local y seleccione Designar superadministrador de emergencia en el cuadro de diálogo.
- Revise el impacto, marque la casilla de confirmación y haga clic en Confirmar deshabilitación.

Si el IdP empresarial no está disponible o la configuración SSO es incorrecta, el superadministrador de emergencia designado puede acceder al sistema con una contraseña local para volver a habilitar el inicio de sesión con cuentas locales o corregir la configuración SSO. Un administrador de la organización normal no es un superadministrador de emergencia, y el nombre de cuenta por sí solo no determina si el inicio de sesión de emergencia está disponible.
Ejemplo de integración con Keycloak
Los siguientes ejemplos describen cómo configurar cada protocolo con Keycloak. Sustituya los dominios, nombres de Realm, Client IDs y rutas de campos de ejemplo por los valores del despliegue. Utilice las URL de devolución de llamada y la información de SP Metadata generadas por FlightHub 2. La ubicación de los menús puede variar entre versiones de Keycloak.
Las capturas de pantalla ilustran la ubicación de los ajustes y las opciones clave. Los nombres de Realm, Client y usuarios de prueba que aparecen en ellas son ejemplos. Para la configuración real, utilice la información de la fuente de identidad, la aplicación y los usuarios de su empresa.
Creación de una fuente de identidad empresarial, roles y usuarios de prueba
Inicie sesión en la consola de administración de Keycloak y cree o seleccione un Realm empresarial en Gestionar Realms, por ejemplo,
Enterprise.
En Roles del Realm, cree
fh2-admin-org,fh2-admin-deviceyfh2-member-org, o cree valores de roles que coincidan con las asignaciones de FlightHub 2.
En Usuarios, cree y habilite un usuario de prueba. Establezca una contraseña en Credenciales y complete las acciones obligatorias de la cuenta.
Asigne un rol de prueba en la pestaña Asignación de roles del usuario. Para la primera prueba, asigne solo un rol de gestión, como
fh2-member-org, para facilitar la verificación de los resultados.
Un Realm empresarial de Keycloak y un Realm de FlightHub 2 son unidades de configuración diferentes y no necesitan tener el mismo nombre. Al integrar varios protocolos, configure un Client independiente para cada uno y utilice dominios de enrutamiento del inicio de sesión diferentes.
Integración OIDC
Cree un Client OpenID Connect en Keycloak, por ejemplo,
Enterprise_OIDC.Habilite Client authentication y Standard flow, y deshabilite Implicit flow. Direct access grants no es necesario para SSO basado en navegador. Habilite Require PKCE y configure PKCE Method como
S256. Busque estos ajustes en Configuración → Configuración de capacidades.
Cree un Realm OIDC en FlightHub 2 e introduzca el correo electrónico de enrutamiento del inicio de sesión, Client ID, Client Secret y Discovery URL. La Discovery URL de Keycloak tiene el siguiente formato:
https://idp.example.com/realms/Enterprise/.well-known/openid-configurationGuarde el borrador de FlightHub 2 para obtener la información real de devolución de llamada. Registre las URL de devolución de llamada del inicio de sesión normal y de prueba en Valid redirect URIs del Client de Keycloak, y configure Web origins con la información generada por FlightHub 2. Obtenga el Client Secret en la pestaña Credenciales del Client.
Añada un User Realm Role Mapper en Ámbitos del Client → ámbito dedicado del Client → Asignadores:
Abra Ámbitos del Client, seleccione el ámbito dedicado del Client actual y abra la configuración del asignador.

Configuración Valor de ejemplo Name sikong-rolesToken Claim Name rolesClaim JSON Type StringMultivalued Activado Add to ID token / Add to access token / Add to userinfo Activado 
En FlightHub 2, configure Role Path como
roles, configure las asignaciones de roles de gestión y ejecute Prueba de conectividad y Prueba de inicio de sesión. Verifique los roles y, a continuación, guarde y aplique la configuración.
Integración SAML 2.0
Obtenga los IdP Metadata de Keycloak mediante una URL con el siguiente formato. El XML de Metadata devuelto por esta URL también se puede utilizar para subirlo como archivo.
https://idp.example.com/realms/Enterprise/protocol/saml/descriptorCree un Realm SAML 2.0 en FlightHub 2, importe los IdP Metadata, guarde el borrador y descargue el XML de SP Metadata generado.
En Keycloak, importe los SP Metadata en Clients → Importar Client, o cree un Client SAML manualmente y verifique los siguientes campos:
Configuración Valor de ejemplo Client ID Entity ID de los SP Metadata de FlightHub 2 Name Un nombre para identificar la aplicación, por ejemplo, Enterprise_SAMLValid redirect URIs ACS URL de FlightHub 2 Name ID format persistentForce name ID format Activado Force POST binding Activado, para devolver la respuesta SAML mediante POST Sign documents / Sign assertions Activado Signature algorithm RSA_SHA256Client signature required Activado. Importe el certificado de firma del SP desde los SP Metadata de FlightHub 2 IDP-Initiated SSO URL name Deje en blanco. Inicie sesión desde FlightHub 2 La siguiente captura de pantalla muestra dónde configurar NameID persistente y POST Binding. Verifique los ajustes de firma y certificados con la tabla anterior.

Configure los asignadores de roles e información de usuario en el ámbito dedicado del Client SAML:
Tipo de asignador Ajustes clave Role list Name y Role attribute name: roles; NameFormat:Basic; Single Role Attribute: ActivadoUser Property User property: username; Attribute name:displayNameUser Property User property: email; Attribute name:email
Compruebe el ámbito predeterminado
role_listy el asignador de roles personalizado del Client para evitar salidas de roles duplicadas o incompatibles. Al utilizar el asignador personalizadorolesanterior, elimine de este Client las asignaciones de ámbitos predeterminados que entren en conflicto.En FlightHub 2, configure Role Attribute como
rolesy el Attribute del nombre de usuario para mostrar comodisplayName; después configure las asignaciones de roles de gestión. Guarde y aplique la configuración una vez superadas ambas pruebas.
Client ID debe utilizar el SP Entity ID real, no el nombre para mostrar de la aplicación. La AuthnRequest de FlightHub 2 puede utilizar Redirect Binding mientras que la respuesta del IdP utiliza POST Binding; estos enlaces tienen fines diferentes. Después de volver a crear un Realm SAML de FlightHub 2, obtenga los nuevos SP Metadata y verifique y actualice los ajustes de Entity ID, ACS y certificados en el IdP.
Integración OAuth2
Keycloak proporciona puntos de conexión OAuth2 mediante un Client OpenID Connect. Seleccione el protocolo OAuth2 en FlightHub 2.
Cree un Client independiente en Keycloak, por ejemplo,
Enterprise_OAuth2. Siga el ejemplo OIDC anterior para configurar Client authentication, Standard flow, PKCE y las URL de devolución de llamada del inicio de sesión normal y de prueba, y obtenga el Secret propio de este Client.Añada un User Realm Role Mapper en el ámbito dedicado del Client. Configure Token Claim Name como
rolesy Multivalued como Activado, y asegúrese de que Add to userinfo esté Activado.Cree un Realm OAuth2 en FlightHub 2 e introduzca las credenciales de la aplicación correspondiente, el correo electrónico de enrutamiento del inicio de sesión y los siguientes ajustes:
Campo de FlightHub 2 Ejemplo de Keycloak Authorization URL https://idp.example.com/realms/Enterprise/protocol/openid-connect/authToken URL https://idp.example.com/realms/Enterprise/protocol/openid-connect/tokenUser URL https://idp.example.com/realms/Enterprise/protocol/openid-connect/userinfoUSER_ID_KEY subUSER_ACCOUNT_KEY preferred_usernameScopes openid profile email, para la API de información de usuario de Keycloak en este ejemploRole Path (UserInfo) rolesGuarde el borrador y configure las asignaciones de roles de gestión. Guarde y aplique la configuración únicamente después de superar Prueba de conectividad y Prueba de inicio de sesión, y de que la información de usuario y el rol de gestión coincidan con los resultados esperados.
Los Scopes y los campos de usuario de ejemplo se aplican a la configuración de Keycloak descrita anteriormente. Ajústelos según la documentación de la API al integrar otro IdP.
Preguntas frecuentes
¿Por qué los usuarios no pueden iniciar sesión aunque se haya superado la prueba de conectividad?
La prueba de conectividad comprueba la configuración y los puntos de conexión. Prueba de inicio de sesión verifica la información de identidad real, la obtención de roles y las asignaciones de roles de gestión. Ejecute Prueba de inicio de sesión y compruebe el ID estable del usuario, los campos de roles, los resultados de las asignaciones, las URL de devolución de llamada y los resultados de validación de firmas.
¿Cómo resuelvo una discrepancia en la URL de devolución de llamada?
Compare el redirect_uri de la solicitud real con la URL de devolución de llamada registrada para la aplicación del IdP correspondiente. Deben coincidir exactamente, incluidos el protocolo, el dominio, el puerto y la ruta. Registre las devoluciones de llamada del inicio de sesión normal y de prueba según el despliegue. No utilice la URL de la página de configuración del frontend ni los valores de ejemplo de un formulario sin guardar.
¿Debe coincidir el correo electrónico de enrutamiento del inicio de sesión con el correo del usuario en el IdP?
El correo electrónico de enrutamiento del inicio de sesión selecciona la fuente de identidad, mientras que el correo del usuario en el IdP forma parte de su perfil. Tienen fines diferentes. Siga los requisitos de configuración del IdP para las cuentas y las direcciones de correo electrónico. El dominio de enrutamiento del inicio de sesión debe cumplir los requisitos de formato de correo electrónico y no debe contener guiones bajos. Introduzca una dirección de correo electrónico completa al crear el Realm.
¿Por qué FlightHub 2 no puede obtener los roles devueltos por el IdP?
Para OIDC, compruebe Role Path con la estructura de la matriz en la información de identidad. Para OAuth2, compruebe la matriz de roles devuelta por User URL. Para SAML, compruebe las mayúsculas y minúsculas de Attribute Name y asegúrese de que los roles múltiples utilicen elementos AttributeValue separados. Compruebe también si hay conflictos entre los asignadores predeterminados y personalizados del IdP y confirme que los valores de Role devueltos coincidan con las asignaciones de roles de gestión.
¿Por qué no se ve ningún proyecto después de iniciar sesión correctamente?
Los roles de gestión de SSO no conceden automáticamente permisos del proyecto. Un administrador debe añadir al usuario en la gestión de miembros del proyecto, asignarle un rol del proyecto y relacionarlo mediante el identificador único estable de su Realm.
¿Se puede utilizar una dirección de correo electrónico como identificador único de usuario?
No. Las direcciones de correo electrónico pueden cambiar o reutilizarse. OIDC utiliza issuer + sub, SAML utiliza IdP Entity ID + persistent NameID y OAuth2 utiliza Realm + stable user ID. Los nombres para mostrar y los nombres de cuenta tampoco reemplazan el identificador único estable.
¿Cómo resuelvo los fallos de obtención de Discovery o Metadata?
Compruebe que la URL sea correcta, que el backend de FlightHub 2 pueda acceder a ella mediante HTTPS y que confíe en el certificado del IdP. Que el navegador pueda acceder o acepte un certificado no significa que el backend de FlightHub 2 pueda acceder o confíe en él. Para SAML, también se puede subir el XML de Metadata realmente exportado por el IdP. Después de resolver el problema, guarde y vuelva a realizar las pruebas.
¿Cómo resuelvo un fallo de intercambio de tokens después de la autenticación del IdP?
Compruebe la conexión de red y la confianza en los certificados TLS entre el backend de FlightHub 2 y la Token URL. Verifique el Client ID y el Client Secret correspondientes, la URL real de devolución de llamada y los parámetros PKCE. Repita las pruebas después de resolver el problema y confirme que la información de usuario y los roles de gestión se obtengan correctamente.
¿Cómo actualizo los certificados o los puntos de conexión?
Para OIDC, actualice Discovery. Para la importación SAML mediante URL, actualice Metadata; para la carga de XML, vuelva a subir el archivo actualizado. Compruebe los campos sustituidos manualmente y actualícelos o restaure los valores automáticos según sea necesario. Para OAuth2, actualice los puntos de conexión manualmente. Vuelva a ejecutar las pruebas después de realizar cambios.
¿Cerrar sesión en FlightHub 2 también cierra la sesión del usuario en el IdP empresarial?
Cerrar sesión solo finaliza la sesión de FlightHub 2. No cierra la sesión del usuario en el IdP empresarial. La sesión empresarial puede seguir activa en el siguiente inicio de sesión, y Prueba de inicio de sesión puede requerir una nueva autenticación.
¿Cómo se puede restablecer el acceso si el IdP falla después de deshabilitar el inicio de sesión con contraseña local?
El superadministrador de emergencia designado al deshabilitar el inicio de sesión con cuentas locales puede utilizar una contraseña local para acceder al sistema, volver a habilitar el inicio de sesión con cuentas locales o corregir la configuración SSO. Confirme que esta cuenta y contraseña funcionen antes de deshabilitar el inicio de sesión con cuentas locales.
¿Qué debo comprobar si no se puede habilitar una fuente de identidad?
Compruebe si se ha guardado el borrador, si los campos obligatorios son válidos, si se solicita repetir las pruebas o si se ha alcanzado el límite de 8 Realms habilitados. Para un Realm OAuth2 recién creado, confirme también que se hayan superado ambas pruebas.