AD FS configuration

This how-to guide describes how to configure Unit4 Identity Services with ADFS.

This is a how-to guide and it does not explain the terminology. For more information about tenants see registering a tenant and Configuration of a tenant.

Prerequisites

Administrative access to AD FS
U4IDS authority address (over the remainder of this document we use value of https://<u4ids basepath>/identity as the address of U4IDS installation's identity endpoint)
Decision ON which claim would be used to uniquely identify the user in the organisation (see "Unique claims" below.)
access to U4IDS in order to create tenant

The list of official IDS environments can be found here

Steps

Add a new Relying Party Trust

Select Claims aware relying party.

You need to enable the WS-Federation Passive protocol.

Manually add the values of address of U4IDS installation.

Configure claims that would be sent to U4IDS

Configure mapping of claims and other AD values sent to U4IDS.

, OR

IMPORTANT NOTICE: Make sure you map to claim 'Name ID' using a unique claim (here User-Principal-Name as a first option or objectGUID on the next screen shot, could also be E-Mail-Addresses). Without a unique user's value mapped to this claim the configuration of U4IDS with AD FS will not work.

Create and configure tenant in U4IDS

With help of Powershell scripts or REST API create the tenant to be used with the AD FS.

Sample tenant configuration:

{
  "authority": "https://<your AD FS server url>/FederationMetadata/2007-06/FederationMetadata.xml",
  "description": "Your Company AD FS",
  "idpRegId": "https://u4ids-dev.azurewebsites.net/identity",
  "nameClaimType": "name",
  "protocol": "ws-federation",
  "tenantId": "89DEC732-5AFB-4C06-A2E5-A8C8CD815FDA",
  "unit4IdClaimType": [ "nameidentifier", "email" ],
  "includeIdentityScopesInConsent": true
}

The above configuration would map the users' UPN to unit4_id which would then be used for all systems of Unit4 to recognize the user.

Note that first UPN is mapped to nameidentifier claim by AD FS and then U4IDS maps this value to unit4_id.

Claim 'name' is mapped to user's name. This claim needs to be provided from AD FS (if missing then you could use here the same claim as for unit4IdClaimType).

Sample value of 89DEC732-5AFB-4C06-A2E5-A8C8CD815FDA is used for tenantId.

The metadata endpoint configured in the authority element is taken from AD FS Endpoints:

Unique claims that can be mapped to unit4_id

| AD claim | Value to be used as unit4IdClaimType | Description | |---|---|---|---|---| | Name ID | nameidentifier or sub | Can be mapped to email address, UPN or objectGUID (as on the screen shots above). | | User-Principal-Name | upn | Depends on the configuration in AD. Can be mapped to email address. | | Email Addresses | email | Email address of a user. | | Primary Security Identifier (SID) | primarysid | e.g. S-1-5-21-918238372-1567831296-1769025822-29564 | | Windows account name | winaccountname | e.g. MyDomain\MyAccountName |

One of the claims that gets sent from AD FS is sub claim. It is used as a default fallback to be placed in unit4_id in case the claim you have chosen in the tenant configuration is not working (for example was not delivered, or you chose a non-existing claim or made a typo).

When objectGUID is mapped to the Name ID claim then its value is the base64-encoded value of the GUID that uniquely identifies the given user object in the AD store. In this case the value of objectGUID being 4d6861cf-526a-4dee-b2f0-3e4a5cb3e36c is transferred as z2FoTWpS7k2y8D5KXLPjbA== (encoded form).

In case you need to receive the decoded value of this claim, follow this sample article on how to create your own attribute store in AD FS that would decode the claim before sending: