Gerenciamento de login único

2026-11-17

O login único (SSO) permite que os usuários façam login no DJI FlightHub 2 com suas contas corporativas. O provedor de identidade (IdP) corporativo autentica os usuários, e o FlightHub 2 usa as informações de identidade retornadas e os mapeamentos de funções para estabelecer uma sessão de login e conceder as permissões correspondentes. As senhas das contas corporativas são gerenciadas pelo sistema de identidade corporativo.

Este recurso está disponível para o plano Enterprise de nuvem pública e a versão local. Este guia destina-se aos administradores da organização e aos administradores do sistema de identidade corporativo. Ele aborda a configuração de fontes de identidade, o gerenciamento de autorizações, os testes e a habilitação, e o gerenciamento de login de contas locais.



Visão geral

Fontes de identidade e processo de login

Um Realm é uma configuração independente de fonte de identidade SSO no FlightHub 2. Cada Realm usa um protocolo e faz a correspondência das solicitações de login pelo domínio do e-mail. O aplicativo correspondente no IdP corporativo e o Realm do FlightHub 2 devem usar protocolos, credenciais de aplicativo, URLs de callback e configurações de saída de funções compatíveis entre si.

Quando um usuário inicia o login SSO no FlightHub 2, o sistema seleciona uma fonte de identidade habilitada com base no domínio do endereço de e-mail informado e redireciona o usuário para o IdP corporativo para autenticação. Em seguida, o FlightHub 2 valida as informações de identidade retornadas e identifica a função de gerenciamento correspondente do usuário. Os usuários devem se autenticar novamente se a sessão de login corporativo tiver expirado ou se o IdP exigir nova autenticação.

O domínio do e-mail é usado apenas para selecionar uma fonte de identidade. Ele não é um identificador único do usuário e não concede permissões diretamente. As permissões de acesso ao projeto devem ser configuradas separadamente após o login SSO.


Escolha de um protocolo

O FlightHub 2 oferece suporte a OIDC, SAML 2.0 e OAuth2.

ComparaçãoOIDCSAML 2.0OAuth2
Fonte das informações de identidadeID TokenAsserção SAMLJSON de informações do usuário retornado por User URL
Método de configuraçãoDiscovery URLIdP Metadata URL ou arquivo Metadata XMLConfiguração manual dos endpoints de autorização, Token e informações do usuário
Configuração de obtenção de funçõesRole PathRole AttributeRole Path (UserInfo)
Identificador único do usuárioissuer + subIdP Entity ID + persistent NameIDRealm + value identified by USER_ID_KEY
Casos de uso adequadosSistemas de identidade corporativos que oferecem suporte a OpenID ConnectSistemas de identidade corporativos que já usam SAMLSistemas que fornecem autorização OAuth2 e uma API de informações do usuário

Observação:

  • OIDC é recomendado quando o IdP corporativo oferece suporte a vários protocolos. Se a empresa já usa SAML para integrar outros aplicativos, ela pode continuar usando SAML.
  • OAuth2 é um protocolo de autorização. Antes de selecionar OAuth2, confirme com o administrador do IdP quais campos da API de informações do usuário fornecem o ID estável do usuário, o nome da conta e as informações de funções.
  • OIDC e OAuth2 usam o fluxo de código de autorização com validação PKCE. Eles obtêm as informações de identidade de maneiras diferentes:
    • OIDC: Verifica o ID Token para estabelecer a identidade do usuário.
    • OAuth2: Usa um Access Token para chamar User URL e obter e analisar as informações do usuário. Não usa os mecanismos de validação de identidade ID Token, Discovery ou JWKS do OIDC.
  • SAML 2.0 oferece suporte apenas ao login iniciado no FlightHub 2 (SP-Initiated), e não ao login iniciado diretamente no portal de aplicativos do IdP corporativo.


Preparação para a configuração

O HTTPS deve ser habilitado antes que o SSO possa ser usado na versão local. Configure o HTTPS no ambiente de implantação e confirme que o FlightHub 2 está acessível por HTTPS antes de configurar uma fonte de identidade SSO.

Como administrador da organização, abra as Configurações de login SSO da organização, clique em Criar Realm e selecione um protocolo.

Configurações de login SSO e o botão Criar Realm

Antes da configuração, prepare as seguintes informações com o administrador do IdP corporativo:

  • O protocolo e o Client ID, Client Secret ou Metadata do aplicativo correspondente.
  • O domínio de e-mail usado para identificar a fonte de identidade correspondente e uma conta corporativa para o teste de login.
  • O campo de funções e os valores de funções nas informações de identidade corporativas, e as funções de gerenciamento do FlightHub 2 a serem atribuídas.
  • Os endpoints HTTPS e os certificados válidos do IdP. Certifique-se de que o backend do FlightHub 2 possa acessar os endpoints e validar seus certificados.

Regras de configuração:

  • No máximo 8 Realms podem ser habilitados ao mesmo tempo em uma organização. As configurações que não estiverem habilitadas podem ser salvas como rascunhos ou mantidas no estado desabilitado.
  • Os nomes dos Realms devem ser únicos dentro da organização. Os nomes de exibição identificam os Realms na interface administrativa.
  • Ao criar um Realm, Login routing email pode conter um endereço de e-mail completo e válido ou apenas um domínio, por exemplo, user@example.com. O sistema armazena o domínio para o roteamento de login. O mesmo domínio não pode ser atribuído a Realms diferentes dentro de uma organização.
  • As URLs de acesso ao FlightHub 2 e os endpoints SSO devem usar HTTPS. Registre no IdP as informações de callback geradas pelo sistema exatamente como fornecidas. Não use a URL da página de configuração no lugar de uma URL de callback.


Configuração de fontes de identidade

Cada página de configuração de Realm tem quatro abas: Configuração básica, Gerenciamento de autorizações, Testes e habilitação e Configuração avançada. Primeiro, conclua a configuração básica e salve um rascunho. Em seguida, configure os mapeamentos de funções, execute os testes e habilite o Realm.

OIDC

Configuração básica

CampoInstruções de configuração
Realm name / Realm display nameInsira um nome para identificar a fonte de identidade, por exemplo, Enterprise_OIDC
Login routing emailInsira um endereço de e-mail completo. Seu domínio é usado para selecionar a fonte de identidade
Discovery URLInsira a Discovery URL HTTPS completa fornecida pelo IdP
Client IDInsira o identificador do aplicativo registrado no IdP
Client SecretInsira o segredo do aplicativo correspondente. O valor em texto simples não é exibido após o salvamento
Callback URLGerada após o salvamento do rascunho. Registre-a exatamente como fornecida como uma URI de redirecionamento válida no IdP
Web Origin URLGerada pelo sistema. Registre-a em Web Origins conforme exigido pelo IdP

Após salvar o rascunho, copie as informações reais de callback da implantação e conclua a configuração do aplicativo no IdP. As URLs de exemplo no formulário de criação não podem ser usadas para integração. O login normal e o Teste de login podem usar URLs de callback diferentes. Registre cada URL de acordo com a implantação.

Em Gerenciamento de autorizações, defina Role Path de acordo com o array de funções retornado pelo IdP, por exemplo, roles ou claims.roles. Para consultar as regras de mapeamento de funções, consulte Gerenciamento de autorizações abaixo.

Configuração avançada

  • Identificador único de identidade: Fixo como issuer + sub. Não é possível usar um endereço de e-mail em seu lugar.
  • Claim do nome de exibição do usuário: O padrão é name. Usado apenas para exibição e pesquisa, não para correspondência de identidade ou atribuição de permissões.
  • Atualização de Discovery: A atualização automática é desabilitada por padrão após a obtenção inicial. Use Atualizar agora para obter a configuração novamente. Se a atualização falhar, a configuração válida mais recente será mantida. As configurações de atualização automática e de intervalo dependem das opções disponíveis na implantação.
  • Opções avançadas de protocolo: Configure Scope, que deve incluir pelo menos openid. Authorization Endpoint, Token Endpoint e JWKS URI podem ser substituídos manualmente.
  • Substituições manuais: Os campos substituídos não são sobrescritos pelas atualizações de Discovery. Clique em Restaurar valores automáticos para restaurar os valores descobertos. As substituições manuais não substituem a obtenção e a validação de Discovery ao salvar a configuração.

SAML 2.0

Configuração básica

  1. Insira o nome do Realm, o nome de exibição e o e-mail de roteamento de login.
  2. Selecione IdP Metadata URL ou Carregar XML para importar o Metadata do IdP corporativo. O sistema analisa IdP Entity ID, SSO URL, o certificado de assinatura e Binding.
  3. Salve o rascunho para obter SP Metadata URL e ACS URL geradas ou baixe o SP Metadata XML.
  4. Forneça o SP Metadata do FlightHub 2 ao administrador do IdP para configurar o aplicativo SAML correspondente. Leia o SP Entity ID no SP Metadata efetivamente gerado; não presuma que seja igual à Metadata URL.
  5. Em Gerenciamento de autorizações, insira o nome do atributo de funções e configure os mapeamentos de funções de gerenciamento.

Para importar por URL, o backend do FlightHub 2 deve poder acessar a Metadata URL por HTTPS. Para carregar um arquivo, use o Metadata XML efetivamente exportado pelo IdP corporativo.

Defina Role Attribute com o nome exato em <Attribute Name="..."> na asserção SAML. O padrão é roles, e o nome diferencia maiúsculas de minúsculas. Várias funções devem ser retornadas como elementos AttributeValue separados, em vez de combinadas em uma única string. Por exemplo:

<Attribute Name="roles">
  <AttributeValue>fh2-member-org</AttributeValue>
</Attribute>

Configuração avançada

  • Identificador único de identidade: Fixo como IdP Entity ID + persistent NameID. Configure o IdP para usar NameID persistente.
  • Atributo do nome de exibição do usuário: O padrão é displayName. O IdP deve fornecer esse atributo na saída.
  • Atualizações de Metadata: A atualização automática é desabilitada por padrão após a obtenção inicial. Para importação por URL, use a opção de atualização fornecida na página. Para carregamento de XML, carregue novamente o arquivo atualizado. As configurações de atualização automática e de intervalo dependem das opções disponíveis na implantação.
  • Opções avançadas de protocolo: Substitua manualmente IdP Entity ID, SSO URL, Binding e o certificado de assinatura, ou restaure os valores automáticos. As atualizações de Metadata não sobrescrevem os campos substituídos manualmente.
  • Gerenciamento de certificados: Importe e atualize os certificados de assinatura por meio de Metadata sempre que possível. A impressão digital de um certificado é usada para verificar o certificado e não pode substituir o conteúdo do certificado X.509.

OAuth2

Configuração básica

OAuth2 não usa Discovery. Configure os endpoints e os caminhos dos campos de informações do usuário de acordo com a documentação da API do IdP.

CampoInstruções de configuração
Realm name / Realm display nameInsira um nome para a fonte de identidade, por exemplo, Enterprise_OAuth2
Login routing emailInsira um endereço de e-mail completo. Seu domínio é usado para selecionar a fonte de identidade
Authorization URLA URL de autorização do usuário fornecida pelo IdP
Token URLA URL de troca do código de autorização fornecida pelo IdP
User URLA URL da API para obter o JSON de identidade e funções do usuário usando um Access Token
Client ID / Client SecretO identificador e o segredo do aplicativo correspondente no IdP
USER_ID_KEYO caminho do campo do ID estável do usuário na resposta de informações do usuário, por exemplo, id ou data.id
USER_ACCOUNT_KEYO caminho do campo do nome da conta na resposta de informações do usuário, por exemplo, username ou data.username
ScopesConfigure de acordo com os requisitos de permissões da API de informações do usuário do IdP
Callback URLGerada após o salvamento do rascunho. Registre-a no IdP exatamente como fornecida

Em Gerenciamento de autorizações, Role Path (UserInfo) deve apontar para o array de strings de funções na resposta de User URL, por exemplo, roles ou data.roles. O FlightHub 2 não obtém funções OAuth2 de um Access Token JWT nem de uma API de permissões separada.

Por exemplo, se User URL retornar a estrutura a seguir, defina USER_ID_KEY como id, USER_ACCOUNT_KEY como username e Role Path como roles:

{
  "id": "user-001",
  "username": "sso-user",
  "roles": ["fh2-member-org"]
}

Esses campos são apenas exemplos. Os caminhos reais dos campos devem corresponder à resposta do IdP. Scopes não determinam funções, e não há um requisito universal para incluir openid; siga os requisitos da API do IdP. Mesmo que USER_ID_KEY seja sub ou que Scopes inclua openid, este Realm continua analisando a identidade e as funções por meio da API de informações do usuário OAuth2.

Configuração avançada

Configuração avançada exibe a regra de identidade estável associada a USER_ID_KEY e o caminho do campo do nome de exibição do usuário. As informações de exibição usam USER_ACCOUNT_KEY; não é necessário um segundo caminho de campo.

OAuth2 não fornece Discovery nem importação ou atualização de Metadata. Atualize os endpoints manualmente quando eles mudarem. Os novos Realms não oferecem as opções legadas de compatibilidade USE_REDIRECT_URL ou SUPER_ACCOUNT. O comportamento de compatibilidade de permissões das configurações migradas não se aplica aos novos Realms.



Gerenciamento de autorizações

Obtenção de funções e mapeamento de funções de gerenciamento

Em Gerenciamento de autorizações, configure o local de obtenção das funções e mapeie os valores externos de Role retornados pelo IdP para as funções de gerenciamento do FlightHub 2.

Configurações de obtenção de funções e mapeamentos de funções de gerenciamento

ProtocoloConfiguraçãoRequisitos
OIDCRole PathAponta para o array de strings de funções nas informações de identidade, por exemplo, roles
SAML 2.0Role AttributeCorresponde a Attribute Name na asserção, por exemplo, roles. Use elementos AttributeValue separados para várias funções
OAuth2Role Path (UserInfo)Aponta para o array de strings de funções na resposta de User URL, por exemplo, data.roles

As funções de gerenciamento e seus mapeamentos padrão estão listados abaixo. Configure um valor externo de Role para cada função de gerenciamento.

Função de gerenciamento do FlightHub 2Valor externo padrão de RolePrioridade
Administrador da organizaçãofh2-admin-org1 (mais alta)
Responsável pelo dispositivofh2-admin-device2
Membrofh2-member-org3
  • Os usuários devem corresponder a pelo menos uma função de gerenciamento para fazer login por meio de um Realm SSO recém-criado.
  • Se houver correspondência com várias funções de gerenciamento, será usada a função com a prioridade mais alta. Os valores de Role não reconhecidos são ignorados.
  • Os usuários SSO externos não podem ser mapeados para Superadministrador.
  • Atualmente, a autorização é baseada em Roles, e não diretamente em Groups, Security Groups ou outros atributos. Se a empresa gerencia os usuários por meio de grupos, configure o IdP para converter a associação aos grupos na lista de funções acordada.

Permissões de projeto

As funções de gerenciamento SSO e as permissões de projeto são independentes. Após o login bem-sucedido, um administrador ainda deve adicionar os usuários SSO no gerenciamento de membros do projeto, atribuir funções de projeto e identificar os usuários usando o identificador único estável do Realm correspondente. Para configurar funções de projeto, consulte Gerenciamento de funções de usuário do projeto.



Testes e habilitação

Procedimento de teste

  1. Conclua Configuração básica e Gerenciamento de autorizações e clique em Salvar rascunho.
  2. Abra Testes e habilitação e execute o Teste de conectividade para verificar os campos obrigatórios, o HTTPS, os endpoints de protocolo e a configuração aplicável de Discovery, Metadata ou certificados.
  3. Execute o Teste de login, autentique-se com uma conta de teste na página do IdP que se abrir e retorne à página de configuração original.
  4. Verifique o identificador estável, o nome de exibição, o e-mail, a lista de Role e a função de gerenciamento retornados. Confirme que a obtenção e o mapeamento de funções funcionam como esperado.
  5. Após a aprovação nos testes, clique em Salvar e aplicar e confirme que a fonte de identidade está habilitada.
Teste de conectividade e Teste de login aprovados

O teste de conectividade valida apenas a configuração e os endpoints. Ele não substitui um teste de login real do usuário. OIDC exige um teste de conectividade bem-sucedido antes da habilitação. Se o Teste de login não tiver sido aprovado, habilitar o Realm após reconhecer os riscos conforme solicitado na página não significa que a validação de login tenha sido aprovada. Recomenda-se concluir ambos os testes antes da habilitação. SAML 2.0 deve ser habilitado após a aprovação em ambos os testes. Realms OAuth2 recém-criados exigem aprovação em ambos os testes; um botão disponível ou uma mensagem genérica de confirmação não indica que os testes tenham sido aprovados.

Se a obtenção de Discovery, a importação de Metadata ou a troca de Token falhar, verifique a rede do backend do FlightHub 2, a confiança no certificado TLS, as credenciais do aplicativo, as URLs de callback e os parâmetros de protocolo. Corrija a configuração, salve e teste novamente.


Manutenção de fontes de identidade

A lista permite editar ou continuar a configuração, testar, habilitar, desabilitar e excluir fontes de identidade. Proceda conforme cada status:

StatusAção
RascunhoConclua a configuração, salve e execute os testes
Novo teste necessárioRevise as alterações nas configurações principais e execute os testes novamente
Falha no testeRevise os resultados da falha, corrija a configuração do IdP ou do FlightHub 2 e teste novamente
Pronto para habilitarConfirme os resultados dos testes e habilite o Realm de acordo com as condições mostradas na página
HabilitadoDisponível para login. Teste novamente conforme solicitado após alterações nas configurações principais
DesabilitadoA configuração é mantida, mas não está disponível para login normal

Após atualizar os endpoints, os certificados ou as configurações de saída de funções do IdP, atualize o Realm de acordo com essas alterações e teste novamente. Os campos substituídos manualmente não são atualizados com os valores obtidos automaticamente e devem ser verificados separadamente.



Gerenciamento de login de contas locais

O seletor Permitir login com senha de conta local na página Configurações de login SSO controla se as contas locais comuns podem fazer login com senha. Quando ele está desabilitado, as contas locais comuns não podem usar o login com senha, e os membros devem fazer login por meio de uma fonte de identidade SSO habilitada e aprovada nos testes.

Para desabilitar o login com senha de conta local:

  1. Configure, teste e habilite pelo menos um Realm e confirme que as contas corporativas conseguem fazer login.
  2. Confirme que a conta do superadministrador de emergência e sua senha local funcionam.
  3. Desative Permitir login com senha de conta local e selecione Designar superadministrador de emergência na caixa de diálogo.
  4. Revise o impacto, selecione a caixa de confirmação e clique em Confirmar desabilitação.
Designação de um superadministrador de emergência ao desabilitar o login de contas locais

Se o IdP corporativo estiver indisponível ou a configuração SSO estiver incorreta, o superadministrador de emergência designado poderá acessar o sistema com uma senha local para habilitar novamente o login de contas locais ou corrigir a configuração SSO. Um administrador da organização comum não é um superadministrador de emergência, e o nome de uma conta, por si só, não determina se o login de emergência está disponível.



Exemplo de integração com Keycloak

Os exemplos a seguir descrevem como configurar cada protocolo com Keycloak. Substitua os domínios, os nomes de Realm, os Client IDs e os caminhos de campos dos exemplos pelos valores da implantação. Use as URLs de callback e as informações de SP Metadata geradas pelo FlightHub 2. A localização dos menus pode variar entre as versões do Keycloak.

As capturas de tela ilustram os locais de configuração e as opções principais. Os nomes de Realm, Client e usuários de teste mostrados nas capturas de tela são exemplos. Use as informações da fonte de identidade, do aplicativo e dos usuários da sua empresa para a configuração real.


Criação de uma fonte de identidade corporativa, funções e usuários de teste

  1. Faça login no console de administração do Keycloak e crie ou selecione um Realm corporativo em Gerenciar Realms, por exemplo, Enterprise.

    Criação de um Realm do Keycloak, inserção do nome e habilitação
  2. Em Funções do Realm, crie fh2-admin-org, fh2-admin-device e fh2-member-org, ou crie valores de funções que correspondam aos mapeamentos do FlightHub 2.

    Lista de funções do Realm do Keycloak e botão Criar função
  3. Em Usuários, crie e habilite um usuário de teste. Defina uma senha em Credenciais e conclua todas as ações obrigatórias da conta.

  4. Atribua uma função de teste na aba Mapeamento de funções do usuário. Para o primeiro teste, atribua apenas uma função de gerenciamento, como fh2-member-org, para facilitar a verificação dos resultados.

    Atribuição da função Membro a um usuário de teste no Keycloak

Um Realm corporativo no Keycloak e um Realm no FlightHub 2 são unidades de configuração diferentes e não precisam ter o mesmo nome. Ao integrar vários protocolos, configure um Client separado para cada protocolo e use domínios de roteamento de login diferentes.


Integração OIDC

  1. Crie um Client OpenID Connect no Keycloak, por exemplo, Enterprise_OIDC.

  2. Habilite Client authentication e Standard flow e desabilite Implicit flow. Direct access grants não são necessários para SSO baseado em navegador. Habilite Require PKCE e defina PKCE Method como S256. Procure essas configurações em Configurações → Configuração de recursos.

    Fluxo de autenticação de Client do Keycloak e configurações PKCE S256
  3. Crie um Realm OIDC no FlightHub 2 e insira o e-mail de roteamento de login, Client ID, Client Secret e Discovery URL. A Discovery URL do Keycloak tem o seguinte formato:

    https://idp.example.com/realms/Enterprise/.well-known/openid-configuration
    
  4. Salve o rascunho do FlightHub 2 para obter as informações reais de callback. Registre as URLs de callback de login normal e de teste em Valid redirect URIs no Client do Keycloak e configure Web origins usando as informações geradas pelo FlightHub 2. Obtenha o Client Secret na aba Credenciais do Client.

  5. Adicione um User Realm Role Mapper em Escopos de Client → escopo dedicado do Client → Mapeadores:

    Abra Escopos de Client, selecione o escopo dedicado do Client atual e abra a configuração do mapeador.

    Entrada do escopo dedicado em Escopos de Client do Keycloak
    ConfiguraçãoValor de exemplo
    Namesikong-roles
    Token Claim Nameroles
    Claim JSON TypeString
    MultivaluedAtivado
    Add to ID token / Add to access token / Add to userinfoAtivado
    User Realm Role Mapper do Keycloak fornecendo funções multivalor em tokens e informações do usuário
  6. No FlightHub 2, defina Role Path como roles, configure os mapeamentos de funções de gerenciamento e execute o Teste de conectividade e o Teste de login. Verifique as funções, salve e aplique a configuração.


Integração SAML 2.0

  1. Obtenha o IdP Metadata do Keycloak usando uma URL no formato a seguir. O Metadata XML retornado por essa URL também pode ser usado para carregar um arquivo.

    https://idp.example.com/realms/Enterprise/protocol/saml/descriptor
    
  2. Crie um Realm SAML 2.0 no FlightHub 2, importe o IdP Metadata, salve o rascunho e baixe o SP Metadata XML gerado.

  3. No Keycloak, importe o SP Metadata em Clients → Importar Client, ou crie um Client SAML manualmente e verifique os seguintes campos:

    ConfiguraçãoValor de exemplo
    Client IDEntity ID do SP Metadata do FlightHub 2
    NameUm nome para identificar o aplicativo, por exemplo, Enterprise_SAML
    Valid redirect URIsACS URL do FlightHub 2
    Name ID formatpersistent
    Force name ID formatAtivado
    Force POST bindingAtivado, para retornar a resposta SAML usando POST
    Sign documents / Sign assertionsAtivado
    Signature algorithmRSA_SHA256
    Client signature requiredAtivado. Importe o certificado de assinatura do SP a partir do SP Metadata do FlightHub 2
    IDP-Initiated SSO URL nameDeixe em branco. Inicie o login no FlightHub 2

    A captura de tela abaixo mostra onde configurar NameID persistente e POST Binding. Verifique as configurações de assinatura e certificado comparando-as com a tabela acima.

    Configurações SAML de NameID persistente e POST Binding do Keycloak
  4. Configure os mapeadores de funções e informações do usuário no escopo dedicado do Client SAML:

    Tipo de mapeadorConfigurações principais
    Role listName e Role attribute name: roles; NameFormat: Basic; Single Role Attribute: Ativado
    User PropertyUser property: username; Attribute name: displayName
    User PropertyUser property: email; Attribute name: email
    Mapeador SAML Role list do Keycloak com o atributo roles e Single Role Attribute ativado
  5. Verifique o escopo padrão role_list do Client e o mapeador de funções personalizado para evitar saídas de funções duplicadas ou conflitantes. Ao usar o mapeador roles personalizado acima, remova deste Client qualquer atribuição de escopo padrão conflitante.

  6. No FlightHub 2, defina Role Attribute como roles e o atributo do nome de exibição do usuário como displayName e configure os mapeamentos de funções de gerenciamento. Salve e aplique a configuração após a aprovação em ambos os testes.

Client ID deve usar o SP Entity ID real, não o nome de exibição do aplicativo. A AuthnRequest do FlightHub 2 pode usar Redirect Binding enquanto a resposta do IdP usa POST Binding; esses bindings têm finalidades diferentes. Após recriar um Realm SAML do FlightHub 2, obtenha o novo SP Metadata e verifique e atualize as configurações de Entity ID, ACS e certificados no IdP.


Integração OAuth2

O Keycloak fornece endpoints OAuth2 por meio de um Client OpenID Connect. Selecione o protocolo OAuth2 no FlightHub 2.

  1. Crie um Client separado no Keycloak, por exemplo, Enterprise_OAuth2. Siga o exemplo OIDC acima para configurar Client authentication, Standard flow, PKCE e as URLs de callback de login normal e de teste, e obtenha o Secret próprio deste Client.

  2. Adicione um User Realm Role Mapper no escopo dedicado do Client. Defina Token Claim Name como roles e Multivalued como Ativado e certifique-se de que Add to userinfo esteja Ativado.

  3. Crie um Realm OAuth2 no FlightHub 2 e insira as credenciais do aplicativo correspondente, o e-mail de roteamento de login e as seguintes configurações:

    Campo do FlightHub 2Exemplo do 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 a API de informações do usuário do Keycloak neste exemplo
    Role Path (UserInfo)roles
  4. Salve o rascunho e configure os mapeamentos de funções de gerenciamento. Salve e aplique a configuração somente após a aprovação no Teste de conectividade e no Teste de login e após confirmar que as informações do usuário e a função de gerenciamento correspondem aos resultados esperados.

Os Scopes e os campos de usuário do exemplo se aplicam à configuração do Keycloak descrita acima. Ajuste-os de acordo com a documentação da API ao integrar com outro IdP.



Perguntas frequentes

Por que os usuários não conseguem fazer login mesmo após a aprovação no teste de conectividade?

O teste de conectividade verifica a configuração e os endpoints. O Teste de login verifica as informações reais de identidade, a obtenção de funções e os mapeamentos de funções de gerenciamento. Execute o Teste de login e verifique o ID estável do usuário, os campos de funções, os resultados do mapeamento, as URLs de callback e os resultados da validação de assinatura.

Como resolver uma incompatibilidade de URL de callback?

Compare o redirect_uri da solicitação real com a URL de callback registrada para o aplicativo correspondente no IdP. Eles devem corresponder exatamente, incluindo protocolo, domínio, porta e caminho. Registre os callbacks de login normal e de teste de acordo com a implantação. Não use a URL da página de configuração do frontend nem valores de exemplo de um formulário não salvo.

O e-mail de roteamento de login deve corresponder ao e-mail do usuário no IdP?

O e-mail de roteamento de login seleciona a fonte de identidade, enquanto o e-mail do usuário no IdP faz parte do perfil do usuário. Eles têm finalidades diferentes. Siga os requisitos de configuração do IdP para contas e endereços de e-mail. O domínio de roteamento de login deve atender aos requisitos de formato de e-mail e não deve conter sublinhados. Insira um endereço de e-mail completo ao criar o Realm.

Por que o FlightHub 2 não consegue obter as funções retornadas pelo IdP?

Para OIDC, compare Role Path com a estrutura do array nas informações de identidade. Para OAuth2, verifique o array de funções retornado por User URL. Para SAML, verifique as maiúsculas e minúsculas de Attribute Name e certifique-se de que várias funções usem elementos AttributeValue separados. Verifique também se há conflitos entre os mapeadores padrão e personalizados do IdP e confirme que os valores de Role retornados correspondem aos mapeamentos de funções de gerenciamento.

Por que nenhum projeto está visível após um login bem-sucedido?

As funções de gerenciamento SSO não concedem permissões de projeto automaticamente. Um administrador deve adicionar o usuário no gerenciamento de membros do projeto, atribuir uma função de projeto e identificar o usuário usando o identificador único estável do Realm do usuário.

Um endereço de e-mail pode ser usado como identificador único do usuário?

Não. Os endereços de e-mail podem mudar ou ser reutilizados. OIDC usa issuer + sub, SAML usa IdP Entity ID + persistent NameID e OAuth2 usa Realm + stable user ID. Os nomes de exibição e os nomes de conta também não substituem o identificador único estável.

Como resolver falhas na obtenção de Discovery ou Metadata?

Verifique se a URL está correta, se o backend do FlightHub 2 pode acessá-la por HTTPS e se o backend confia no certificado do IdP. O acesso pelo navegador ou a aceitação de um certificado não significa que o backend do FlightHub 2 possa acessar a URL ou confiar no certificado. Para SAML, também é possível carregar o Metadata XML efetivamente exportado pelo IdP. Após resolver o problema, salve e teste novamente.

Como resolver uma falha na troca de token após a autenticação no IdP?

Verifique a conexão de rede e a confiança no certificado TLS entre o backend do FlightHub 2 e a Token URL. Verifique o Client ID e o Client Secret correspondentes, a URL real de callback e os parâmetros PKCE. Teste novamente após resolver o problema e confirme que as informações do usuário e as funções de gerenciamento são obtidas com sucesso.

Como atualizar certificados ou endpoints?

Para OIDC, atualize Discovery. Para importação SAML por URL, atualize Metadata; para carregamento de XML, carregue novamente o arquivo atualizado. Verifique os campos substituídos manualmente e atualize-os ou restaure os valores automáticos conforme necessário. Para OAuth2, atualize os endpoints manualmente. Execute os testes novamente após fazer alterações.

Sair do FlightHub 2 também encerra a sessão do usuário no IdP corporativo?

Sair encerra apenas a sessão do FlightHub 2. Isso não encerra a sessão do usuário no IdP corporativo. A sessão corporativa ainda pode estar ativa no próximo login, e o Teste de login pode exigir nova autenticação.

Como restaurar o acesso se o IdP falhar após a desabilitação do login com senha local?

O superadministrador de emergência designado ao desabilitar o login de contas locais pode usar uma senha local para acessar o sistema, habilitar novamente o login de contas locais ou corrigir a configuração SSO. Confirme que essa conta e senha funcionam antes de desabilitar o login de contas locais.

O que verificar se uma fonte de identidade não puder ser habilitada?

Verifique se o rascunho foi salvo, se os campos obrigatórios são válidos, se um novo teste foi solicitado ou se o limite de 8 Realms habilitados foi atingido. Para um Realm OAuth2 recém-criado, confirme também que ambos os testes foram aprovados.

Last Updated: