Anslut Context Handler / FKA med SAML 2.0

FoxIDs kan anslutas till Context Handler med en SAML 2.0 autentiseringsmetod.

Context Handler är en dansk identity broker som kopplar de danska kommunerna i en gemensam federation, på danska Fælleskommunal Adgangsstyring (FKA).

Context Handler är ansluten som en SAML 2.0 Identity Provider (IdP) baserad på OIOSAML 3 och OCES3 (RSASSA-PSS).

Genom att konfigurera en SAML 2.0 autentiseringsmetod och en OpenID Connect applikationsregistrering blir FoxIDs en bridge mellan SAML 2.0 och OpenID Connect. FoxIDs hanterar då SAML 2.0 anslutningen som Relying Party (RP) / Service Provider (SP) och du behöver bara hantera OpenID Connect i din applikation. Vid behov kan du välja flera inloggningsalternativ (autentiseringsmetoder) från samma OpenID Connect applikationsregistrering.

I test kan du logga in med FoxIDs test IdP.

Eller konfigurera en FoxIDs miljö som test Identity Provider för Context Handler med en SAML 2.0 applikationsregistrering och autentisera testanvändare.

Context Handler kan konfigureras baserat på OIOSAML 2 eller OIOSAML 3 med OCES3 (RSASSA-PSS) och FoxIDs stödjer dessutom de nödvändiga certifikaten och det är möjligt att stödja NSIS.

Du kan testa Context Handler inloggning med online web app sample (sample docs) genom att klicka Log in och sedan Danish Context Handler TEST för testmiljön (välj FoxIDs - test-corp på Context Handler inloggningssidan) eller Danish Context Handler för produktion.
Se Context Handler exempelkonfigurationen i FoxIDs Control: https://control.foxids.com/test-corp
Få read access med användaren reader@foxids.com och lösenordet gEh#V6kSw och välj context-handler, context-handler-test eller context-handler-idp-test miljön.
Exemplet är konfigurerat med separata miljöer för Context Handler SAML 2.0 integrationen.

Context Handler / FKA dokumentation:

• Context Handler guide.
• Administrationsportal
  • Test
  • Production
• Context Handler testapplikation

Transformera DK privilege XML claim till en JSON claim.

Separat miljö

Context Handler kräver att varje anslutning i en miljö (test eller produktion) använder ett unikt OCES3 certifikat.
Överväg därför att ansluta Context Handler i separata miljöer där OCES3 certifikat kan konfigureras.

Skapa en ny miljö i FoxIDs Control Client:

1. Hitta sektionen Environments längst upp i mitten
2. Klicka på drop-down
3. Klicka New environment
4. Lägg till Name
5. Klicka Create

Om du konfigurerar både test och produktionsmiljö ska de placeras i separata miljöer. Om du konfigurerar en test Identity Provider för Context Handler bör den också placeras i en separat miljö och ha ett unikt OCES3 certifikat.

Du kan enkelt ansluta två miljöer i samma tenant med en Environment Link.

Certifikat

Context Handler kräver att alla requests (authn och logout) signeras med produktion OCES3 certifikat i alla miljöer.
Det är INTE möjligt att använda ett certifikat utfärdat av en annan certifikatutfärdare, ett self-signed certifikat eller test OCES3 certifikat.

Ett OCES3 certifikat är giltigt i tre år. Därefter måste det uppdateras manuellt.

Lägg till .P12 OCES3 certifikatet i FoxIDs Control Client:

1. Välj (eller skapa) en separat miljö som ska användas för Context Handler som Identity Provider eller en test Identity Provider för Context Handler
2. Välj fliken Certificates
3. Om inte konfigurerad för container certifikat. Klicka pilen ner på Swap certificate knappen och klicka sedan i sektionen Contained certificates på Change container type
4. Klicka på det primära certifikatet
5. Ange lösenordet i Optional certificate password
6. Ladda upp .P12 OCES3 certifikatet

Därefter är det möjligt att lägga till ett sekundärt certifikat och att byta mellan primärt och sekundärt certifikat.

Konfigurera Context Handler som Identity Provider

Denna guide beskriver hur du sätter upp Context Handler som en SAML 2.0 Identity Provider och följer OIOSAML3.

Du måste konfigurera OCES3 certifikatet innan du följer denna guide.

1 - Börja med att skapa en SAML 2.0 autentiseringsmetod i FoxIDs Control Client

1. Välj fliken Authentication
2. Klicka New authentication och sedan Identity Provider (SAML 2.0)
3. Lägg till Name t.ex. Context Handler
4. Lägg till Context Handler IdP metadata i Metadata URL fältet
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2/metadata.idp
   Production metadata: https://n2adgangsstyring.stoettesystemerne.dk/runtime/saml2/metadata.idp
5. Klicka Create

6. Välj Show advanced
7. Sätt Logout response binding till Redirect
8. Konfigurera en Custom SP issuer, issuer kan valfritt börja med https://saml.. Issuer i detta exempel är https://saml.foxids.com/test-corp/context-handler-test/
9. Sätt valfritt Certificate validation mode till Chain trust om OCES3 root certifikatet är betrott på din plattform Sätt Certificate revocation mode till Online
10. Välj Yes i Add logout response location URL in metadata
11. Välj Yes i Include the encryption certificate in metadata
12. Sätt NameID format in metadata till urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

13. I Attribute consuming service in metadata, klicka Add attribute consuming service och lägg till Service name
14. Lägg till alla claims du vill ta emot som requested attributes med format urn:oasis:names:tc:SAML:2.0:attrname-format:uri. Sätt valfritt varje attribute som required.

Följande claims används oftast:

• 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, klicka Add contact person och klicka Administrative för att lägga till en administrativ kontaktperson
16. Klicka Update
17. Gå till toppen av SAML 2.0 autentiseringsmetoden
18. Hitta SP-metadata i SAML 2.0 method URL, i detta fall https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
19. SP-metadata URL används för att konfigurera ett Context Handler användarsystem (DK: brugervendt system).

2 - Gå sedan till Context Handler administrationsportalen i Test eller Production

1. Välj IT-systems (DK: IT-systemer)
2. Klicka Add IT-system (DK: Tilslut it-system)
3. Fyll i fälten och välj User system (DK: Brugervendt system)
4. Gå till User system fliken (DK: Brugervendt system)
5. Välj Context Handler med NSIS och ta bort valet av Context Handler (utan NSIS)
6. Välj OIOSAML3 som OIOSAML profil och NSIS nivå
7. Lägg till SAML 2.0 autentiseringsmetodens SP-metadata URL, i detta fall https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
8. Fyll i resten, acceptera villkoren och klicka Save (DK: Gem)

3 - Lägg till privilege claim transform i FoxIDs Control Client

FoxIDs kan transformera DK privilege XML claim till en JSON claim. Det rekommenderas att lägga till transformationen för att få mindre claims och tokens. Dessutom gör det tokens läsbara.

1. Välj fliken Claim transform
2. Klicka Add claim transform och klicka DK XML privilege to JSON
3. Klicka Update

FoxIDs konverterar internt SAML 2.0 claims till JWT claims. Mappningen mellan SAML 2.0 och JWT claims skapas automatiskt som standard. Du kan hitta och ändra mappningen i fliken Settings.

Du är klar. SAML 2.0 autentiseringsmetoden kan nu användas som autentiseringsmetod för applikationsregistreringar i miljön.

En applikationsregistrering kommer endast att utfärda tillagda claims.
Kom därför ihåg att lägga till JWT claims till OpenID Connect applikationsregistreringar eller använd * notationen.

Konfigurera test Identity Provider för Context Handler

Denna guide beskriver hur du konfigurerar FoxIDs som en test Identity Provider för Context Handler. Context Handler läggs till som en SAML 2.0 Relying Party.

Du måste använda en separat miljö för att ha plats för testanvändare och konfigurera OCES3 certifikatet innan du följer denna guide.

1 - Börja med att skapa en SAML 2.0 applikationsregistrering i FoxIDs Control Client

1. Välj fliken Applications

2. Klicka New application

3. Välj Show advanced

4. Välj Web Application (SAML 2.0)

5. Lägg till Name t.ex. Context Handler IdP

6. Ladda ner Context Handler RP metadata där du kan hitta endpoints och certifikatet att lita på.
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/metadata.idp
   Certifikatet är base64 kodat och kan konverteras till en .cer certifikatfil med FoxIDs certifikatverktyg.

7. Lägg till Application issuer https://saml.n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime och metadata

8. Lägg till Assertion consumer service (ACS) URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/consume.idp från metadata

9. Klicka Register

10. Läs Metadata URL och spara den för senare

11. Klicka Close

12. Den detaljerade konfigurationen öppnas, välj Show advanced uppe till höger i denna konfigurationssektion

13. Aktivera Absolute ACS URL

14. Sätt Encrypt authn response till Yes

15. Lägg till krypteringscertifikatet från metadata i Encryption certificate

16. Sätt NameID format till urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

17. Lägg till Logged out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffresponse.idp från metadata

18. Lägg till Single logout out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffrequest.idp från metadata

19. Sätt Logout request binding och Logout response binding till redirect

20. Sätt OIOSAML3 claims som ska utfärdas till Context Handler i Issue claims

Följande claims används oftast:

• 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. Lägg till signeringscertifikatet från metadata i Signature validation certificate
22. Sätt valfritt Certificate validation mode till Chain trust om OCES3 root certifikatet är betrott på din plattform Sätt Certificate revocation mode till Online
23. Sätt Authn response sign type till Sign assertion
24. Konfigurera en Custom IdP issuer, issuer kan valfritt börja med https://saml.. Issuer i detta exempel är https://saml.foxids.com/test-corp/context-handler-test-idp/
25. Välj Yes i Add logout response location URL in metadata
26. Välj Yes i Include the encryption certificate in metadata
27. I Contact persons in metadata, klicka Add contact person och klicka Administrative för att lägga till en administrativ kontaktperson
28. Klicka Update
29. Gå till toppen av SAML 2.0 applikationssektionen
30. Hitta test IdP-metadata i SAML 2.0 Metadata, i detta fall https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata
    Test IdP-metadata används för att konfigurera Context Handler identity provider.

2 - Gå sedan till Context Handler administrationsportalen i Test

1. Välj IT-systems (DK: IT-systemer)
2. Klicka Add IT-system (DK: Tilslut it-system)
3. Fyll i fälten och välj Identity Provider
4. Gå till Identity Provider fliken
5. Välj Context Handler med NSIS och ta bort valet av Context Handler (utan NSIS)
6. Välj OIOSAML3 som OIOSAML profil och NSIS nivå
7. Lägg till test IdP-metadata URL:en, i detta fall https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata.
8. Fyll i resten, acceptera villkoren och klicka Save (DK: Gem)

Du måste vara registrerad som egen testmyndighet (DK: egen test myndighed) i testmiljön för att lägga till ett federationsavtal. Ett federationsavtal (DK: føderationsaftaler) krävs för att aktivera identity provider i Context Handler.

3 - Lägg till claim transformation i FoxIDs Control Client

Skapa claims som ska utfärdas till Context Handler i claim transforms.

1. Gå tillbaka till SAML 2.0 applikationen Context Handler IdP
2. Välj fliken Claim transforms
3. Lägg till en Constant claim https://data.gov.dk/model/core/specVersion med värdet OIO-SAML-3.0
4. Lägg till en Constant claim https://data.gov.dk/model/core/kombitSpecVer med värdet 2.0
5. Lägg till en Constant levels of assurance (loa) claim https://data.gov.dk/concept/core/nsis/loa med t.ex. värdet Substantial eller läs claimen via claims pipeline

6. Lägg till en Concatenated claim för att ersätta NameID http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier claimen med en sammansatt version av CVR nummer, display name och unik user ID
7. Välj Action Replace claim
8. Sammanfoga 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ätt Concatenate format string till C=DK,O={0},CN={1} {2},Serial={3}
10. Klicka Update

4 - Lägg till SAML 2.0 claim till JWT claim mappings i FoxIDs Control Client

FoxIDs konverterar internt SAML 2.0 claims till JWT claims. Context Handler använder en OIOSAML3 definierad uppsättning SAML 2.0 claims där motsvarande JWT mappings behöver läggas till i miljön.

1. Gå till Settings fliken och Claim mappings
2. Klicka Add claim mapping för alla claims konfigurerade i steg 1.20, du kan skapa egna korta JWT claimnamn om det inte finns ett standardnamn (eller redigera claim mappings om de redan finns)
3. Klicka Update

5 - Lägg till testanvändare i FoxIDs Control Client

Du kan lägga till testanvändare med testclaims i fliken Users och under fliken Internal Users.

Testclaims på testanvändare är JWT-baserade och mappade till SAML 2.0 claims.

Varje testanvändare måste ha en CVR cvr claim, given name given_name claim, family name family_name claim och valfritt en privilege claim med en base64 kodad DK privilege XML strängvärde.

Om användaren ska ha Job funktionsroll (DK: Jobfunktionsrolle) http://foxids.com/roles/jobrole/test-corp-admin_access/1 skulle DK privilege XML vara (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>