Gestión del inicio de sesión único

2026-11-17

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ónOIDCSAML 2.0OAuth2
Fuente de información de identidadID TokenAserción SAMLJSON de información de usuario devuelto por User URL
Método de configuraciónDiscovery URLIdP Metadata URL o archivo XML de MetadataConfigurar manualmente los puntos de conexión de autorización, Token e información de usuario
Configuración de obtención de rolesRole PathRole AttributeRole Path (UserInfo)
Identificador único de usuarioissuer + subIdP Entity ID + persistent NameIDRealm + value identified by USER_ID_KEY
Casos de uso adecuadosSistemas de identidad empresarial que admiten OpenID ConnectSistemas de identidad empresarial que ya utilizan SAMLSistemas 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.

Configuración de inicio de sesión SSO y botón Crear Realm

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

CampoInstrucciones de configuración
Realm name / Realm display nameIntroduzca un nombre para identificar la fuente de identidad, por ejemplo, Enterprise_OIDC
Login routing emailIntroduzca una dirección de correo electrónico completa. Su dominio se utiliza para seleccionar la fuente de identidad
Discovery URLIntroduzca la Discovery URL HTTPS completa proporcionada por el IdP
Client IDIntroduzca el identificador de la aplicación registrada en el IdP
Client SecretIntroduzca el secreto de la aplicación correspondiente. El valor en texto sin formato no se muestra después de guardarlo
Callback URLSe 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 URLLa 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

  1. Introduzca el nombre del Realm, el nombre para mostrar y el correo electrónico de enrutamiento del inicio de sesión.
  2. 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.
  3. Guarde el borrador para obtener las SP Metadata URL y ACS URL generadas, o descargue el XML de SP Metadata.
  4. 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.
  5. 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.

CampoInstrucciones de configuración
Realm name / Realm display nameIntroduzca un nombre de fuente de identidad, por ejemplo, Enterprise_OAuth2
Login routing emailIntroduzca una dirección de correo electrónico completa. Su dominio se utiliza para seleccionar la fuente de identidad
Authorization URLLa URL de autorización de usuario proporcionada por el IdP
Token URLLa URL de intercambio del código de autorización proporcionada por el IdP
User URLLa URL de la API para obtener el JSON de identidad y roles del usuario mediante un Access Token
Client ID / Client SecretEl identificador y el secreto de la aplicación del IdP correspondiente
USER_ID_KEYLa ruta del campo del ID estable del usuario en la respuesta de información de usuario, por ejemplo, id o data.id
USER_ACCOUNT_KEYLa ruta del campo del nombre de cuenta en la respuesta de información de usuario, por ejemplo, username o data.username
ScopesConfigure según los requisitos de permisos de la API de información de usuario del IdP
Callback URLSe 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.

Configuración de obtención de roles y asignaciones de roles de gestión

ProtocoloConfiguraciónRequisitos
OIDCRole PathApunta a la matriz de cadenas de roles en la información de identidad, por ejemplo, roles
SAML 2.0Role AttributeCoincide con Attribute Name en la aserción, por ejemplo, roles. Utilice elementos AttributeValue separados para los roles múltiples
OAuth2Role 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 2Valor externo de Role predeterminadoPrioridad
Administrador de la organizaciónfh2-admin-org1 (la más alta)
Mantenedor de dispositivosfh2-admin-device2
Miembrofh2-member-org3
  • 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

  1. Complete Configuración básica y Gestión de autorizaciones y, a continuación, haga clic en Guardar borrador.
  2. 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.
  3. 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.
  4. 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.
  5. Una vez superadas las pruebas, haga clic en Guardar y aplicar y confirme que la fuente de identidad esté habilitada.
Prueba de conectividad y Prueba de inicio de sesión superadas

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:

EstadoAcción
BorradorComplete la configuración, guarde y ejecute las pruebas
Se requiere repetir las pruebasRevise los cambios en los ajustes clave y vuelva a ejecutar las pruebas
Prueba fallidaRevise los resultados del fallo, corrija la configuración del IdP o de FlightHub 2 y repita las pruebas
Listo para habilitarConfirme los resultados de las pruebas y habilite el Realm según las condiciones mostradas en la página
HabilitadoDisponible para iniciar sesión. Repita las pruebas según se indique tras cambiar los ajustes clave
DeshabilitadoLa 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:

  1. Configure, pruebe y habilite al menos un Realm, y confirme que las cuentas empresariales puedan iniciar sesión correctamente.
  2. Confirme que la cuenta del superadministrador de emergencia y su contraseña local funcionen.
  3. Desactive Permitir inicio de sesión con contraseña de cuenta local y seleccione Designar superadministrador de emergencia en el cuadro de diálogo.
  4. Revise el impacto, marque la casilla de confirmación y haga clic en Confirmar deshabilitación.
Designación de un superadministrador de emergencia al deshabilitar el inicio de sesión con cuentas locales

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

  1. Inicie sesión en la consola de administración de Keycloak y cree o seleccione un Realm empresarial en Gestionar Realms, por ejemplo, Enterprise.

    Creación de un Realm de Keycloak, introducción de su nombre y habilitación
  2. En Roles del Realm, cree fh2-admin-org, fh2-admin-device y fh2-member-org, o cree valores de roles que coincidan con las asignaciones de FlightHub 2.

    Lista de roles del Realm de Keycloak y botón Crear rol
  3. En Usuarios, cree y habilite un usuario de prueba. Establezca una contraseña en Credenciales y complete las acciones obligatorias de la cuenta.

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

    Asignación del rol Miembro a un usuario de prueba en Keycloak

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

  1. Cree un Client OpenID Connect en Keycloak, por ejemplo, Enterprise_OIDC.

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

    Flujo de autenticación del Client de Keycloak y ajustes de PKCE S256
  3. 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-configuration
    
  4. Guarde 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.

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

    Entrada del ámbito dedicado en Ámbitos del Client de Keycloak
    ConfiguraciónValor de ejemplo
    Namesikong-roles
    Token Claim Nameroles
    Claim JSON TypeString
    MultivaluedActivado
    Add to ID token / Add to access token / Add to userinfoActivado
    User Realm Role Mapper de Keycloak que incluye roles multivalor en los tokens y en la información de usuario
  6. 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

  1. 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/descriptor
    
  2. Cree un Realm SAML 2.0 en FlightHub 2, importe los IdP Metadata, guarde el borrador y descargue el XML de SP Metadata generado.

  3. En Keycloak, importe los SP Metadata en Clients → Importar Client, o cree un Client SAML manualmente y verifique los siguientes campos:

    ConfiguraciónValor de ejemplo
    Client IDEntity ID de los SP Metadata de FlightHub 2
    NameUn nombre para identificar la aplicación, por ejemplo, Enterprise_SAML
    Valid redirect URIsACS URL de FlightHub 2
    Name ID formatpersistent
    Force name ID formatActivado
    Force POST bindingActivado, para devolver la respuesta SAML mediante POST
    Sign documents / Sign assertionsActivado
    Signature algorithmRSA_SHA256
    Client signature requiredActivado. Importe el certificado de firma del SP desde los SP Metadata de FlightHub 2
    IDP-Initiated SSO URL nameDeje 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.

    Ajustes de NameID persistente y POST Binding de SAML en Keycloak
  4. Configure los asignadores de roles e información de usuario en el ámbito dedicado del Client SAML:

    Tipo de asignadorAjustes clave
    Role listName y Role attribute name: roles; NameFormat: Basic; Single Role Attribute: Activado
    User PropertyUser property: username; Attribute name: displayName
    User PropertyUser property: email; Attribute name: email
    Asignador Role list de SAML en Keycloak con el atributo roles y Single Role Attribute activado
  5. Compruebe el ámbito predeterminado role_list y el asignador de roles personalizado del Client para evitar salidas de roles duplicadas o incompatibles. Al utilizar el asignador personalizado roles anterior, elimine de este Client las asignaciones de ámbitos predeterminados que entren en conflicto.

  6. En FlightHub 2, configure Role Attribute como roles y el Attribute del nombre de usuario para mostrar como displayName; 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.

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

  2. Añada un User Realm Role Mapper en el ámbito dedicado del Client. Configure Token Claim Name como roles y Multivalued como Activado, y asegúrese de que Add to userinfo esté Activado.

  3. 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 2Ejemplo de Keycloak
    Authorization URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/auth
    Token URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/token
    User URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/userinfo
    USER_ID_KEYsub
    USER_ACCOUNT_KEYpreferred_username
    Scopesopenid profile email, para la API de información de usuario de Keycloak en este ejemplo
    Role Path (UserInfo)roles
  4. Guarde 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.

Last Updated: