Ir para o conteúdo

Configurando o Active Directory Federation Services usando WS-Federation no Jitterbit App Builder

O App Builder pode se integrar com o Active Directory Federation Services (AD FS) usando o protocolo WS-Federation Passive. O protocolo WS-Federation Passive define os seguintes papéis operacionais:

Ator Papel
App Builder Relying party
AD FS Identity Provider (IdP) / Security Token Service (STS)
Usuário Passive requestor

A configuração envolve os seguintes procedimentos:

  1. Criar um Security Provider do App Builder para AD FS
  2. Criar um Relying Party Trust do AD FS para o App Builder

Requisitos

Para prosseguir, você precisará do seguinte:

  • Acesso de administrador ao AD FS.
  • Acesso de administrador ao App Builder.
  • O App Builder precisará se conectar ao AD FS via HTTPS para recuperar o documento de metadados. O AD FS deve usar um certificado TLS com uma raiz confiável: o App Builder não conseguirá recuperar o documento de metadados se o certificado não for confiável ou for inválido de outra forma.
  • O App Builder precisará estar disponível via HTTPS. O security provider Require HTTPS deve estar habilitado (ou outras medidas devem ser tomadas para garantir que o App Builder seja acessível apenas via HTTPS).
  • As máquinas cliente precisarão ser configuradas para confiar no AD FS. Caso contrário, o AD FS solicitará que o usuário faça login.

As instruções abaixo farão referência às seguintes propriedades:

Exemplo Observações
URL do App Builder https://example.com/Vinyl/ O App Builder deve estar acessível via HTTPS. A URL deve incluir a barra à direita. O caminho diferencia maiúsculas de minúsculas.
Nome do Provider ExampleADFS Cada security provider do App Builder recebe um nome lógico. Como o nome do provider aparecerá na URL do Protocolo Passive (veja abaixo), evite espaços, pontuação e caracteres especiais.
URL do Protocolo Passive https://example.com/Vinyl/signin-ExampleADFS O App Builder provisiona automaticamente um endpoint do Protocolo Passive para security providers WS-Federation. Observe que o Nome do Provider aparece na URL.
URL do Documento de Metadados de Federação https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml A URL do Documento de Metadados de Federação pode ser recuperada no AD FS. Para fazer isso, abra o console de Gerenciamento do AD FS. Selecione AD FS → Serviço → Endpoints. Localize o endpoint do Tipo Federation Metadata.
Audience https://example.com/Vinyl/signin-ExampleADFS Recomenda-se usar um valor Audience para limitar o escopo da autenticação. Considere usar a URL do Protocolo Passive.
Wtrealm https://example.com/Vinyl/signin-ExampleADFS Embora o Wtrealm seja arbitrário, o AD FS e o App Builder devem usar o mesmo valor. Considere usar a URL do Protocolo Passive.

Criar um security provider do App Builder para AD FS

Para criar o Security Provider, comece fazendo login no App Builder como administrador:

  1. Navegue até o IDE
  2. Selecione o botão Security Providers
  3. Clique no botão + Security Provider
  4. Forneça o seguinte:

    • Name: Security Provider Name (veja acima)

      Exemplo: ExampleADFS

    • Type: WS-Federation

    • Enabled: Marque
    • User Provisioning: Marque para ativar o provisionamento de usuário Just-in-Time (JIT).
    • Supplies Group Membership: Marque se o AD FS foi configurado para passar a associação de grupo do usuário.
    • Show On Login Form: Marque
  5. Clique no botão Save

  6. No painel Properties, clique no botão + Property
  7. Forneça o seguinte:

    • Parameter: MetadataAddress
    • Value: Federation Metadata Document URL (veja acima).

      Exemplo: https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

  8. Clique no ícone Save (Verificar)

  9. No painel Properties, clique no botão + Property
  10. Forneça o seguinte:

    • Parameter: Wtrealm
    • Value: Wtrealm (veja acima).

      Exemplo: https://example.com/Vinyl/signin-ExampleADFS

  11. Clique no ícone Save (Verificar)

  12. No painel Properties, clique no botão + Property
  13. Forneça o seguinte:

    • Parameter: Audience
    • Value: Audience (veja acima).

      Exemplo: https://example.com/Vinyl/signin-ExampleADFS

  14. Clique no ícone Save (Verificar)

Além disso, qualquer reclamação mapeada no AD FS precisará ser mapeada no App Builder. Por exemplo, para mapear a reclamação de email:

  1. No painel Claims, clique no botão + Claim
  2. Forneça o seguinte:

    • Identifier: Nome do tipo de reclamação.\

      Exemplo: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • Usage: Uso do tipo de reclamação.\

      Exemplo: Email Address

  3. Clique no ícone Save (Verificar)

Criar uma confiança de terceira parte confiável do AD FS para o App Builder

Cada instância do App Builder deve ser registrada no AD FS como uma confiança de terceira parte confiável. Os detalhes completos sobre como criar, configurar e manter as confianças de terceira parte confiável estão fora do escopo deste documento. Para obter informações adicionais sobre como criar uma confiança de terceira parte confiável do AD FS, consulte o seguinte artigo do TechNet:

https://technet.microsoft.com/en-ca/library/dd807108.aspx

A criação de uma confiança de terceira parte confiável requer as seguintes informações:

  • Protocol: WS-Federation Passive
  • Relying party WS-Federation Passive protocol URL: Corresponde à Passive Protocol URL (veja acima).\

    Exemplo: https://example.com/Vinyl/signin-ExampleADFS

  • Relying party trust identifier: Corresponde à propriedade Wtrealm (veja acima).\

    Exemplo: https://example.com/Vinyl/signin-ExampleADFS

Criar uma URL de ponto de extremidade do AD FS para o App Builder

Cada instância do App Builder deve ser registrada no AD FS como um ponto de extremidade. Crie um ponto de extremidade na guia Endpoints no AD FS da seguinte forma:

  1. Clique no botão Add WS-Federation.
  2. Defina o ponto de extremidade como padrão (caixa de seleção).
  3. Trusted URL: Corresponde à propriedade Wtrealm (veja acima).

    Exemplo: https://example.com/Vinyl/signin-ExampleADFS

Mapeamentos de reclamações (opcional)

Você também pode fornecer mapeamentos de reclamações opcionais. O seguinte artigo do TechNet descreve como criar regras de reclamação de confiança de terceira parte confiável do AD FS:

https://technet.microsoft.com/en-us/library/dd807115.aspx

As reclamações comumente mapeadas incluem:

  • Email Address - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Group Membership - http://schemas.xmlsoap.org/claims/Group

Consulte Claims para obter informações adicionais sobre reclamações.

Solução de problemas

Configurações de configuração

Nota

Suas configurações podem variar dos exemplos fornecidos neste artigo, dependendo do seu ambiente exato. Por exemplo, dependendo de como o seu App Pool está configurado, você pode estar usando demo.zudy.com/signin-AD ou demo.zudy.com/vinyl/signin-AD.

A URL pode exibir: http://example.com/Vinyl/service/authentication/external?returnUrl=...

Verifique o Event Log do Windows. Especificamente, procure no log de Aplicação por avisos do ASP.Net com ID de evento 1309. Você pode encontrar uma entrada com a seguinte mensagem de exceção:

Unable to get document from: https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

Isso indica que o App Builder não conseguiu recuperar o Documento de Metadados de Federação. Verifique se o servidor web do App Builder consegue fazer uma conexão HTTPS com o endpoint do Documento de Metadados do AD FS. Também verifique se o certificado TLS é válido. Se o certificado não for assinado por uma raiz confiável, você pode registrá-lo manualmente.

Erro "runtime error" após fazer login no AD FS

A URL pode exibir: http://example.com/Vinyl/signin-ADFS

Verifique o Event Log do Windows. Especificamente, procure no log de Aplicação por avisos do ASP.Net com ID de evento 1309. Você pode encontrar uma entrada com uma das seguintes mensagens de exceção.

Claim ausente

The identity does not contain a claim matching the given type.

Isso indica que a asserção SAML está sem um ou mais claims obrigatórios. Revise a configuração da regra de claim.

Audience inválida

IDX10214: Audience validation failed. Audiences: 'https://example.com/Vinyl'. Did not match:  validationParameters.ValidAudience: 'https://example.com/Vinyl/' or validationParameters.ValidAudiences: 'null'

Isso indica que a asserção SAML possui uma restrição de audience inválida. Neste exemplo em particular, falta a barra final na audience. Verifique se o identificador de confiança da terceira parte é correto.

Execute o seguinte comando do PowerShell no servidor AD FS para exibir as configurações de confiança de terceira parte:

> Get-ADFSRelyingPartyTrust -Identifier https://example.com/Vinyl/signin-ADFS`

O argumento Identifier corresponde à Passive Protocol URL (conforme descrito acima).

Associação de grupo ausente

Por padrão, o ADFS não inclui claims de grupo em asserções SAML. Administradores devem criar uma ou mais regras de claim para incluir associação a grupos. É possível criar uma única regra de claim que inclua todas as associações a grupos. Entretanto, usando a regra "Group Claim" integrada do ADFS, é necessária uma regra separada para cada grupo.

O artigo a seguir descreve como incluir associação a grupos que correspondem a uma expressão regular (por exemplo, grupos começados com "App Builder"):

http://social.technet.microsoft.com/wiki/contents/articles/8008.ad-fs-2-0-selectively-send-group-membership-s-as-a-claim.aspx

O artigo a seguir descreve como usar expressões regulares em regras de transformação de claims:

http://social.technet.microsoft.com/wiki/contents/articles/16161.ad-fs-2-0-using-regex-in-the-claims-rule-language.aspx

Configuração de claims ausente ou incorreta

A seguinte mensagem de erro pode ser exibida após autenticar:

The user account (`<username>`) has successfully signed in, but no available landing page has been configured for their applications.

Isso indica configuração bem-sucedida do provedor de segurança e do lado do AD FS, mas significa que os claims ainda não foram configurados ou precisam de correção.

Revise os claims retornados ao App Builder pelo ADFS (verifique se Store Claims está marcado) para garantir que os claims corretos estão sendo passados (associações a grupos, atributos personalizados) ao App Builder e que possam ser mapeados na configuração de Claims do Provedor de Segurança.