Verbind Context Handler / FKA met SAML 2.0

FoxIDs kan worden verbonden met Context Handler via een SAML 2.0 authenticatiemethode.

Context Handler is een Deense identity broker die de Deense gemeenten in een gezamenlijke federatie verbindt, in het Deens Fælleskommunal Adgangsstyring (FKA).

Context Handler is verbonden als een SAML 2.0 Identity Provider (IdP) op basis van OIOSAML 3 en OCES3 (RSASSA-PSS).

Door een SAML 2.0 authenticatiemethode en een OpenID Connect applicatieregistratie te configureren wordt FoxIDs een bridge tussen SAML 2.0 en OpenID Connect. FoxIDs handelt de SAML 2.0 verbinding af als Relying Party (RP) / Service Provider (SP) en je hoeft alleen OpenID Connect in je applicatie te gebruiken. Indien nodig kun je meerdere login opties (authenticatiemethoden) selecteren vanuit dezelfde OpenID Connect applicatieregistratie.

In test kun je inloggen met de FoxIDs test IdP.

Of configureer een FoxIDs omgeving als test Identity Provider voor Context Handler met een SAML 2.0 applicatieregistratie en authenticeer testgebruikers.

Context Handler kan worden geconfigureerd op basis van OIOSAML 2 of OIOSAML 3 met OCES3 (RSASSA-PSS) en FoxIDs ondersteunt bovendien de vereiste certificaten en het is mogelijk om NSIS te ondersteunen.

Je kunt Context Handler login testen met de online web app sample (sample docs) door op Log in te klikken en daarna Danish Context Handler TEST voor de testomgeving (selecteer FoxIDs - test-corp op de Context Handler loginpagina) of Danish Context Handler voor productie.
Bekijk de Context Handler voorbeeldconfiguratie in FoxIDs Control: https://control.foxids.com/test-corp
Vraag read toegang aan met gebruiker reader@foxids.com en wachtwoord gEh#V6kSw en selecteer de context-handler, context-handler-test of context-handler-idp-test omgeving.
Het voorbeeld is geconfigureerd met aparte omgevingen voor de Context Handler SAML 2.0 integratie.

Context Handler / FKA documentatie:

• Context Handler gids.
• Beheerportaal
  • Test
  • Productie
• Context Handler testapplicatie

Transformeer de DK privilege XML claim naar een JSON claim.

Aparte omgeving

Context Handler vereist dat elke verbinding in een omgeving (test of productie) een uniek OCES3 certificaat gebruikt.
Overweeg daarom Context Handler te koppelen in aparte omgevingen waar de OCES3 certificaten kunnen worden geconfigureerd.

Maak een nieuwe omgeving in FoxIDs Control Client:

1. Zoek de sectie Environments bovenin het midden
2. Klik op de drop-down
3. Klik New environment
4. Voeg de Name toe
5. Klik Create

Als je zowel een test als een productie omgeving configureert, moeten ze in aparte omgevingen worden geplaatst. Als je een test Identity Provider voor Context Handler configureert, moet die ook in een aparte omgeving geplaatst worden en een uniek OCES3 certificaat hebben.

Je kunt twee omgevingen binnen dezelfde tenant eenvoudig verbinden met een Environment Link.

Certificaat

Context Handler vereist dat alle requests (authn en logout) worden ondertekend met productie OCES3 certificaten in alle omgevingen.
Het is NIET mogelijk om een certificaat te gebruiken dat door een andere certificaatautoriteit is uitgegeven, een self-signed certificaat of test OCES3 certificaten.

Een OCES3 certificaat is drie jaar geldig. Daarna moet het handmatig worden vernieuwd.

Voeg het .P12 OCES3 certificaat toe in FoxIDs Control Client:

1. Selecteer (of maak) een aparte omgeving die gebruikt wordt voor Context Handler als Identity Provider of een test Identity Provider voor Context Handler
2. Selecteer het tabblad Certificates
3. Als het niet is geconfigureerd voor containercertificaten, klik je op het pijltje omlaag bij Swap certificate en klik je in de sectie Contained certificates op Change container type
4. Klik op het primaire certificaat
5. Voeg het wachtwoord toe in Optional certificate password
6. Upload het .P12 OCES3 certificaat

Daarna is het mogelijk een secundair certificaat toe te voegen en te wisselen tussen het primaire en secundaire certificaat.

Context Handler configureren als Identity Provider

Deze gids beschrijft hoe je Context Handler instelt als een SAML 2.0 Identity Provider en voldoet aan OIOSAML3.

Je moet het OCES3 certificaat configureren voordat je deze gids volgt.

1 - Begin met het maken van een SAML 2.0 authenticatiemethode in FoxIDs Control Client

1. Selecteer het tabblad Authentication
2. Klik New authentication en daarna Identity Provider (SAML 2.0)
3. Voeg de Name toe, bijv. Context Handler
4. Voeg de Context Handler IdP metadata toe in het Metadata URL veld
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2/metadata.idp
   Productie metadata: https://n2adgangsstyring.stoettesystemerne.dk/runtime/saml2/metadata.idp
5. Klik Create

6. Selecteer Show advanced
7. Zet Logout response binding op Redirect
8. Configureer een Custom SP issuer, de issuer mag optioneel beginnen met https://saml.. De issuer in dit voorbeeld is https://saml.foxids.com/test-corp/context-handler-test/
9. Zet optioneel Certificate validation mode op Chain trust als het OCES3 root certificaat op je platform wordt vertrouwd Zet Certificate revocation mode op Online
10. Selecteer Yes bij Add logout response location URL in metadata
11. Selecteer Yes bij Include the encryption certificate in metadata
12. Zet NameID format in metadata op urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

13. Klik in Attribute consuming service in metadata op Add attribute consuming service en voeg de Service name toe
14. Voeg alle claims die je wilt ontvangen toe als requested attributes met format urn:oasis:names:tc:SAML:2.0:attrname-format:uri. Zet optioneel elke attribute als required.

De volgende claims worden het vaakst gebruikt:

• 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. Klik in Contact persons in metadata op Add contact person en klik Administrative om een administratieve contactpersoon toe te voegen
16. Klik Update
17. Ga naar de top van de SAML 2.0 authenticatiemethode
18. Zoek de SP-metadata in SAML 2.0 method URL, in dit geval https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
19. De SP-metadata URL wordt gebruikt om een Context Handler gebruikerssysteem (DK: brugervendt system) te configureren.

2 - Ga daarna naar het Context Handler beheerportaal in Test of Productie

1. Selecteer IT-systems (DK: IT-systemer)
2. Klik Add IT-system (DK: Tilslut it-system)
3. Vul de velden in en selecteer User system (DK: Brugervendt system)
4. Ga naar het User system tabblad (DK: Brugervendt system)
5. Selecteer Context Handler met NSIS en verwijder de selectie van Context Handler (zonder NSIS)
6. Selecteer OIOSAML3 als OIOSAML profiel en NSIS niveau
7. Voeg de SP-metadata URL van de SAML 2.0 authenticatiemethode toe, in dit geval https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
8. Vul de rest in, accepteer de voorwaarden en klik Save (DK: Gem)

3 - Voeg privilege claim transformatie toe in FoxIDs Control Client

FoxIDs kan de DK privilege XML claim transformeren naar een JSON claim. Het is aanbevolen om de transformatie toe te voegen om kleinere claims en tokens te krijgen. Daarnaast maakt het tokens leesbaar.

1. Selecteer het tabblad Claim transform
2. Klik Add claim transform en klik DK XML privilege to JSON
3. Klik Update

FoxIDs zet intern SAML 2.0 claims om naar JWT claims. De mapping tussen SAML 2.0 en JWT claims wordt standaard automatisch aangemaakt. Je kunt de mapping vinden en aanpassen in het tabblad Settings.

Je bent klaar. De SAML 2.0 authenticatiemethode kan nu als authenticatiemethode worden gebruikt voor applicatieregistraties in de omgeving.

Een applicatieregistratie geeft alleen toegevoegde claims uit.
Vergeet daarom niet om de JWT claims toe te voegen aan OpenID Connect applicatieregistraties of gebruik de * notatie.

Test Identity Provider configureren voor Context Handler

Deze gids beschrijft hoe je FoxIDs configureert als test Identity Provider voor Context Handler. Context Handler is toegevoegd als SAML 2.0 Relying Party.

Je moet een aparte omgeving gebruiken om plek te hebben voor de testgebruikers en het OCES3 certificaat configureren voordat je deze gids volgt.

1 - Begin met het maken van een SAML 2.0 applicatieregistratie in FoxIDs Control Client

1. Selecteer het tabblad Applications

2. Klik New application

3. Selecteer Show advanced

4. Selecteer Web Application (SAML 2.0)

5. Voeg de Name toe, bijv. Context Handler IdP

6. Download de Context Handler RP metadata waar je endpoints en het te vertrouwen certificaat kunt vinden.
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/metadata.idp
   Het certificaat is base64 gecodeerd en kan worden omgezet naar een .cer certificaatbestand met de FoxIDs certificaat tool.

7. Voeg de Application issuer https://saml.n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime en de metadata toe

8. Voeg de Assertion consumer service (ACS) URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/consume.idp uit de metadata toe

9. Klik Register

10. Lees de Metadata URL en bewaar die voor later

11. Klik Close

12. De detailconfiguratie wordt geopend, selecteer Show advanced rechtsboven in deze configuratiesectie

13. Schakel Absolute ACS URL in

14. Zet Encrypt authn response op Yes

15. Voeg het encryptiecertificaat uit de metadata toe in Encryption certificate

16. Zet NameID format op urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

17. Voeg de Logged out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffresponse.idp uit de metadata toe

18. Voeg de Single logout out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffrequest.idp uit de metadata toe

19. Zet Logout request binding en Logout response binding op redirect

20. Zet de OIOSAML3 claims die aan Context Handler moeten worden uitgegeven in Issue claims

De volgende claims worden het vaakst gebruikt:

• 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. Voeg het signing certificaat uit de metadata toe in Signature validation certificate
22. Zet optioneel Certificate validation mode op Chain trust als het OCES3 root certificaat op je platform wordt vertrouwd Zet Certificate revocation mode op Online
23. Zet Authn response sign type op Sign assertion
24. Configureer een Custom IdP issuer, de issuer mag optioneel beginnen met https://saml.. De issuer in dit voorbeeld is https://saml.foxids.com/test-corp/context-handler-test-idp/
25. Selecteer Yes bij Add logout response location URL in metadata
26. Selecteer Yes bij Include the encryption certificate in metadata
27. Klik in Contact persons in metadata op Add contact person en klik Administrative om een administratieve contactpersoon toe te voegen
28. Klik Update
29. Ga naar de top van de SAML 2.0 applicatiesectie
30. Zoek de test IdP-metadata in SAML 2.0 Metadata, in dit geval https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata
    De test IdP-metadata wordt gebruikt om de Context Handler identity provider te configureren.

2 - Ga daarna naar het Context Handler beheerportaal in Test

1. Selecteer IT-systems (DK: IT-systemer)
2. Klik Add IT-system (DK: Tilslut it-system)
3. Vul de velden in en selecteer Identity Provider
4. Ga naar het Identity Provider tabblad
5. Selecteer Context Handler met NSIS en verwijder de selectie van Context Handler (zonder NSIS)
6. Selecteer OIOSAML3 als OIOSAML profiel en NSIS niveau
7. Voeg de test IdP-metadata URL toe, in dit geval https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata.
8. Vul de rest in, accepteer de voorwaarden en klik Save (DK: Gem)

Je moet in de testomgeving geregistreerd zijn als je eigen testautoriteit (DK: egen test myndighed) om een federatieovereenkomst toe te voegen. Een federatieovereenkomst (DK: føderationsaftaler) is vereist om de identity provider in Context Handler te activeren.

3 - Voeg claimtransformatie toe in FoxIDs Control Client

Maak de claims die aan Context Handler moeten worden uitgegeven in claim transforms.

1. Ga terug naar de SAML 2.0 applicatie Context Handler IdP
2. Selecteer het tabblad Claim transforms
3. Voeg een Constant claim https://data.gov.dk/model/core/specVersion toe met waarde OIO-SAML-3.0
4. Voeg een Constant claim https://data.gov.dk/model/core/kombitSpecVer toe met waarde 2.0
5. Voeg een Constant levels of assurance (loa) claim toe https://data.gov.dk/concept/core/nsis/loa met bijv. de waarde Substantial of lees de claim via de claims pipeline

6. Voeg een Concatenated claim toe om de NameID http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier claim te vervangen met een concatenatie van het CVR-nummer, display name en unieke user ID
7. Selecteer Action Replace claim
8. Concateneer 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. Zet de Concatenate format string op C=DK,O={0},CN={1} {2},Serial={3}
10. Klik Update

4 - Voeg SAML 2.0 claim naar JWT claim mappings toe in FoxIDs Control Client

FoxIDs zet intern SAML 2.0 claims om naar JWT claims. Context Handler gebruikt een door OIOSAML3 gedefinieerde set SAML 2.0 claims waarvoor overeenkomstige JWT mappings moeten worden toegevoegd in de omgeving.

1. Ga naar het tabblad Settings en Claim mappings
2. Klik Add claim mapping voor alle claims die in stap 1.20 zijn geconfigureerd, je kunt eigen korte JWT claimnamen maken als er geen standaard naam bestaat (of de claim mappings bewerken als ze al bestaan)
3. Klik Update

5 - Voeg testgebruikers toe in FoxIDs Control Client

Je kunt testgebruikers toevoegen met testclaims in het tabblad Users en het subtabblad Internal Users.

Testclaims op testgebruikers zijn JWT-gebaseerd en gemapt naar SAML 2.0 claims.

Elke testgebruiker moet een CVR cvr claim, given name given_name claim, family name family_name claim en optioneel een privilege claim met een base64 gecodeerde DK privilege XML string waarde hebben.

Als de gebruiker de Job function role (DK: Jobfunktionsrolle) http://foxids.com/roles/jobrole/test-corp-admin_access/1 moet hebben, zou de DK privilege XML er zo uitzien (met test CVR nummer: 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>