Connect to Context Handler with SAML 2.0
FoxIDs can be connected to Context Handler / Fælleskommunal Adgangsstyring (Danish identity broker) with a SAML 2.0 authentication method. Context Handler is a Danish identity broker connecting the Danish municipalities in a common federation.
Context Handler is connected as a SAML 2.0 Identity Provider (IdP) based on OIOSAML 3 and OCES3 (RSASSA-PSS).
By configuring an SAML 2.0 authentication method and a OpenID Connect application registration FoxIDs become a bridge between SAML 2.0 and OpenID Connect. FoxIDs will then handle the SAML 2.0 connection as a Relying Party (RP) / Service Provider (SP) and you only need to care about OpenID Connect in your application. If needed, you can possibly select multiple login option (authentication methods) from the same OpenID Connect application registration.
In the test environment, FoxIDs can be connected to Context Handler as a test Identity Provider with a SAML 2.0 application registration and authenticate test users. Context Handler is connected as a SAML 2.0 test Relying Party (RP).
Context Handler can be configured based on either OIOSAML 2 or OIOSAML 3 with OCES3 (RSASSA-PSS) and FoxIDs furthermore support the required certificates and it is possible to support NSIS.
You can test Context Handler login with the online web app sample (sample docs) by clicking
Log in
and thenDanish Context Handler TEST
for the test environment (selectFoxIDs - test-corp
on the Context Handler log in page) orDanish Context Handler
for production.
Take a look at the Context Handler sample configuration in FoxIDs Control: https://control.foxids.com/test-corp
Get read access with the user[email protected]
and passwordTestAccess!
then select thecontext-handler
,context-handler-test
orcontext-handler-idp-test
environment.
The sample is configured with a separate environments for the Context Handler SAML 2.0 integration.
Context Handler documentation:
- Context Handler guide.
- Context Handler administration portal
- Context Handler test application
Transform the DK privilege XML claim to a JSON claim.
Separate environment
Context Handler requires each connection in an environment (test or production) to use a unique OCES3 certificate.
Therefore, consider connecting Context Handler in separate environments where the OCES3 certificates can be configured without affecting any other configuration.
If you both configure a test and production environment, they should be placed in separate environments. If you set up a test Relying Party, it should also be placed in a separate environment and have a unique OCES3 certificate.
You can easily connect two environments in the same tenant with a Environment Link.
Certificate
Context Handler requires all requests (authn and logout) to be signed with real production OCES3 certificates in all environments. It is NOT possible to use a certificate issued by another certificate authority, a self-signed certificate or test OCES3 certificates.
A OCES3 certificate is valid for three years. After that, it must be updated manually.
If the
.P12
file fails to load, you can convert it to a.PFX
file with the FoxIDs.ConvertCertificateTool.
Add the .P12
OCES3 certificate in FoxIDs Control Client:
- Select (or create) a separate environment to be used for Context Handler as Identity Provider or test Relying Party
- Select the Certificates tab
- Click the arrow down on the Swap certificate button and then in the Contained certificates section click Change container type
- Then click on the primary certificate, then write the password and upload the
.P12
or.PFX
OCES3 certificate
It is subsequently possible to add a secondary certificate and to swap between the primary and secondary certificates.
Configuring Context Handler as Identity Provider
This guide describe how to setup Context Handler as a SAML 2.0 Identity Provider and comply to OIOSAML3.
You need to configure the OCES3 certificate before following this guide.
1 - Start by creating an SAML 2.0 authentication method in FoxIDs Control Client
- Select the Authentication methods tab
- Click Create authentication method and then SAML 2.0
- Add the name
- Add the Context Handler IdP metadata in the Metadata URL field
Test metadata:https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2/metadata.idp
Production metadata:https://n2adgangsstyring.stoettesystemerne.dk/runtime/saml2/metadata.idp
- Click Create
- Change Logout response binding to Redirect
- Select Show advanced settings
- Configure a custom SP issuer, the issuer can optionally start with
https://saml.
The issuer in this example ishttps://saml.foxids.com/test-corp/context-handler-test/
- Set the certificate revocation mode to
Online
and optionally the validation mode toChain trust
if the OCES3 root certificate is trusted on your platform. The OCES3 root certificate is NOT trusted in Azure. - Select to add logout response location URL in metadata
- Select to include the encryption certificate in metadata
- Set the NameID format in metadata to
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- Add an attribute consuming service in metadata and add the service name.
- Add all the claims you want to receive as requested attributes with the format
urn:oasis:names:tc:SAML:2.0:attrname-format:uri
. Optionally set each attribute as required.
The following claims is most often used:
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
- Add an administrative contact person
- Click Update
- Go to the top of the SAML 2.0 authentication method
- Find the SAML 2.0 authentication method SP-metadata URL, in this case https://foxids.com/test-corp/context-handler-test/(cp-rp)/saml/spmetadata.
- The SP-metadata URL is used to configure a Context Handler user system (DK: brugervendt system).
2 - Then go to the Context Handler administration portal
- Select IT-systems (DK: IT-systemer)
- Click Add IT-system (DK: Tilslut it-system)
- Fill out the fields and select User system (DK: Brugervendt system)
- Go to the User system tab (DK: Brugervendt system)
- Select Context Handler with NSIS and remove the selection of Context Handler (without NSIS)
- Select OIOSAML3 as OIOSAML profile and NSIS level
- Add the SAML 2.0 authentication method SP-metadata URL, in this case
https://foxids.com/test-corp/context-handler-test/(cp-rp)/saml/spmetadata
. - Fill out the rest, accept the terms and click Save (DK: Gem)
3 - Add privilege claim transformation in FoxIDs Control Client
FoxIDs can transform the DK privilege XML claim to a JSON claim. It is recommended to add the transformation in order to obtain smaller claims and tokens. Furthermore, it makes the tokens readable.
- Select the Claim transform tab
- Click Add claim transform and click DK XML privilege to JSON
- Click Add claim transform and click Match claim
- As action select Remove claim, to remove the original privilege claim from the claims pipeline
- In the Remove claim field add
https://data.gov.dk/model/core/eid/privilegesIntermediate
- Click update
Remember to add a claim mapping from SAML
http://schemas.foxids.com/identity/claims/privilege
to JWTprivilege
please see next section 4).
4 - Add SAML 2.0 claim to JWT claim mappings in FoxIDs Control Client
FoxIDs internally converts SAML 2.0 clams to JWT claims. Context Handler use a OIOSAML3 defined set of SAML 2.0 claims where corresponding JWT mappings need to be added in the environment.
- Go to Settings tab and Claim mappings
- Add mappings for all the claims configured in step 1.14, you can create you own short JWT claim names if no standard name exists
- Click update
You are done. The SAML 2.0 authentication method can now be used as an authentication method for application registrations in the environment.
A application registration will only issue added claims.
Therefore, remember to add the JWT claims to OpenID Connect application registrations or use the*
notation.
Configuring Context Handler as test Relying Party
This guide describe how to setup Context Handler as a SAML 2.0 test Relying Party and comply to OIOSAML3.
You need to use a separate environment to have a place for the test users and to configure the OCES3 certificate before following this guide.
1 - Start by creating an SAML 2.0 application registration in FoxIDs Control Client
- Select the Applications tab
- Click Create application registration and then SAML 2.0
- Add the name
- Click Add allow authentication method and click login, to let the user login with test users in the environment
- 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
The certificate is base64 encoded and can be converted into a certificate .cer file with the FoxIDs certificate tool. - Add the issuer and endpoints from the metadata
- Set the bindings to redirect with the exception of the Authn response binding which is set to post
- Set the OIOSAML3 claims which should be issued to Context Handler
The following claims is 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
- Add the certificate from the metadata as a signature validation certificate
- Click Create
Select Show advanced settings
Select Encrypt authn response
Add the certificate from the metadata as a optional encryption certificate
Set the certificate revocation mode to
Online
and optionally the validation mode toChain trust
if the OCES3 root certificate is trusted on your platform. The OCES3 root certificate is NOT trusted in Azure.Set Authn response sign type to Sign assertion
Configure a custom IdP issuer, the issuer can optionally start with
https://saml.
The issuer in this examplehttps://saml.foxids.com/test-corp/context-handler-test-idp/
.Select to add logout response location URL in metadata
Select to include the encryption certificate in metadata
Set the NameID format in metadata to
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
Add an administrative contact person
Click Update
Go to the top of the SAML 2.0 application registration
Find the SAML 2.0 application registration IdP-metadata, in this case
https://localhost:44330/testcorp/test-contexthandler-idp/ch-idp(*)/saml/idpmetadata
.The IdP-metadata is used to configure the Context Handler identity provider.
2 - Then go to the Context Handler administration portal
- Select IT-systems (DK: IT-systemer)
- Click Add IT-system (DK: Tilslut it-system)
- Fill out the fields and select Identity Provider
- Go to the Identity Provider tab
- Select Context Handler with NSIS and remove the selection of Context Handler (without NSIS)
- Select OIOSAML3 as OIOSAML profile and NSIS level
- Add the SAML 2.0 application registration IdP-metadata URL, in this case
https://localhost:44330/testcorp/test-contexthandler-idp/ch-idp(*)/saml/idpmetadata
. - 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 which has to be issued to Context Handler in claim transforms.
- Add the spec. ver. claims
- Optionally add the levels of assurance (loa) claim or read it through the claims pipeline
- Replace the NameID / NameIdentifier claim which a concatenated version of the CVR number, display name and unique user ID. Format string
C=DK,O={0},CN={1} {2},Serial={3}
- Click update
4 - Add SAML 2.0 claim to JWT claim mappings in FoxIDs Control Client
FoxIDs internally converts SAML 2.0 clams to JWT claims. Context Handler use a OIOSAML3 defined set of SAML 2.0 claims where corresponding JWT mappings need to be added in the environment.
- Go to Settings tab and Claim mappings
- Add mappings for all the claims configured in step 1.8, you can create you own short JWT claim names if no standard name exists - please see step 4 in section Configuring Context Handler as Identity Provider
- Click update
5 - Add test users in FoxIDs Control Client
You can add test uses in the FoxIDs test environment and add claims to each user.
A claim with a CVR claim, given name, family name and optionally a base64 encoded DK privilege XML string.
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:
<?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>