V1.91 2024-08 

Introduction

This overview describes how to create a Single Sign On (SSO) relationship between your organizations' EntraID (previously Azure Active Directory or AAD) and the govroam ‘govconext’ SSO platform, based on SAML2. It will enable SSO for the end users of your organization to the govroam webservices, like govVPN, govguest etcetera. For each of these services, your organisation explicitly has to approve usage of it. For this, an administrative process through the Klantportaal can be started by the govroam Organization Contact Person. 

In case your organisation might already have SSO links for individual govroam services like govguest and getgovroam, the new SSO link created in this instruction will run in parallel to any SSO relations that are already in place. We will align with your Organizational Contact Person how and when the authentication for these services will actually be moved over to govconext. For this situation it is important that the e-mail address that was used as user identifier in the previous SSO link(s) is the same as the one used over the new link. 

Set up the Enterprise Application 

The connection is set up by creating a EntraID ‘Enterprise Application’.

Log into the Azure portal via https://portal.azure.com and select "Azure Active Directory”:  

Open

Azure Active Directory in the Azure admin portal

Go to “Enterprise Applications” (“Bedrijfstoepassingen”) and click “New Application”:  

Open

‘New Application'

Choose “Create your own application” (“Uw eigen toepassing maken”):

enter “govconext” as the name of your app (or choose your own. It might also be ‘govroam’ since govconext provides a single SSO link that provides access to all govroam webservices that your organisation makes use of). 

choose “Integrate any other application you don’t find in the gallery (Non-gallery)” and  

choose “Create” (“Maken”): 

With the newly created application open, choose “Set up single sign on”, and decide on access for users as well: 

Next, choose “SAML” as the “single sign-on method”:  

In the next screen, copy the “App Federation Metadata Url” and paste it into the ‘Technisch Intakeformulier govconext’: 

Next, select “Edit” in the “Basic SAML Configuration setting”, and enter the following settings for govconext Acceptance (for Production: see further on): 

 for govconext Production use the following URL’s:

Attribute mappings 

The govconext application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes. 

In addition to the above, the govconext application expects a few more attributes to be passed back in the SAML response, which are shown below. For a more elaborate overview and classification, please see the attributes overview. These attributes are also pre-populated but you can review them as per your requirements. Below is the list, and after the list an instruction on how to enter them. The attributes shown in bold are mandatory: 

For each of the claims in the table above, you need to go through the following steps.

Attributes that are exact copies of EntraID claims can easily be created based on the instruction in the next paragraph.

Attribute mappings that require manipulation are explained in the subsequent sections.

Add an attribute with a 1:1 mapping 

In the box ‘Attributes & Claims’, click ‘Edit’. 

Click ‘+ Add new claim’: 

Enter the claim name (first column in the table above) in the ‘Name’ field and select the Source attribute that you found in the second column in the table above: 

For urn:mace:dir:attribute-def:eduPersonAffiliation it is sufficient to simply type ‘employee’ in the source attribute field without the quotes, Microsoft will automatically put the word in double quotes.

Repeat the steps for every attribute mentioned in the table above.  

Add the manipulated attribute: schacHomeOrganization

The urn:mace:terena.org:attribute-def:schacHomeOrganization is slightly more complex: 

First add the claim by choosing ‘+ Add claim’ and enter “urn:mace:terena.org:attribute-def:schacHomeOrganization“ in the Name field. 

Then select Transformation button as a Source under Manage claim section. 

In the Manage transformation page, perform the following steps: 

1. Select Extract() from the dropdown in Transformation field and click After matching button. 

2. Select Attribute as a Parameter 1 (Input). 

3. In the Attribute name field, select user.userprinciplename from the dropdown. 

4. Select @ value from the dropdown. 

5. Click Add. 

Please add the default SchacHomeOrganization(s) used within your organization in the form ‘Technisch Intakeformulier govconext’ (usually the same as the main e-maildomain.nl). If your tenant contains multiple organizations, please provide each schacHomeOrganization in the table including their formal name, like Organisatie X and Y in the example below. If you serve multiple organizations that each have their own tenant, you can add them to the same table, like Organisatie Y and Z in the example below: 

The SAML configuration in EntraID (AAD) is now ready.  

Add the manipulated attribute: eduPersonScopedAffiliation

The Affiliation attribute contains a role that can be set to ‘employee’ by default. The ScopedAffiliation attribute should also add the domain of the user, which is in fact the same as schacHomeOrganization. This can be achieved by a transformation of the type ‘RegexReplace()’ with:

• Regex pattern: ^.*\@(?'domain')

• Replacement pattern (vervangingspatroon): employee@{domain}

Submit the intake form 

Please complete the form ‘Technisch Intakeformulier govconext’ with the metadata-URL and default schacHomeOrganization and the other required information and send it through the govroam ‘klantportaal’ and/or ‘tech@govroam.nl’. 

We connect you 

Once govconext is setup by stichting govroam, you will receive a notification that it is ready to use, and you can then log in to the govroam services that your organization subscribed to via your own IdP.  …

Please test 

You can then test the authentication and attribute mappings by browsing to:

• govconext-Acceptatie: https://acc.govconext.nl/debug  

• govconext-Productie: https://govconext.nl/debug

…and then search for your organization, after which you can login at your own organization. After that, the debug page should look like the screenshot below. The first four default Microsoft claims will be validated as a warning (yellow symbol) which you can ignore. All others must be validated correctly with a green symbol:

If the claims cannot be correctly validated, please check the steps above and reload the debug page until all required claims are correctly validated. If you’re in doubt, you can press the button ‘Mail naar govconext’ to have them checked.

Allow access to desired Service Providers

Only after your tests have been successful, we will set the authorisation to access the Service Providers that your organisation indicated wanting to be accessed. This step will be possible through the Dashboard in a later phase.

Allow users 

Please ensure that in Azure AD you assign users and groups to this ‘Enterprise application’ > ‘govconext’ through the menu-item ‘Users and Groups’ on the left. 

This step is often forgotten and the result is that users cannot log in. 

Troubleshooting 

Govconext provides a debug page that shows which attributes are received and other useful information:
https://engine.govconext.nl/authentication/sp/debug 

Additional information

Since govconext is built using OpenConext software which is also used for SURFconext, you can find additional information if you search for SURFconext, specifically:
Handleiding Azure AD als SAML Identity Provider in SURFconext - SURFconext - Get Conexted - SURF Wiki - https://wiki.surfnet.nl/  

Also, Microsoft provides an extensive article:  
https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/surfconext-tutorial