Connect to Context Handler / FKA with SAML 2.0 (Template)

Connect FoxIDs to Context Handler with the Context Handler / FKA SAML 2.0 authentication method template. The template configures OIOSAML 3 for the Context Handler test or production environment.

Context Handler is the Danish identity broker for municipal federation, called Fælleskommunal Adgangsstyring (FKA).

Combine the authentication method with an OpenID Connect application registration to let FoxIDs bridge SAML 2.0 to OpenID Connect. Applications select the Context Handler authentication method and receive the configured claims.

In the Context Handler test environment, you can sign in with the FoxIDs test IdP or through other test municipalities. You can also configure your own FoxIDs test Identity Provider using a manually configured SAML application registration.

You can try Context Handler with the online web app sample by selecting Log in and Danish Context Handler TEST or Danish Context Handler. In test, select FoxIDs - test-corp on the Context Handler login page. Explore the configuration in FoxIDs Control: test-corp. The reader email address and password are shown on the sign-in page. Select the context-handler, context-handler-test or context-handler-idp-test environment.

Separate environments

Use separate FoxIDs environments for Context Handler test and production. Each connection needs its own production OCES3 certificate, including the test connection. Follow KOMBIT's certificate guidance and use a unique certificate for each registered system and environment.

The certificate belongs to the entire FoxIDs environment. Uploading a certificate through the template changes the environment's signing certificate and can affect other connections. Connect the dedicated environments to your application environment with Environment Links.

To create an environment, open the Environments selector in FoxIDs Control Client, click New environment, enter a name and click Create.

A test Identity Provider for Context Handler also belongs in its own environment with a unique production OCES3 certificate.

Create the Context Handler authentication method

1. Select the dedicated FoxIDs environment and open Authentication.

2. Click New authentication and select Connect to Context Handler / FKA.

   

3. Enter a name, for example Context Handler test.

4. Select Context Handler environment: Test or Production.

   

5. Both test and production require a production OCES3 certificate with its private key, available through the certificate administration. The template reuses a matching certificate from the environment. Otherwise, upload your certificate (.p12), enter its password and click Read and use certificate.

   Select Change certificate to choose another certificate. A certificate type warning indicates that a production OCES3 certificate is expected; you can still save the uploaded certificate. Expired certificates are shown in red and require a valid replacement. The selected certificate is applied when you click Create or Update.

   To manage the certificate on the environment's Certificates tab instead, enable Show advanced and disable Update the environment certificate.

   

6. Review the attributes and privileges and enter the name of your own service in Service name in metadata. This required name is included in the SP metadata shared with Context Handler.

7. Add an administrative contact person, including company and email address.

   

8. Click Create.

The selected environment supplies the IdP metadata URL:

FoxIDs uses automatic metadata updates with a 24-hour update interval, including updates to Context Handler's signing certificates. The URLs are published in KOMBIT's Context Handler documentation.

Attributes and privileges

The template requests and forwards these attributes:

• 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

See the Context Handler OIOSAML 3 attribute profile for details about the supported attributes.

Request CPR attribute is available under Show advanced and disabled by default. Enable it to request and forward https://data.gov.dk/model/core/eid/cprNumber when your application needs it. The attributes actually returned depend on the Context Handler connection and upstream identity provider.

DK XML privilege to JSON is enabled by default. It converts the received privilege XML into readable JSON using the DK privilege transformation. Disable it to forward the original privilege claim. This does not change the roles assigned in Context Handler.

FoxIDs maps SAML claims to JWT claims for OpenID Connect applications. Configure the application's issued claims to include the required mapped claims; see claims. For example, the privilege claim is mapped to privileges_intermediate.

Register the user system in Context Handler

1. Open the Context Handler administration portal for test or production.
2. Select IT-systems (IT-systemer) and Add IT-system (Tilslut it-system).
3. Fill in the system details and select User system (Brugervendt system).
4. On the User system tab, select SAML 2.0.
5. Select the OIOSAML3 profile, the required NSIS level and, optionally, a NIST assurance level.
6. In FoxIDs, copy the SAML 2.0 method URL from Application information at the top of the saved template.
7. Register this URL as the NSIS SAML metadata URL in Context Handler. Use the URL so metadata and certificate changes can be retrieved automatically. The template also offers a metadata download.
8. Complete the remaining fields, accept the terms and save.

See KOMBIT's administration guide for the metadata URL and certificate replacement workflow.

Try the connection

Open the saved authentication method and select Test authentication, then Start the test. In the Context Handler test environment, select the FoxIDs test IdP or another test municipality and sign in with a test user. A successful login returns to the test application with the received claims. You can also try logout and inspect the returned privilege JSON.

Standard SAML configuration

Select Switch to standard SAML settings on a saved authentication method to edit the full SAML configuration. This stops the template's automatic certificate updates. Switching back reapplies its defaults and keeps the saved certificate-update choice.

For the manual configuration steps, see Context Handler / FKA (Legacy standard configuration).

Configuring test Identity Provider for Context Handler

Configuring your own test Identity Provider is optional. You can also sign in through other test municipalities available in the Context Handler test environment.

To configure FoxIDs as your own test Identity Provider, add Context Handler as a SAML 2.0 relying party as described below.

Use a separate environment for your test users. On its Certificates tab, select Contained certificates, upload your unique production OCES3 certificate as the primary certificate and enter its password.

1 - Start by creating a SAML 2.0 application registration in FoxIDs Control Client

1. Select the Applications tab

2. Click New application

3. Select Show advanced

4. Select Web Application (SAML 2.0)

5. Add the Name e.g., Context Handler IdP

6. Download the Context Handler RP metadata where you can find endpoints and the certificate to trust.
   Test metadata: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/metadata.idp?samlprofile=nemlogin3
   The certificate is base64 encoded and can be converted into a certificate file .cer with the FoxIDs certificate tool.

7. Add the Application issuer https://saml.n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime and the metadata

8. Add the Assertion consumer service (ACS) URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/consume.idp from the metadata

9. Click Register

10. Read the Metadata URL and save it for later

11. Click Close

12. The detailed configuration opens, select Show advanced in the top right corner of this configuration section

13. Enable Absolute ACS URL

14. Set Encrypt authn response to Yes

15. Add the encryption certificate from the metadata in Encryption certificate

16. Set the NameID format to urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

17. Add the Logged out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffresponse.idp from the metadata

18. Add the Single logout out URL https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2auth/signoffrequest.idp from the metadata

19. Set the Logout request binding and the Logout response binding to redirect

20. Set the OIOSAML3 claims which should be issued to Context Handler in Issue claims

The following claims are most often used:

• 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. Add the signing certificate from the metadata in Signature validation certificate
22. Optionally set the Certificate validation mode to Chain trust if the OCES3 root certificate is trusted on your platform Set the Certificate revocation mode to Online
23. Set Authn response sign type to Sign assertion
24. Configure a Custom IdP issuer, the issuer can optionally start with https://saml. The issuer in this example https://saml.foxids.com/test-corp/context-handler-test-idp/
25. Select Yes in Add logout response location URL in metadata
26. Select Yes in Include the encryption certificate in metadata
27. In Contact persons in metadata, click Add contact person and click Administrative to add an administrative contact person
28. Click Update
29. Go to the top of the SAML 2.0 application section
30. Find the test IdP-metadata in SAML 2.0 Metadata, in this case https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata
    The test IdP-metadata is used to configure the Context Handler identity provider.

2 - Then go to the Context Handler administration portal in Test

1. Select IT-systems (DK: IT-systemer)
2. Click Add IT-system (DK: Tilslut it-system)
3. Fill out the fields and select Identity Provider
4. Go to the Identity Provider tab
5. Select Context Handler with NSIS and remove the selection of Context Handler (without NSIS)
6. Select OIOSAML3 as OIOSAML profile and NSIS level
7. Add the test IdP-metadata URL, in this case https://foxids.com/test-corp/context-handler-idp-test/ch-idp(*)/saml/idpmetadata.
8. Fill out the rest, accept the terms and click Save (DK: Gem)

You are required to be registered as your own test authority (DK: egen test myndighed) in the test environment to add a federation agreement. A federation agreement (DK: føderationsaftaler) is required to enable the identity provider in Context Handler.

3 - Add claim transformation in FoxIDs Control Client

Create the claims to issue to Context Handler using claim transforms.

1. Go back to the SAML 2.0 application Context Handler IdP
2. Select the Claim transforms tab
3. Add a Constant claim https://data.gov.dk/model/core/specVersion with the value OIO-SAML-3.0
4. Add a Constant claim https://data.gov.dk/model/core/kombitSpecVer with the value 2.0
5. Add a Constant level of assurance (loa) claim https://data.gov.dk/concept/core/nsis/loa with e.g. the value Substantial or read the claim through the claims pipeline

6. Add a Concatenated claim to replace the NameID http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier with a concatenated version of the CVR number, display name and unique user ID
7. Select Action Replace claim
8. Concatenate 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. Set the Concatenate format string to C=DK,O={0},CN={1} {2},Serial={3}
10. Click Update

4 - Add SAML 2.0 claim to JWT claim mappings in FoxIDs Control Client

FoxIDs internally converts SAML 2.0 claims to JWT claims. Context Handler uses an OIOSAML3 defined set of SAML 2.0 claims where corresponding JWT mappings need to be added in the environment.

1. Go to Settings tab and Claim mappings
2. Click Add claim mapping for all the claims configured in step 1.20, you can create your own short JWT claim names if no standard name exists (or edit the claim mappings if they already exist)
3. Click Update

5 - Add test users in FoxIDs Control Client

Add test users with test claims on the Users tab under Internal Users.

Test claims on test users are JWT based and mapped to SAML 2.0 claims.

Each test user is required to have a CVR cvr claim, given name given_name claim, family name family_name claim and optionally a privilege claim with a base64 encoded DK privilege XML string value.

If the user should have the Job function role (DK: Jobfunktionsrolle) http://foxids.com/roles/jobrole/test-corp-admin_access/1 the DK privilege XML would be (with test CVR number: 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>

Related documentation

• SAML 2.0 authentication method
• OpenID Connect application registration
• SAML 2.0 application registration
• DK privilege transformation
• Environment Links