Forbind Context Handler / FKA med SAML 2.0 (Skabelon)

Forbind FoxIDs til Context Handler med skabelonen Context Handler / FKA til en SAML 2.0 autentifikationsmetode. Skabelonen konfigurerer OIOSAML 3 til Context Handlers test- eller produktionsmiljø.

Context Handler er den danske identity broker til kommunal føderation, kaldet Fælleskommunal Adgangsstyring (FKA).

Kombiner autentifikationsmetoden med en OpenID Connect applikationsregistrering, så FoxIDs kan bygge bro fra SAML 2.0 til OpenID Connect. Applikationerne vælger Context Handler autentifikationsmetoden og modtager de konfigurerede claims.

I Context Handlers testmiljø kan du logge ind med FoxIDs test IdP eller via andre testkommuner. Du kan også konfigurere din egen FoxIDs test Identity Provider med en manuelt konfigureret SAML applikationsregistrering.

Du kan prøve Context Handler med online webapp-eksemplet ved at vælge Log in og Danish Context Handler TEST eller Danish Context Handler. I test skal du vælge FoxIDs - test-corp på Context Handlers loginside. Se konfigurationen i FoxIDs Control: test-corp. Reader-e-mailadressen og adgangskoden vises på loginsiden. Vælg miljøet context-handler, context-handler-test eller context-handler-idp-test.

Separate miljøer

Brug separate FoxIDs miljøer til Context Handler test og produktion. Hver forbindelse skal have sit eget OCES3 produktionscertifikat, også testforbindelsen. Følg KOMBITs certifikatvejledning, og brug et unikt certifikat til hvert registreret system og miljø.

Certifikatet tilhører hele FoxIDs miljøet. Upload af et certifikat gennem skabelonen ændrer miljøets signeringscertifikat og kan påvirke andre forbindelser. Forbind de dedikerede miljøer med dit applikationsmiljø via Environment Links.

Opret et miljø ved at åbne Environments i FoxIDs Control Client, klikke på New environment, angive et navn og klikke på Create.

En test Identity Provider til Context Handler hører også til i sit eget miljø med et unikt OCES3 produktionscertifikat.

Opret Context Handler autentifikationsmetoden

1. Vælg det dedikerede FoxIDs miljø, og åbn Authentication.

2. Klik på New authentication, og vælg Connect to Context Handler / FKA.

   

3. Angiv et navn, for eksempel Context Handler test.

4. Vælg Context Handler environment: Test eller Production.

   

5. Både test og produktion kræver et OCES3 produktionscertifikat med privat nøgle, som kan fås gennem certifikatadministrationen. Skabelonen genbruger et matchende certifikat fra miljøet. Ellers skal du uploade dit certifikat (.p12), angive adgangskoden og klikke på Read and use certificate.

   Vælg Change certificate for at vælge et andet certifikat. En advarsel om certifikattypen angiver, at der forventes et OCES3 produktionscertifikat; du kan stadig gemme det uploadede certifikat. Udløbne certifikater vises med rødt og skal erstattes med et gyldigt certifikat. Det valgte certifikat anvendes, når du klikker på Create eller Update.

   Hvis du i stedet vil administrere certifikatet på miljøets fane Certificates, skal du aktivere Show advanced og deaktivere Update the environment certificate.

   

6. Gennemgå attributter og privilegier, og angiv navnet på din egen service i Service name in metadata. Dette obligatoriske navn medtages i de SP metadata, som deles med Context Handler.

7. Tilføj en administrativ kontaktperson med virksomhed og e-mailadresse.

   

8. Klik på Create.

Det valgte miljø angiver IdP metadata-URL'en:

FoxIDs opdaterer automatisk metadata med et interval på 24 timer, herunder Context Handlers signeringscertifikater. URL'erne er offentliggjort i KOMBITs dokumentation til Context Handler.

Attributter og privilegier

Skabelonen anmoder om og videresender disse attributter:

• https://data.gov.dk/model/core/specVersion
• https://data.gov.dk/concept/core/nsis/loa
• dk:gov:saml:attribute:AssuranceLevel
• https://data.gov.dk/model/core/eid/professional/uuid/persistent
• 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/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

Se Context Handler OIOSAML 3 attributprofilen for oplysninger om de understøttede attributter.

Request CPR attribute findes under Show advanced og er deaktiveret som standard. Aktivér den for at anmode om og videresende https://data.gov.dk/model/core/eid/cprNumber, når din applikation har brug for det. De attributter, der faktisk returneres, afhænger af Context Handler forbindelsen og den bagvedliggende identitetsudbyder.

DK XML privilege to JSON er aktiveret som standard. Den konverterer den modtagne privilegie-XML til læsbar JSON med DK privilege transformation. Deaktivér den for at videresende den oprindelige privilegieclaim. Dette ændrer ikke de roller, der er tildelt i Context Handler.

FoxIDs mapper SAML claims til JWT claims for OpenID Connect applikationer. Konfigurer applikationens udstedte claims, så de nødvendige mappede claims medtages; se claims. Privilegieclaimen mappes for eksempel til privileges_intermediate.

Registrer det brugervendte system i Context Handler

1. Åbn Context Handlers administrationsportal til test eller produktion.
2. Vælg IT-systems (IT-systemer) og Add IT-system (Tilslut it-system).
3. Udfyld systemoplysningerne, og vælg User system (Brugervendt system).
4. Vælg SAML 2.0 på fanen User system.
5. Vælg profilen OIOSAML3, det krævede NSIS niveau og eventuelt et NIST sikringsniveau.
6. Kopiér i FoxIDs SAML 2.0 method URL fra Application information øverst i den gemte skabelon.
7. Registrer denne URL som NSIS SAML metadata URL i Context Handler. Brug URL'en, så ændringer i metadata og certifikater kan hentes automatisk. Skabelonen tilbyder også download af metadata.
8. Udfyld de resterende felter, accepter betingelserne, og gem.

Se KOMBITs administrationsvejledning for fremgangsmåden ved metadata-URL og udskiftning af certifikater.

Prøv forbindelsen

Åbn den gemte autentifikationsmetode, og vælg Test authentication og derefter Start the test. Vælg FoxIDs test IdP eller en anden testkommune i Context Handlers testmiljø, og log ind med en testbruger. Et vellykket login vender tilbage til testapplikationen med de modtagne claims. Du kan også prøve logout og undersøge den returnerede privilegie-JSON.

Standardkonfiguration af SAML

Vælg Switch to standard SAML settings på en gemt autentifikationsmetode for at redigere den fulde SAML konfiguration. Dette stopper skabelonens automatiske certifikatopdateringer. Når du skifter tilbage, anvendes standardindstillingerne igen, og det gemte valg for certifikatopdatering bevares.

Se Context Handler / FKA (Legacy standardkonfiguration) for de manuelle konfigurationstrin.

Konfigurér test Identity Provider for Context Handler

Det er valgfrit at konfigurere din egen test Identity Provider. Du kan også logge ind via andre testkommuner, der er tilgængelige i Context Handler testmiljøet.

For at konfigurere FoxIDs som din egen test Identity Provider skal du tilføje Context Handler som en SAML 2.0 relying party som beskrevet nedenfor.

Brug et separat miljø til dine testbrugere. Vælg Contained certificates på miljøets fane Certificates, upload dit unikke OCES3 produktionscertifikat som det primære certifikat, og angiv adgangskoden.

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?samlprofile=nemlogin3 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>

Relateret dokumentation

• SAML 2.0 autentifikationsmetode
• OpenID Connect applikationsregistrering
• SAML 2.0 applikationsregistrering
• DK privilege transformation
• Environment Links