Context Handler - kmd-identity/documentation GitHub Wiki

Context Handler is a SAML identity provider (IdP) which is part of the KOMBIT solution called Fælleskommunal Adgangsstyring for brugere.

KMD Identity supports both SAML and OpenID applications that would like to integrate with the Context Handler to authenticate (and authorize) users for their user-facing applications ("Brugervendte systemer").

Why integrate using KMD Identity

Integrating to Context Handler via KMD Identity does not free the individual KMD products from having to register and maintain their IT-system configuration in Serviceplatformen (test / production), so you might be wondering why even use KMD Identity for this integration.

There are three scenarios where it makes sense to use KMD Identity anyway:

1. If you want to use OAuth/OpenID Connect. Because Context Handler only supports direct integrations via SAML.
2. If you need to support multiple IdP's but only want to configure your application to use one. Using KMD Identity, we can act as a broker for multiple IdP's.
3. If you would like to have additional claims that are not present in the response from Context Handler. Using KMD Identity's Custom Claims feature, we can inject additional claims based on the response from your Custom Claims API.

Requirements

To integrate with Context Handler via KMD Identity:

• Your application(s) must be registered with KMD Identity. See the "Get Started" pages for SAML and OpenID applications.

• An app-specific integration to Context Handler must be setup, which can then be enabled for your application. Below are the steps to setup such an integration.

How to get started

Step 1 - Contact KMD Identity and specify:

• Which Context Handler environment you want to integrate with ("Production" or "Ekstern Test").

• EntityId that is going to be used by the "user-facing application" (brugervendt system) in Context Handler. Note that this EntityId must be unique in Context Handler. If possible, we recommend reusing the EntityId of the SAML application that you have registered with KMD Identity. Alternatively (if you are using OpenID) we suggest using our naming convention for SAML applications to generate the EntityId.

• Arrange to send a valid OCES3 certificate to KMD Identity via a secure channel (private key and password included). It will be used for signing and decryption purposes. Note that this certificate must also be unique in Context Handler. For production integrations, a FOCES production certificate must be used. For "Ekstern Test" integrations, FOCES devtest4 certificates must be used.

• The EntityID of the application you have registered with KMD Identity that should be allowed to use this Context Handler integration. For OpenID applications the ClientID, for SAML applications the Relying Party Identifier.

Step 2 - KMD Identity will provide a link to a metadata endpoint.

Step 3 - Using the XML document returned by the metadata endpoint provided in step 2, register a user-facing application on an IT-System in Context Handler.

How to get access to the Context Handlers admin interface

Context Handler IT-systems are managed in what is called the "administrationsmodul" of Serviceplatformen.

To access it you need:

• A MitID Erhverv user with a MitID
• The necessary rights/roles.

To get a MitID Erhverv user, use the standard procedure to make such a request in your organization. The details of which is beyond the scope of this document.

Once you have an employee certificate the next step is to request the roles needed to access the "administrationsmodul".

• Go to https://brugeradministration.nemlog-in.dk/
• Select the “MitID” tab
• Login using your MitID Erhverv users MitID
• Click on “My Profile” to see the list of “User Rights”
• Depending on your specific needs, you must request a subset of the following rights:
  • KOMBIT STS Administrationsmodulet (test) Aftaleadministrator
  • KOMBIT STS Administrationsmodulet (test) Leverandøradministrator
  • KOMBIT STS Administrationsmodulet (test) Organisationsadministrator
  • KOMBIT STS Administrationsmodulet (test) Rolleadministrator
  • KOMBIT STS Administrationsmodulet Leverandøradministrator
  • KOMBIT STS Administrationsmodulet Organisationsadministrator
• The first 4 rights corresponds to their test environment. The last 2 for production environment.
• Here is a link to KOMBIT's documentation which describes the flow from the point of view of the administrator approving the requests. This document also contains descriptions of what each user right/role does.

If you are missing any of the above rights then:

• Click on “Get more rights”
• Expand KOMBIT (Do NOT put a checkmark in KOMBIT, otherwise you’ll try to get access to all the roles).
• Find the rights you are missing and select them (checkbox)
• Write a comment stating why it is you need the rights that you are requesting.
• Click on “Send request”

Once you have the necessary rights, proceed to log-in to Administrationsmodul.

• Test environment: https://exttestwww.serviceplatformen.dk/administration/
  • Click on “Log på” and then “Administrationsmodulet (exttest)”
• Production environment: https://www.serviceplatformen.dk/administration/
  • Click on "Log på" and then “Administrationsmodulet (produktion)”

How to receive user privileges using the integration

You must configure "usersystemroles" (brugersystemroller) on your "user-facing application" (brugervendt system) in Context Handler.

Your customers must configure "jobfunctionroles" (jobfunktionsroller) and map them to the usersystemroles of your IT-System in Context Handler.

When authenticating a user that is assigned to a jobfunctionrole that is mapped to one or more of your usersystemroles, the response will contain a "dk:gov:saml:attribute:Privileges_intermediate" claim that contains the privilege information as a base64 encoded string.

The KOMBIT "Adgangsstyring for brugere" website has a section titled Vejledninger. The "Tilslut brugervendt system" document also includes example code on how to decode the privileges_intermediate claim.