Connect to Context Handler / FKA with SAML 2.0

O FoxIDs pode ser ligado ao Context Handler com um método de autenticação SAML 2.0.

O Context Handler é um identity broker dinamarquês que liga os municípios dinamarqueses numa federação comum, em dinamarquês chamada Fælleskommunal Adgangsstyring (FKA).

O Context Handler é ligado como SAML 2.0 Identity Provider (IdP) baseado em OIOSAML 3 e OCES3 (RSASSA-PSS).

Ao configurar um método de autenticação SAML 2.0 e um registo de aplicação OpenID Connect, o FoxIDs torna-se uma bridge entre SAML 2.0 e OpenID Connect. O FoxIDs irá então tratar da ligação SAML 2.0 como Relying Party (RP) / Service Provider (SP) e na sua aplicação só precisa de se preocupar com OpenID Connect. Se necessário, pode eventualmente selecionar múltiplas opções de login, isto é, métodos de autenticação, a partir do mesmo registo de aplicação OpenID Connect.

Em teste, pode iniciar sessão com o FoxIDs test IdP.

Ou configurar um ambiente FoxIDs como test Identity Provider para Context Handler com um registo de aplicação SAML 2.0 e autenticar utilizadores de teste.

O Context Handler pode ser configurado com base em OIOSAML 2 ou OIOSAML 3 com OCES3 (RSASSA-PSS) e o FoxIDs suporta ainda os certificados necessários e é possível suportar NSIS.

Pode testar o login do Context Handler com o sample web app online (documentação do sample) clicando em Log in e depois em Danish Context Handler TEST para o ambiente de teste, selecione FoxIDs - test-corp na página de login do Context Handler, ou Danish Context Handler para produção.
Veja a configuração sample Context Handler no FoxIDs Control: https://control.foxids.com/test-corp
Obtenha acesso de leitura com o utilizador reader@foxids.com e a password gEh#V6kSw, depois selecione o ambiente context-handler, context-handler-test ou context-handler-idp-test.
O sample está configurado com ambientes separados para a integração Context Handler SAML 2.0.

Documentação do Context Handler / FKA:

• Guia do Context Handler guide.
• Portal de administração
  • Test
  • Production
• Aplicação de teste do Context Handler

Transforme o DK privilege XML claim num claim JSON.

Separate environment

O Context Handler requer que cada ligação num ambiente, teste ou produção, utilize um certificado OCES3 único.
Por isso, considere ligar o Context Handler em ambientes separados onde os certificados OCES3 possam ser configurados.

Crie um novo ambiente no FoxIDs Control Client:

1. Encontre a secção Environments no topo ao centro
2. Clique na lista suspensa
3. Clique em New environment
4. Adicione o Name
5. Clique em Create

Se configurar tanto um ambiente de teste como um de produção, devem ficar em ambientes separados. Se configurar um test Identity Provider para Context Handler, este também deve ficar num ambiente separado e ter um certificado OCES3 único.

Pode ligar facilmente dois ambientes no mesmo tenant com um Environment Link.

Certificate

O Context Handler requer que todos os pedidos, authn e logout, sejam assinados com certificados OCES3 de produção em todos os ambientes. NÃO é possível usar um certificado emitido por outra autoridade certificadora, um certificado self-signed ou certificados OCES3 de teste.

Um certificado OCES3 é válido durante três anos. Depois disso, tem de ser atualizado manualmente.

Adicione o certificado OCES3 .P12 no FoxIDs Control Client:

1. Selecione, ou crie, um ambiente separado para usar com Context Handler como Identity Provider ou com um test Identity Provider para Context Handler
2. Selecione o separador Certificates
3. Se não estiver configurado para certificados contidos, clique na seta para baixo do botão Swap certificate e depois, na secção Contained certificates, clique em Change container type
4. Clique no certificado primário 5, Adicione a password em Optional certificate password
5. Carregue o certificado OCES3 .P12

Posteriormente, é possível adicionar um certificado secundário e alternar entre o certificado primário e o secundário.

Configuring Context Handler as Identity Provider

Este guia descreve como configurar o Context Handler como SAML 2.0 Identity Provider e cumprir OIOSAML3.

Precisa de configurar o certificado OCES3 antes de seguir este guia.

1 - Comece por criar um método de autenticação SAML 2.0 no FoxIDs Control Client

1. Selecione o separador Authentication
2. Clique em New authentication e depois em Identity Provider (SAML 2.0)
3. Adicione o Name, por exemplo Context Handler
4. Adicione os metadata IdP do Context Handler no campo Metadata URL
   Metadata de teste: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2/metadata.idp
   Metadata de produção: https://n2adgangsstyring.stoettesystemerne.dk/runtime/saml2/metadata.idp
5. Clique em Create

6. Selecione Show advanced
7. Defina Logout response binding como Redirect
8. Configure um Custom SP issuer; o issuer pode opcionalmente começar com https://saml.. O issuer neste exemplo é https://saml.foxids.com/test-corp/context-handler-test/
9. Opcionalmente defina Certificate validation mode como Chain trust se o certificado root OCES3 for trusted na sua plataforma Defina Certificate revocation mode como Online
10. Selecione Yes em Add logout response location URL in metadata
11. Selecione Yes em Include the encryption certificate in metadata
12. Defina NameID format in metadata como urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

13. Em Attribute consuming service in metadata, clique em Add attribute consuming service e adicione o Service name
14. Adicione todos os claims que pretende receber como requested attributes com o formato urn:oasis:names:tc:SAML:2.0:attrname-format:uri. Opcionalmente defina cada atributo como required.

Os seguintes claims são os mais usados:

• https://data.gov.dk/model/core/specVersion
• https://data.gov.dk/concept/core/nsis/loa
• https://data.gov.dk/model/core/eid/professional/cvr
• https://data.gov.dk/model/core/eid/professional/orgName
• https://data.gov.dk/model/core/eid/cprNumber
• https://data.gov.dk/model/core/eid/email
• https://data.gov.dk/model/core/eid/firstName
• https://data.gov.dk/model/core/eid/lastName
• https://data.gov.dk/model/core/eid/privilegesIntermediate

15. Em Contact persons in metadata, clique em Add contact person e depois em Administrative para adicionar uma pessoa de contacto administrativa
16. Clique em Update
17. Vá ao topo do método de autenticação SAML 2.0
18. Encontre os SP-metadata em SAML 2.0 method URL, neste caso https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
19. O SP-metadata URL é usado para configurar um sistema de utilizador do Context Handler.

2 - Depois vá ao portal de administração do Context Handler em Test ou Production

1. Selecione IT-systems
2. Clique em Add IT-system
3. Preencha os campos e selecione User system
4. Vá ao separador User system
5. Selecione Context Handler with NSIS e remova a seleção de Context Handler without NSIS
6. Selecione OIOSAML3 como perfil OIOSAML e nível NSIS
7. Adicione o SP-metadata URL do método de autenticação SAML 2.0, neste caso https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
8. Preencha o restante, aceite os termos e clique em Save

3 - Adicione a transformação do claim privilege no FoxIDs Control Client

O FoxIDs pode transformar o DK privilege XML claim num claim JSON. Recomenda-se adicionar a transformação para obter claims e tokens mais pequenos. Além disso, torna os tokens legíveis.

1. Selecione o separador Claim transform
2. Clique em Add claim transform e depois em DK XML privilege to JSON
3. Clique em Update

O FoxIDs converte internamente claims SAML 2.0 em claims JWT. O mapeamento entre claims SAML 2.0 e JWT é criado automaticamente por predefinição. Pode encontrar e alterar o mapeamento no separador Settings.

Terminou. O método de autenticação SAML 2.0 pode agora ser usado como método de autenticação para registos de aplicação no ambiente.

Um registo de aplicação só emitirá os claims adicionados.
Por isso, lembre-se de adicionar os claims JWT aos registos de aplicação OpenID Connect ou de usar a notação *.

Configuring test Identity Provider for Context Handler

Este guia descreve como configurar o FoxIDs como test Identity Provider para o Context Handler. O Context Handler é adicionado como SAML 2.0 Relying Party.

Precisa de usar um ambiente separado para ter um espaço para os utilizadores de teste e configurar o certificado OCES3 antes de seguir este guia.

1 - Comece por criar um registo de aplicação SAML 2.0 no FoxIDs Control Client

1. Selecione o separador Applications

2. Clique em New application

3. Selecione Show advanced

4. Selecione Web Application (SAML 2.0)

5. Adicione o Name, por exemplo Context Handler IdP

6. Descarregue os metadata RP do Context Handler, onde pode encontrar endpoints e o certificado a trusted.
   Metadata de teste: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/metadata.idp
   O certificado está codificado em base64 e pode ser convertido num ficheiro de certificado .cer com a ferramenta de certificados FoxIDs.

7. Adicione Application issuer https://saml.n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime e os metadata

8. Adicione Assertion consumer service (ACS) URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/consume.idp dos metadata

9. Clique em Register

10. Leia o Metadata URL e guarde-o para mais tarde

11. Clique em Close

12. A configuração detalhada abre-se; selecione Show advanced no canto superior direito desta secção de configuração

13. Ative Absolute ACS URL

14. Defina Encrypt authn response como Yes

15. Adicione o certificado de encriptação dos metadata em Encryption certificate

16. Defina NameID format como urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

17. Adicione Logged out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffresponse.idp dos metadata

18. Adicione Single logout out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffrequest.idp dos metadata

19. Defina Logout request binding e Logout response binding como redirect

20. Defina os claims OIOSAML3 que devem ser emitidos para o Context Handler em Issue claims

Os seguintes claims são os mais usados:

• https://data.gov.dk/model/core/specVersion
• https://data.gov.dk/model/core/kombitSpecVer
• https://data.gov.dk/concept/core/nsis/loa
• https://data.gov.dk/model/core/eid/professional/cvr
• https://data.gov.dk/model/core/eid/privilegesIntermediate

21. Adicione o certificado de assinatura dos metadata em Signature validation certificate
22. Opcionalmente defina Certificate validation mode como Chain trust se o certificado root OCES3 for trusted na sua plataforma Defina Certificate revocation mode como Online
23. Defina Authn response sign type como Sign assertion
24. Configure um Custom IdP issuer; o issuer pode opcionalmente começar com https://saml.. O issuer neste exemplo é https://saml.foxids.com/test-corp/context-handler-test-idp/
25. Selecione Yes em Add logout response location URL in metadata
26. Selecione Yes em Include the encryption certificate in metadata
27. Em Contact persons in metadata, clique em Add contact person e depois em Administrative para adicionar uma pessoa de contacto administrativa
28. Clique em Update
29. Vá ao topo da secção da aplicação SAML 2.0
30. Encontre os metadata do test IdP em SAML 2.0 Metadata, neste caso https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata
    Os metadata do test IdP são usados para configurar o identity provider do Context Handler.

2 - Depois vá ao portal de administração do Context Handler em Test

1. Selecione IT-systems
2. Clique em Add IT-system
3. Preencha os campos e selecione Identity Provider
4. Vá ao separador Identity Provider
5. Selecione Context Handler with NSIS e remova a seleção de Context Handler without NSIS
6. Selecione OIOSAML3 como perfil OIOSAML e nível NSIS
7. Adicione o test IdP-metadata URL, neste caso https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata.
8. Preencha o restante, aceite os termos e clique em Save

É obrigatório estar registado como sua própria test authority, em dinamarquês egen test myndighed, no ambiente de teste para adicionar um acordo de federação. Um acordo de federação, em dinamarquês føderationsaftaler, é necessário para ativar o identity provider no Context Handler.

3 - Adicione a transformação de claims no FoxIDs Control Client

Crie os claims que têm de ser emitidos para o Context Handler em claim transforms.

1. Volte à aplicação SAML 2.0 Context Handler IdP
2. Selecione o separador Claim transforms
3. Adicione um claim Constant https://data.gov.dk/model/core/specVersion com o valor OIO-SAML-3.0
4. Adicione um claim Constant https://data.gov.dk/model/core/kombitSpecVer com o valor 2.0
5. Adicione um claim Constant de níveis de assurance, loa, https://data.gov.dk/concept/core/nsis/loa com, por exemplo, o valor Substantial ou leia o claim através do pipeline de claims

6. Adicione um claim Concatenated para substituir o claim NameID http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier por uma versão concatenada do número CVR, display name e unique user ID
7. Selecione Action Replace claim
8. Concatene os claims:
   • https://data.gov.dk/model/core/eid/professional/cvr
   • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
   • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
   • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
9. Defina Concatenate format string como C=DK,O={0},CN={1} {2},Serial={3}
10. Clique em Update

4 - Adicione mapeamentos de claim SAML 2.0 para claim JWT no FoxIDs Control Client

O FoxIDs converte internamente claims SAML 2.0 em claims JWT. O Context Handler usa um conjunto de claims SAML 2.0 definido pelo OIOSAML3 e os correspondentes mapeamentos JWT precisam de ser adicionados no ambiente.

1. Vá ao separador Settings e a Claim mappings
2. Clique em Add claim mapping para todos os claims configurados no passo 1.20; pode criar os seus próprios nomes curtos de claims JWT se não existir um nome standard, ou editar os claim mappings se já existirem
3. Clique em Update

5 - Adicione utilizadores de teste no FoxIDs Control Client

Pode adicionar utilizadores de teste com claims de teste no separador Users e no sub separador Internal Users.

Os claims de teste em utilizadores de teste são baseados em JWT e mapeados para claims SAML 2.0.

Cada utilizador de teste precisa de ter um claim CVR cvr, um claim given name given_name, um claim family name family_name e opcionalmente um claim privilege com um valor string XML de DK privilege codificado em base64.

Se o utilizador tiver de ter a função Job function role, em dinamarquês Jobfunktionsrolle, http://foxids.com/roles/jobrole/test-corp-admin_access/1, o DK privilege XML será, com número CVR de teste: 11111111:

<?xml version="1.0" encoding="UTF-8"?>
<bpp:PrivilegeList xmlns:bpp="http://digst.dk/oiosaml/basic_privilege_profile" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
    <PrivilegeGroup Scope="urn:dk:gov:saml:cvrNumberIdentifier:11111111">
        <Privilege>http://foxids.com/roles/jobrole/test-corp-admin_access/1</Privilege>
    </PrivilegeGroup>
</bpp:PrivilegeList>