ADFS Configuration Manual

Setting up AD FS to run OIDC for MOPS 4.0

AD FS supports OAuth2 and thereby OpenID Connect (OIDC) out of the box. This standard of token-based authentication is required for the entire MOPS 4.0 system, client application will make requests to the Identity Provider to authenticate clients, their access to MOPS 4.0 APIs and authorize users in the MOPS 4.0 web-application.

Prerequisites

This guide is for configuring AD FS for MOPS 4.0 (web-client application) and requires that the following is already setup & available:

  • Windows Server 2019 machine (or later) with AD FS installed.
  • Certificate for signing tokens.

Setting Federation Service Identifier

In the OpenID Connect standard there is an exposed endpoint to retrieve all service endpoints, allowed authentication methods, response types, supported claims, allowed scopes and so on. This endpoint must be accessible by MOPS 4.0, and to make sure it can be accessed, Federation Service Identifier must be set correctly. How to make sure configured right:

  1. Open Server Manager on the computer that is running AD FS, on the top-right menu choose Tools > AD FS Management.

  1. In AD FS, in the menu to the left, right-click on AD FS and select Edit Federation Service Properties...

  2. Make sure the field Federation Service identifier ends with /adfs and not /adfs/services/trust.

Adding an Application Group

  1. In AD FS, in the menu to the left, right-click on Application Groups > Add Application Group....

  1. Add Application Group Wizard will open, in the Name field type MOPS4.0 and select the Template Native application accessing a web API marked in the screenshot below. This will add steps in the menu to the left.

  1. In Native Application, Change the generated Client Identifier to MOPS and add the following url:s by entering them in Redirect URI and clicking Add:
  • https://<your_mops4_installation>/callback

Shown as http://localhost/callback in the screenshot below.

The Name field can be left as-is.

  1. In Configure Web API, add MOPS as Identifier.

The Name field can be left as-is.

  1. Select an Access Control Policy-template, selecting Permit everyone will allow everyone to access this Application Group.

  1. In Configure Application Permissions, Client application-box should already contain MOPS4.0 - Native application.

In the box below, select the scopes openid, email and profile.

  1. In the final step, verify that provided configuration is correct.

Modifying claims to work with MOPS 4.0

The OpenID Connect standard contains all claims needed by MOPS 4.0, however AD FS does some things a bit different. In an access token generated by AD FS, the standard client_id is called appid, this means an additional claim called client_id must be added and mapped to use the value from appid. Following are the steps to do so:

  1. In AD FS, expand Services and select Claim Descriptions.

  1. Add a new claim by either right-clicking Claim Descriptions > Add Claim Description... on the left-hand menu or Add Claim Description... in Actions menu on the right.
  1. Fill in the form as shown below, where Display Name will be used for mapping and Short Name is what the claim will be called in an access token.

Remember to check both options for publishing this claim description!

  1. To map the created client_id claim to use the value from appid, click Application Groups > MOPS4.0 > MOPS4.0 - Web API > Issuance Transform Rules, the window will look like this:

  1. Click Add Rule. A new window will appear, select Claim rule template Transform an Incoming Claim.

  1. Fill in the for as specified below, it will map the incoming Oauth Client Id (appid claim) to the newly created OIDC Client ID (client_id claim that will be shown in access tokens). Then select Pass through all claim values and click finish.

Additional claims

One more claim mapping rule is required, there are a couple of claims for user information that needs to be exposed in every access token. These are LDAP-attributes that have their values mapped straight through so it is a much simpler process, no new claim descriptions are required:

  1. In AD FS, click Application Groups > MOPS4.0 > MOPS4.0 - Web API > Issuance Transform Rules and click Add Rule. In the new window select the Claim rule template Send LDAP Attributes as Claims.

  1. In the next window, fill in the form like this:

Note that E-mail-Addresses are mapped twice, once to E-mail Address, which is the claim email and to Name ID which is the sub claim in an access token. The sub claim is used as a unique identifier for users in MOPS 4.0 and it is important that it’s present in every access token.)

If MOPS 4.0 is not running on the same domain as AD FS

In a likely scenario, MOPS 4.0 will need to make a Cross-Origin Resource Sharing (CORS) request when the application is trying to reach AD FS installed on a different domain than the MOPS 4.0 installation. In order for this to work, CORS response headers for AD FS must be enabled and a trusted origin must be added, this is done in two simple steps:

  1. On the machine where AD FS is installed, open an elevated Windows Powershell window (run it as Administrator), and run the following command: Set-AdfsResponseHeaders -EnableCORS $true.

  2. Run a second command with the allowed origin: Set-AdfsResponseHeaders -CORSTrustedOrigins https://<your_mops4_installation>

To add multiple trusted CORS origins simply divide them with a ‘,’ example: Set-AdfsResponseHeaders -CORSTrustedOrigins https://<your_mops4_installation>,https://<other_trusted_origin>

To check if CORS is configured correct run Get-AdfsResponseHeaders, this command will show the properties CORSEnabled, which should be True and the CORSTrustedOrigins that has been set.

Condition Monitoring System (CMS)

If CMS was installed with MOPS 4.0, it’s services will also need to be authenticated. Since these services are not interactive users in the UI of MOPS 4.0 they will need to setup to use the client_credentials OIDC flow. In ADFS an additional client must be created in the same application group as the one used for MOPS 4.0.

 

  1. Click on Application Groups to the left and then select mops-test. Click on Add Application...

 

  1. Select Server Application

 

  1. Enter a name in the Client Identifier-field, this could be MOPS4.0-CMS. In the Redirect URI-field enter the same URL as main client, https://<your_mops4_installation>/callback

 

  1. Check Generated a shared secret and click on Copy to clipboard. This value should be sent to the person configuring CMS for MOPS 4.0.

This value will only be visible in this window and only once