Forbind Context Handler / FKA med SAML 2.0

FoxIDs kan forbindes til Context Handler med en SAML 2.0 autentifikationsmetode.

Context Handler er en dansk identity broker, der forbinder de danske kommuner i en fælles føderation, på dansk Fælleskommunal Adgangsstyring (FKA).

Context Handler er forbundet som en SAML 2.0 Identity Provider (IdP) baseret på OIOSAML 3 og OCES3 (RSASSA-PSS).

Ved at konfigurere en SAML 2.0 autentifikationsmetode og en OpenID Connect applikationsregistrering bliver FoxIDs en bridge mellem SAML 2.0 og OpenID Connect. FoxIDs håndterer derefter SAML 2.0 forbindelsen som Relying Party (RP) / Service Provider (SP), og du behøver kun at forholde dig til OpenID Connect i din applikation. Om nødvendigt kan du vælge flere loginmuligheder (autentifikationsmetoder) fra samme OpenID Connect applikationsregistrering.

I test kan du logge ind med FoxIDs test IdP.

Eller konfigurer et FoxIDs miljø som test Identity Provider for Context Handler med en SAML 2.0 applikationsregistrering og autentificér testbrugere.

Context Handler kan konfigureres baseret på enten OIOSAML 2 eller OIOSAML 3 med OCES3 (RSASSA-PSS), og FoxIDs understøtter desuden de krævede certifikater, og det er muligt at understøtte NSIS.

Du kan teste Context Handler login med online web app sample (sample docs) ved at klikke Log in og derefter Danish Context Handler TEST for testmiljøet (vælg FoxIDs - test-corp på Context Handler login siden) eller Danish Context Handler for produktion.
Se Context Handler eksempelkonfigurationen i FoxIDs Control: https://control.foxids.com/test-corp
Få read adgang med brugeren reader@foxids.com og adgangskoden gEh#V6kSw og vælg context-handler, context-handler-test eller context-handler-idp-test miljøet.
Eksemplet er konfigureret med separate miljøer for Context Handler SAML 2.0 integrationen.

Context Handler / FKA dokumentation:

• Context Handler guide.
• Administrationsportal
  • Test
  • Production
• Context Handler test applikation

Transformér DK privilege XML claim til en JSON claim.

Separat miljø

Context Handler kræver at hver forbindelse i et miljø (test eller produktion) bruger et unikt OCES3 certifikat.
Overvej derfor at forbinde Context Handler i separate miljøer hvor OCES3 certifikater kan konfigureres.

Opret et nyt miljø i FoxIDs Control Client:

1. Find Environments sektionen øverst i midten
2. Klik på drop-down
3. Klik New environment
4. Tilføj Name
5. Klik Create

Hvis du både konfigurerer et test og et produktion miljø, bør de placeres i separate miljøer. Hvis du konfigurerer en test Identity Provider for Context Handler, bør den også placeres i et separat miljø og have et unikt OCES3 certifikat.

Du kan nemt forbinde to miljøer i samme tenant med en Environment Link.

Certifikat

Context Handler kræver at alle requests (authn og logout) er signeret med produktion OCES3 certifikater i alle miljøer.
Det er IKKE muligt at bruge et certifikat udstedt af en anden certifikatautoritet, et self-signed certifikat eller test OCES3 certifikater.

Et OCES3 certifikat er gyldigt i tre år. Derefter skal det opdateres manuelt.

Tilføj .P12 OCES3 certifikatet i FoxIDs Control Client:

1. Vælg (eller opret) et separat miljø som skal bruges for Context Handler som Identity Provider eller en test Identity Provider for Context Handler
2. Vælg fanen Certificates
3. Hvis ikke konfigureret for container certifikater. Klik pilen ned på Swap certificate knappen og klik derefter i sektionen Contained certificates på Change container type
4. Klik på det primære certifikat
5. Tilføj adgangskoden i Optional certificate password
6. Upload .P12 OCES3 certifikatet

Det er efterfølgende muligt at tilføje et sekundært certifikat og at skifte mellem det primære og sekundære certifikat.

Konfigurér Context Handler som Identity Provider

Denne guide beskriver hvordan du opsætter Context Handler som en SAML 2.0 Identity Provider og overholder OIOSAML3.

Du skal konfigurere OCES3 certifikatet før du følger denne guide.

1 - Start med at oprette en SAML 2.0 autentifikationsmetode i FoxIDs Control Client

1. Vælg fanen Authentication
2. Klik New authentication og derefter Identity Provider (SAML 2.0)
3. Tilføj Name fx Context Handler
4. Tilføj Context Handler IdP metadata i Metadata URL feltet
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2/metadata.idp
   Production metadata: https://n2adgangsstyring.stoettesystemerne.dk/runtime/saml2/metadata.idp
5. Klik Create

6. Vælg Show advanced
7. Sæt Logout response binding til Redirect
8. Konfigurer en Custom SP issuer, issuer kan valgfrit starte med https://saml.. Issuer i dette eksempel er https://saml.foxids.com/test-corp/context-handler-test/
9. Sæt valgfrit Certificate validation mode til Chain trust hvis OCES3 root certifikatet er betroet på din platform Sæt Certificate revocation mode til Online
10. Vælg Yes i Add logout response location URL in metadata
11. Vælg Yes i Include the encryption certificate in metadata
12. Sæt NameID format in metadata til urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

13. I Attribute consuming service in metadata, klik Add attribute consuming service og tilføj Service name
14. Tilføj alle claims du vil modtage som requested attributes med format urn:oasis:names:tc:SAML:2.0:attrname-format:uri. Sæt valgfrit hver attribute som required.

Følgende claims bruges oftest:

• 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. I Contact persons in metadata, klik Add contact person og klik Administrative for at tilføje en administrativ kontaktperson
16. Klik Update
17. Gå til toppen af SAML 2.0 autentifikationsmetoden
18. Find SP-metadata i SAML 2.0 method URL, i dette tilfælde https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
19. SP-metadata URL'en bruges til at konfigurere et Context Handler brugervendt system (DK: brugervendt system).

2 - Gå derefter til Context Handler administrationsportalen i Test eller Production

1. Vælg IT-systems (DK: IT-systemer)
2. Klik Add IT-system (DK: Tilslut it-system)
3. Udfyld felterne og vælg User system (DK: Brugervendt system)
4. Gå til User system fanen (DK: Brugervendt system)
5. Vælg Context Handler med NSIS og fjern valget af Context Handler (uden NSIS)
6. Vælg OIOSAML3 som OIOSAML profil og NSIS niveau
7. Tilføj SAML 2.0 autentifikationsmetodens SP-metadata URL, i dette tilfælde https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
8. Udfyld resten, accepter vilkårene og klik Save (DK: Gem)

3 - Tilføj privilege claim transform i FoxIDs Control Client

FoxIDs kan transformere DK privilege XML claim til en JSON claim. Det anbefales at tilføje transformationen for at få mindre claims og tokens. Derudover gør det tokens læsbare.

1. Vælg fanen Claim transform
2. Klik Add claim transform og klik DK XML privilege to JSON
3. Klik Update

FoxIDs konverterer internt SAML 2.0 claims til JWT claims. Mappingen mellem SAML 2.0 og JWT claims oprettes automatisk som standard. Du kan finde og ændre mappingen i fanen Settings.

Du er færdig. SAML 2.0 autentifikationsmetoden kan nu bruges som autentifikationsmetode for applikationsregistreringer i miljøet.

En applikationsregistrering vil kun udstede tilføjede claims.
Husk derfor at tilføje JWT claims til OpenID Connect applikationsregistreringer eller brug * notation.

Konfigurér test Identity Provider for Context Handler

Denne guide beskriver hvordan du konfigurerer FoxIDs som en test Identity Provider for Context Handler. Context Handler tilføjes som en SAML 2.0 Relying Party.

Du skal bruge et separat miljø til at have et sted til testbrugere og konfigurere OCES3 certifikatet før du følger denne guide.

1 - Start med at oprette en SAML 2.0 applikationsregistrering i FoxIDs Control Client

1. Vælg fanen Applications

2. Klik New application

3. Vælg Show advanced

4. Vælg Web Application (SAML 2.0)

5. Tilføj Name fx Context Handler IdP

6. Download Context Handler RP metadata hvor du kan finde endpoints og certifikatet der skal betros.
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/metadata.idp
   Certifikatet er base64 kodet og kan konverteres til en .cer certifikatfil med FoxIDs certifikatværktøj.

7. Tilføj Application issuer https://saml.n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime og metadata

8. Tilføj Assertion consumer service (ACS) URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/consume.idp fra metadata

9. Klik Register

10. Læs Metadata URL og gem den til senere

11. Klik Close

12. Den detaljerede konfiguration åbner, vælg Show advanced øverst til højre i denne konfigurationssektion

13. Aktivér Absolute ACS URL

14. Sæt Encrypt authn response til Yes

15. Tilføj krypteringscertifikatet fra metadata i Encryption certificate

16. Sæt NameID format til urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

17. Tilføj Logged out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffresponse.idp fra metadata

18. Tilføj Single logout out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffrequest.idp fra metadata

19. Sæt Logout request binding og Logout response binding til redirect

20. Sæt OIOSAML3 claims som skal udstedes til Context Handler i Issue claims

Følgende claims bruges oftest:

• 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. Tilføj signing certifikatet fra metadata i Signature validation certificate
22. Sæt valgfrit Certificate validation mode til Chain trust hvis OCES3 root certifikatet er betroet på din platform Sæt Certificate revocation mode til Online
23. Sæt Authn response sign type til Sign assertion
24. Konfigurer en Custom IdP issuer, issuer kan valgfrit starte med https://saml.. Issuer i dette eksempel er https://saml.foxids.com/test-corp/context-handler-test-idp/
25. Vælg Yes i Add logout response location URL in metadata
26. Vælg Yes i Include the encryption certificate in metadata
27. I Contact persons in metadata, klik Add contact person og klik Administrative for at tilføje en administrativ kontaktperson
28. Klik Update
29. Gå til toppen af SAML 2.0 applikationssektionen
30. Find test IdP-metadata i SAML 2.0 Metadata, i dette tilfælde https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata
    Test IdP-metadata bruges til at konfigurere Context Handler identity provider.

2 - Gå derefter til Context Handler administrationsportalen i Test

1. Vælg IT-systems (DK: IT-systemer)
2. Klik Add IT-system (DK: Tilslut it-system)
3. Udfyld felterne og vælg Identity Provider
4. Gå til Identity Provider fanen
5. Vælg Context Handler med NSIS og fjern valget af Context Handler (uden NSIS)
6. Vælg OIOSAML3 som OIOSAML profil og NSIS niveau
7. Tilføj test IdP-metadata URL'en, i dette tilfælde https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata.
8. Udfyld resten, accepter vilkårene og klik Save (DK: Gem)

Du skal være registreret som egen testmyndighed (DK: egen test myndighed) i testmiljøet for at tilføje en føderationsaftale. En føderationsaftale (DK: føderationsaftaler) er nødvendig for at aktivere identity provider i Context Handler.

3 - Tilføj claim transformation i FoxIDs Control Client

Opret claims som skal udstedes til Context Handler i claim transforms.

1. Gå tilbage til SAML 2.0 applikationen Context Handler IdP
2. Vælg fanen Claim transforms
3. Tilføj en Constant claim https://data.gov.dk/model/core/specVersion med værdien OIO-SAML-3.0
4. Tilføj en Constant claim https://data.gov.dk/model/core/kombitSpecVer med værdien 2.0
5. Tilføj en Constant levels of assurance (loa) claim https://data.gov.dk/concept/core/nsis/loa med fx værdien Substantial eller læs claimen via claims pipeline

6. Tilføj en Concatenated claim for at erstatte NameID http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier claimen med en sammenkædet version af CVR nummer, display name og unik bruger ID
7. Vælg Action Replace claim
8. Sammensæt 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. Sæt Concatenate format string til C=DK,O={0},CN={1} {2},Serial={3}
10. Klik Update

4 - Tilføj SAML 2.0 claim til JWT claim mappings i FoxIDs Control Client

FoxIDs konverterer internt SAML 2.0 claims til JWT claims. Context Handler bruger et OIOSAML3 defineret sæt af SAML 2.0 claims hvor tilsvarende JWT mappings skal tilføjes i miljøet.

1. Gå til Settings fanen og Claim mappings
2. Klik Add claim mapping for alle claims konfigureret i trin 1.20, du kan oprette dine egne korte JWT claimnavne hvis der ikke findes et standardnavn (eller redigere claim mappings hvis de allerede findes)
3. Klik Update

5 - Tilføj testbrugere i FoxIDs Control Client

Du kan tilføje testbrugere med testclaims i Users fanen og under Internal Users.

Testclaims på testbrugere er JWT-baserede og mappet til SAML 2.0 claims.

Hver testbruger skal have en CVR cvr claim, given name given_name claim, family name family_name claim og valgfrit en privilege claim med en base64 kodet DK privilege XML strengværdi.

Hvis brugeren skal have Job funktionsrolle (DK: Jobfunktionsrolle) http://foxids.com/roles/jobrole/test-corp-admin_access/1 vil DK privilege XML være (med 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>