Koble til Context Handler / FKA med SAML 2.0

FoxIDs kan kobles til Context Handler med en SAML 2.0 autentiseringsmetode.

Context Handler er en dansk identitetsmegler som kobler de danske kommunene i en felles føderasjon, på dansk kalt Fælleskommunal Adgangsstyring (FKA).

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

Ved å konfigurere en SAML 2.0 autentiseringsmetode og en OpenID Connect applikasjonsregistrering blir FoxIDs en bro mellom SAML 2.0 og OpenID Connect. FoxIDs håndterer deretter SAML 2.0 tilkoblingen som en Relying Party (RP) / Service Provider (SP) og du trenger bare å forholde deg til OpenID Connect i applikasjonen din. Om nødvendig kan du velge flere innloggingsalternativer (autentiseringsmetoder) fra samme OpenID Connect applikasjonsregistrering.

I test kan du logge inn med FoxIDs test IdP.

Eller konfigurer et FoxIDs miljø som en test Identity Provider for Context Handler med en SAML 2.0 applikasjonsregistrering og autentiser testbrukere.

Context Handler kan konfigureres basert på enten OIOSAML 2 eller OIOSAML 3 med OCES3 (RSASSA-PSS) og FoxIDs støtter i tillegg de nødvendige sertifikatene og det er mulig å støtte NSIS.

Du kan teste Context Handler innlogging med online web app sample (sample docs) ved å klikke Log in og deretter Danish Context Handler TEST for testmiljøet (velg FoxIDs - test-corp på Context Handler innloggingssiden) eller Danish Context Handler for produksjon.
Ta en titt på Context Handler eksempelkonfigurasjonen i FoxIDs Control: https://control.foxids.com/test-corp
Få lesetilgang med brukeren reader@foxids.com og passordet gEh#V6kSw og velg miljøet context-handler, context-handler-test eller context-handler-idp-test.
Eksempelet er konfigurert med separate miljøer for Context Handler SAML 2.0 integrasjonen.

Context Handler / FKA dokumentasjon:

• Context Handler guide.
• Administrasjonsportal
  • Test
  • Produksjon
• Context Handler testapplikasjon

Transformer DK privilege XML kravet til et JSON krav.

Separate miljø

Context Handler krever at hver tilkobling i et miljø (test eller produksjon) bruker et unikt OCES3 sertifikat.
Derfor bør du vurdere å koble Context Handler i separate miljøer der OCES3 sertifikatene kan konfigureres.

Opprett et nytt miljø i FoxIDs Control Client:

1. Finn seksjonen Environments øverst i midten
2. Klikk nedtrekksmenyen
3. Klikk New environment
4. Legg til Name
5. Klikk Create

Hvis du konfigurerer både test og produksjonsmiljø, bør de plasseres i separate miljøer. Hvis du konfigurerer en test Identity Provider for Context Handler, bør den også plasseres i et separat miljø og ha et unikt OCES3 sertifikat.

Du kan enkelt koble to miljøer i samme tenant med en Environment Link.

Sertifikat

Context Handler krever at alle forespørsler (authn og logout) signeres med produksjon OCES3 sertifikater i alle miljøer. Det er IKKE mulig å bruke et sertifikat utstedt av en annen sertifikatutsteder, et selvsignert sertifikat eller test OCES3 sertifikater.

Et OCES3 sertifikat er gyldig i tre år. Etter det må det oppdateres manuelt.

Legg til .P12 OCES3 sertifikatet i FoxIDs Control Client:

1. Velg (eller opprett) et separat miljø som skal brukes for Context Handler som Identity Provider eller en test Identity Provider for Context Handler
2. Velg fanen Certificates
3. Hvis det ikke er konfigurert for containerte sertifikater. Klikk pilen ned på Swap certificate knappen og klikk deretter Change container type i seksjonen Contained certificates
4. Klikk på primærsertifikatet 5, Legg til passordet i Optional certificate password
5. Last opp .P12 OCES3 sertifikatet

Det er deretter mulig å legge til et sekundært sertifikat og bytte mellom primært og sekundært sertifikat.

Konfigurer Context Handler som Identity Provider

Denne veiledningen beskriver hvordan du setter opp Context Handler som en SAML 2.0 Identity Provider og oppfyller OIOSAML3.

Du må konfigurere OCES3 sertifikatet før du følger denne veiledningen.

1 - Start med å opprette en SAML 2.0 autentiseringsmetode i FoxIDs Control Client

1. Velg fanen Authentication
2. Klikk New authentication og deretter Identity Provider (SAML 2.0)
3. Legg til Name f.eks. Context Handler
4. Legg til Context Handler IdP metadata i feltet Metadata URL
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2/metadata.idp
   Produksjon metadata: https://n2adgangsstyring.stoettesystemerne.dk/runtime/saml2/metadata.idp
5. Klikk Create

6. Velg Show advanced
7. Sett Logout response binding til Redirect
8. Konfigurer en Custom SP issuer, issuer kan eventuelt starte med https://saml. Issuer i dette eksempelet er https://saml.foxids.com/test-corp/context-handler-test/
9. Valgfritt sett Certificate validation mode til Chain trust hvis OCES3 rotsertifikatet er betrodd på plattformen din Sett Certificate revocation mode til Online
10. Velg Yes i Add logout response location URL in metadata
11. Velg Yes i Include the encryption certificate in metadata
12. Sett NameID format in metadata til urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

13. I Attribute consuming service in metadata, klikk Add attribute consuming service og legg til Service name
14. Legg til alle kravene du vil motta som forespurte attributter med formatet urn:oasis:names:tc:SAML:2.0:attrname-format:uri. Eventuelt sett hvert attributt som påkrevd.

Følgende krav brukes 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, klikk Add contact person og klikk Administrative for å legge til en administrativ kontaktperson
16. Klikk Update
17. Gå til toppen av SAML 2.0 autentiseringsmetoden
18. Finn SP metadata i SAML 2.0 method URL, i dette tilfellet https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
19. SP metadata URL brukes for å konfigurere et Context Handler brukersystem (DK: brugervendt system).

2 - Gå deretter til Context Handler administrasjonsportalen i Test eller Produksjon

1. Velg IT systems (DK: IT-systemer)
2. Klikk Add IT-system (DK: Tilslut it-system)
3. Fyll ut feltene og velg User system (DK: Brugervendt system)
4. Gå til User system fanen (DK: Brugervendt system)
5. Velg Context Handler med NSIS og fjern valget av Context Handler (uten NSIS)
6. Velg OIOSAML3 som OIOSAML profil og NSIS nivå
7. Legg til SAML 2.0 autentiseringsmetode SP metadata URL, i dette tilfellet https://foxids.com/test-corp/context-handler-test/(g9ey6lfw)/saml/spmetadata.
8. Fyll ut resten, godta vilkårene og klikk Save (DK: Gem)

3 - Legg til privilege krav transformasjon i FoxIDs Control Client

FoxIDs kan transformere DK privilege XML kravet til et JSON krav. Det anbefales å legge til transformasjonen for å få mindre krav og tokens. Videre gjør det tokenene lesbare.

1. Velg fanen Claim transform
2. Klikk Add claim transform og klikk DK XML privilege to JSON
3. Klikk Update

FoxIDs konverterer internt SAML 2.0 krav til JWT krav. Mappingen mellom SAML 2.0 og JWT krav opprettes automatisk som standard. Du kan finne og endre mappingen i fanen Settings.

Du er ferdig. SAML 2.0 autentiseringsmetoden kan nå brukes som autentiseringsmetode for applikasjonsregistreringer i miljøet.

En applikasjonsregistrering vil bare utstede krav som er lagt til.
Derfor må du huske å legge til JWT krav til OpenID Connect applikasjonsregistreringer eller bruke * notasjonen.

Konfigurer test identitetsleverandør for Context Handler

Denne veiledningen beskriver hvordan du konfigurerer FoxIDs som en test Identity Provider for Context Handler. Context Handler legges til som en SAML 2.0 Relying Party.

Du må bruke et separat miljø for å ha et sted for testbrukerne og for å konfigurere OCES3 sertifikatet før du følger denne veiledningen.

1 - Start med å opprette en SAML 2.0 applikasjonsregistrering i FoxIDs Control Client

1. Velg fanen Applications

2. Klikk New application

3. Velg Show advanced

4. Velg Web Application (SAML 2.0)

5. Legg til Name f.eks. Context Handler IdP

6. Last ned Context Handler RP metadata der du finner endepunkter og sertifikatet som skal stoles på.
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/metadata.idp
   Sertifikatet er base64 kodet og kan konverteres til en sertifikatfil .cer med FoxIDs certificate tool.

7. Legg til Application issuer https://saml.n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime og metadataene

8. Legg til Assertion consumer service (ACS) URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/consume.idp fra metadataene

9. Klikk Register

10. Les Metadata URL og lagre den til senere

11. Klikk Close

12. Den detaljerte konfigurasjonen åpnes, velg Show advanced øverst til høyre i denne konfigurasjonsseksjonen

13. Aktiver Absolute ACS URL

14. Sett Encrypt authn response til Yes

15. Legg til krypteringssertifikatet fra metadataene i Encryption certificate

16. Sett NameID format til urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

17. Legg til Logged out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffresponse.idp fra metadataene

18. Legg til Single logout out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffrequest.idp fra metadataene

19. Sett Logout request binding og Logout response binding til redirect

20. Sett OIOSAML3 kravene som skal utstedes til Context Handler i Issue claims

Følgende krav brukes 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. Legg til signeringssertifikatet fra metadataene i Signature validation certificate
22. Valgfritt Certificate validation mode til Chain trust hvis OCES3 rotsertifikatet er betrodd på plattformen din Sett Certificate revocation mode til Online
23. Sett Authn response sign type til Sign assertion
24. Konfigurer en Custom IdP issuer, issuer kan eventuelt starte med https://saml. Issuer i dette eksempelet https://saml.foxids.com/test-corp/context-handler-test-idp/
25. Velg Yes i Add logout response location URL in metadata
26. Velg Yes i Include the encryption certificate in metadata
27. I Contact persons in metadata, klikk Add contact person og klikk Administrative for å legge til en administrativ kontaktperson
28. Klikk Update
29. Gå til toppen av SAML 2.0 applikasjonsseksjonen
30. Finn test IdP metadata i SAML 2.0 Metadata, i dette tilfellet https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata
    Test IdP metadata brukes for å konfigurere Context Handler identitetsleverandør.

2 - Gå deretter til Context Handler administrasjonsportalen i Test

1. Velg IT systems (DK: IT-systemer)
2. Klikk Add IT-system (DK: Tilslut it-system)
3. Fyll ut feltene og velg Identity Provider
4. Gå til Identity Provider fanen
5. Velg Context Handler med NSIS og fjern valget av Context Handler (uten NSIS)
6. Velg OIOSAML3 som OIOSAML profil og NSIS nivå
7. Legg til test IdP metadata URL, i dette tilfellet https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata.
8. Fyll ut resten, godta vilkårene og klikk Save (DK: Gem)

Du må være registrert som egen testmyndighet (DK: egen test myndighed) i testmiljøet for å legge til en føderasjonsavtale. En føderasjonsavtale (DK: føderationsaftaler) er nødvendig for å aktivere identitetsleverandøren i Context Handler.

3 - Legg til kravtransformasjon i FoxIDs Control Client

Opprett kravene som skal utstedes til Context Handler i claim transforms.

1. Gå tilbake til SAML 2.0 applikasjonen Context Handler IdP
2. Velg fanen Claim transforms
3. Legg til et Constant krav https://data.gov.dk/model/core/specVersion med verdien OIO-SAML-3.0
4. Legg til et Constant krav https://data.gov.dk/model/core/kombitSpecVer med verdien 2.0
5. Legg til et Constant nivå for assurance (loa) krav https://data.gov.dk/concept/core/nsis/loa med f.eks. verdien Substantial eller les kravet gjennom claims pipeline

6. Legg til et Concatenated krav for å erstatte NameID http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier kravet som en sammenkjedet versjon av CVR nummeret, visningsnavn og unik bruker ID
7. Velg Action Replace claim
8. Sett sammen kravene:
   • 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. Sett Concatenate format string til C=DK,O={0},CN={1} {2},Serial={3}
10. Klikk Update

4 - Legg til SAML 2.0 krav til JWT krav mappinger i FoxIDs Control Client

FoxIDs konverterer internt SAML 2.0 krav til JWT krav. Context Handler bruker et OIOSAML3 definert sett av SAML 2.0 krav hvor tilsvarende JWT mappinger må legges til i miljøet.

1. Gå til Settings fanen og Claim mappings
2. Klikk Add claim mapping for alle kravene konfigurert i trinn 1.20, du kan opprette dine egne korte JWT kravnavn hvis det ikke finnes et standardnavn (eller rediger claim mappings hvis de allerede finnes)
3. Klikk Update

5 - Legg til testbrukere i FoxIDs Control Client

Du kan legge til testbrukere med testkrav i fanen Users og underfanen Internal Users.

Testkrav på testbrukere er JWT basert og mappet til SAML 2.0 krav.

Hver testbruker må ha et CVR cvr krav, et fornavn given_name krav, et etternavn family_name krav og eventuelt et privilege krav med en base64 kodet DK privilege XML strengverdi.

Hvis brukeren skal ha jobbfunksjonsrollen (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>