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:
- Criar um Security Provider do App Builder para AD FS
- 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:
- Navegue até o IDE
- Selecione o botão Security Providers
- Clique no botão + Security Provider
-
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
-
-
Clique no botão Save
- No painel Properties, clique no botão + Property
-
Forneça o seguinte:
- Parameter: MetadataAddress
-
Value:
Federation Metadata Document URL(veja acima).Exemplo:
https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml
-
Clique no ícone Save (Verificar)
- No painel Properties, clique no botão + Property
-
Forneça o seguinte:
- Parameter: Wtrealm
-
Value:
Wtrealm(veja acima).Exemplo:
https://example.com/Vinyl/signin-ExampleADFS
-
Clique no ícone Save (Verificar)
- No painel Properties, clique no botão + Property
-
Forneça o seguinte:
- Parameter: Audience
-
Value: Audience (veja acima).
Exemplo:
https://example.com/Vinyl/signin-ExampleADFS
-
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:
- No painel Claims, clique no botão + Claim
-
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
-
-
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:
- Clique no botão Add WS-Federation.
- Defina o ponto de extremidade como padrão (caixa de seleção).
-
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.
Erro "runtime error" ao clicar no link "sign in with..."
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.
Imprimir configurações de confiança de terceira parte do AD FS
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"):
O artigo a seguir descreve como usar expressões regulares em regras de transformação de claims:
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.