Toggle menu

ADFS

The ADFS (Active Directory Federated Services) provider authenticates a user against an ADFS server. As with other providers, once a user has successfully authenticated, a local iCM site user is created for them.

The user's ADFS group membership can optionally be mirrored in iCM as well. The OAuth2 interface introduced in ADFS v3.0 (2012R2+) is used, and for this reason only ADFS v3.0+ is supported (Windows Server 2012R2, 2016).

Note that this is not seamless SSO - it requires the user to visit the authentication template page and choose the "Log in with <ProviderDisplayName>" option.  However, if JavaScript is enabled in the browser the provider can be configured, using the autoSubmitIfOnlyProvider property, to auto submit if only one provider is configured. See the successful login flow example below for more information.

Provider Linking

Linking to and from this provider type is always disabled. Providers of this type are almost always used to grant access to a corporate network. Linking an ADFS provider to a social provider could grant undue access to a user who logs in with their social account. By disabling linking potential problems with mirrored groups are also avoided.

adfs_basic

A second version of this provider type exists called adfs_basic.  This type is safe to use with provider linking because it will never create user groups, even if configured to do so.

Parameters

As well as the parameters described in Base Provider Parameters, the following must be set in the params object.

NameTypeDescription
adfsServerHostString (URL), requiredThe root path of the ADFS server host, eg:

https://sso.gossinteractive.com

The 'authorize' and 'token' paths will be made relative to this URL. eg token: 

https://sso.gossinteractive.com + "/adfs/oauth2/token"
authorizeEndpointUrlString(URL), optionalFully qualified URL to the ADFS server's /authorize end point

If adfsServerHost is supplied then the default ADFS paths relative to that host can be assumed. This requires less configuration in the standard case.

<adfsServerHost> + "/adfs/oauth2/authorize"

However, if the authorize/token endpoint URLs are not relative to the same host (the case for some Azure ADFS setups) the fully qualified URLs to both the authorize and token end points can be explicitly supplied
azureBooleanSet true if working with Azure
clientIdString, requiredThe ADFS OAuth2 Client's ClientId (provided by the ADFS server you are connecting to)
clientSecretString, required for AzureAzure ADFS web applications require a client secret to be supplied when exchanging an access token for an access code
clockSkewInteger, optionalA number of seconds to allow for discrepancies between clocks on local and remote servers. Default 0
debugLoggingBoolean, optionalDefault: false

If enabled the JWT Token and Attribute Mapping Values will be logged, simplifying the process of creating a mapping

This configuration option is ONLY for use in a development environment to assist in creating the attribute mapping. If this must be used NEVER LEAVE THIS ENABLED as it prints out user information to a log file
excludeMirroredGroupsArray<String>, optionalBy default this list is: ["BUILTIN", "NT AUTHORITY"] 

If includeMirroredGroups and includeMirroredGroupsRegex have not been provided then all groups will be mirrored, excluding those in this list or those that match excludeMirroredGroupsRegex. Group names are case insensitive
excludeMirroredGroupsRegexString (Regex), optionalDefault: null

If includeMirroredGroups and includeMirroredGroupsRegex have not been provided then all groups will be mirrored, excluding those in excludeMirroredGroups and those that match this regular expression
groupAttributeString, optionalDefault: null

Name of the JWT token attribute containing the JSON array of groups the user is a member of

For example if on the server the attribute 'Token-Groups - Unqualified Names' was mapped to a token name of 'ADGROUPS', the value of this property should be 'ADGROUPS'
includeMirroredGroupsArray<String>, optionalDefault: null

If defined, only LDAP groups in this list of group names or those that match includeMirroredGroupsRegex will be mirrored. Group names are case insensitive
includeMirroredGroupsRegexString (Regex), optionalDefault: null

If defined, only LDAP groups that are either in the includeMirroredGroups list or match this regex will be mirrored
mirrorGroupsBoolean, optionalDefault: false

If true, creates an iCM Site User group membership structure identical to that returned by ADFS

For example assuming a provider prefix of "ADFS_" and a user named "administrator" in the following ADFS groups:
  • admins
  • webteam
  • companyuser

then upon this user authenticating, iCM site user groups with the following names will be created if they do not already exist, and the user added to them:

  • ADFS
  • ADFS _ADMINS
  • ADFS _WEBTEAM
  • ADFS _COMPANYUSER
relyingPartyTrustIdString, requiredThe ADFS OAuth2 enabled Relying Party Trust identifier (provided by the ADFS server you are connecting to)
scopesString, optionalScopes will only be used when working with Azure ADFS (azure: true, see above) otherwise ignored

Default: "openid profile email"

Space delimited scopes to request from the Azure ADFS server. Scopes are configured on the ADFS server itself, and dictate what attributes are returned for a given relyingPartyTrustId
tokenEndpointUrlString(URL), optionalFully qualified URL to the ADFS server's /token end point

If adfsServerHost is supplied then the default ADFS paths relative to that host can be assumed. This requires less configuration in the standard case.

<adfsServerHost> + "/adfs/oauth2/token"

However, if the authorize/token endpoint URLs are not relative to the same host (the case for some Azure ADFS setups) the fully qualified URLs to both the authorize and token end points can be explicitly supplied
tokenSigningCertFilePathString(File path), optionalDefault: null

Optional path to a PEM encoded .cer file containing the certificate to use to verify the JWT token returned by ADFS

If not supplied, JWT tokens will not be verified

Certificates should be stored in the ${APISERVER}/data/auth directory, eg ${APISERVER}/data/auth/adfs-providername/adfs-token-signing.cer
tokenSigningKeyString, optionalA key to use instead of a certificate
userProfileAttributeMappingRequiredMaps LDAP attributes as returned by the ADFS server via the ADFS JWT token (left) to the Authentication Worker's UserProfile class fields (right)

Only the UNIQUEID field is required. See Site User Profile Mapping for further information

"userProfileAttributeMapping": {
    "mapping": {
        "UPN": {
            "mappings": ["UNIQUEID"]
        },
        "WINACCOUNTNAME": {
            "mappings": ["SAMACCOUNTNAME"]
        },
        "TITLE": {
            "mappings": ["TITLE"]
        },
        "GIVEN_NAME": {
            "mappings": ["FORENAMES", "PREFERREDNAME"]
        },
        "FAMILY_NAME": {
            "mappings": ["SURNAME"]
        },
        "EMAIL": {
            "mappings": ["EMAIL"]
        }
    }
}

User Profile Data

Attribute names and the attributes supplied are entirely ADFS server configuration dependent. See https://msdn.microsoft.com/en-us/library/microsoft.identitymodel.claims.claimtypes_members.aspx for a list of common .NET claim attributes. Note that while common claims have a commonly used names they can be mapped to a JWT token alias of any name.

See the Linking Providers, Account and Profile Management article for information about how profiles and email addresses are updated.

Examples

Hosted ADFS Server

{
    "providerName": "adfs",
    "providerDisplayName": "ADFS-DLV",
    "type": "adfs",
    "params": {
        // Required
        "clientId": "oauth2testclient",
        "adfsServerHost": "https://sso.gossinteractive.com",
        "relyingPartyTrustId": "testrelyingpartytrustidentifier",
        "userProfileAttributeMapping": {
            "mapping": {
                "UPN": { "mappings": ["UNIQUEID", "UPN"] },
                "WINACCOUNTNAME": { "mappings": ["SAMACCOUNTNAME"] },
                "PERSONALTITLE": { "mappings": ["TITLE"] },
                "GIVEN_NAME": { "mappings": ["PREFNAME", "FIRSTNAME"] },
                "NAME": { "mappings": ["FULLNAME"] },
                "EMAIL": {"mappings": ["EMAIL"]}
            }
        },
        // Optional
        "mirrorGroups": true,
        "groupAttribute": "ADGROUPS",
        "tokenSigningCertFilePath": "${APISERVER}/data/auth/adfs-dlvdc1/adfs-token-signing.cer"
    }
}

Azure Hosted ADFS

{
    "providerName": "adfs-demo",
    "providerDisplayName": "Azure",
    "type": "adfs",
    "userPrefix": "adfs-",
    "params": {
        "debugLogging": false,
        "azure": true,
        "autoSubmitIfOnlyProvider": true,
        "clientId": "redacted",
        "clientSecret": "redacted",
        "relyingPartyTrustId": "redacted",
        "adfsServerHost": "redacted",
        "authorizeEndpointUrl": "https://login.microsoftonline.com/xxxx-directoryid-xxxx/oauth2/authorize",
        "tokenEndpointUrl": "https://login.microsoftonline.com/xxxx-directoryid-xxxx/oauth2/token",
        "userProfileAttributeMapping": {
            "mapping":{
                "UPN": { "mappings": ["UNIQUEID", "UPN"] },
                "WINACCOUNTNAME": { "mappings": ["SAMACCOUNTNAME"] },
                "PERSONALTITLE": { "mappings": ["TITLE"] },
                "GIVEN_NAME": { "mappings": ["PREFNAME", "FIRSTNAME"] },
                "NAME": { "mappings": ["FULLNAME"] },
                "FAMILY_NAME": { "mappings": ["LASTNAME"] },
                "EMPLOYEEID": { "mappings": ["EMPLOYEEID"] },
                "COMPANYNAME": { "mappings": ["COMPANY"] },
                "DEPARTMENT": { "mappings": ["DEPARTMENT"] },
                "JOBTITLE": { "mappings": ["JOBTITLE"] }
             }
        },
        "profileFieldsToUpdate": ["EMPLOYEEID", "COMPANY", "DEPARTMENT", "JOBTITLE", "FIRSTNAME", "LASTNAME"]
    }
}

Successful Login Flow

  1. The user selects the "Log in with <ProviderDisplayName>" option on the login article and an OAuth2 authorization request is made to the corresponding ADFS server's end point.

    ADFS Example Login
     

    The user's browser is redirected to the ADFS hosted AuthorizationUrl, as returned in the response.
  2. User login
    • If the user has logged in before via ADFS form based authentication within a certain time period then the user will be logged in without the need to resupply their login credentials.
    • If ADFS forms based authentication is configured for the ADFS login page and the user hasn't logged in before within a certain time frame then the user must then enter their domain username and password.
    • If Kerberos authentication is appropriately enabled for the ADFS login page and the browser is Kerberos compliant then the user will be logged in via Kerberos negotiation, as handled by the ADFS server.
  3. The user's browser is forwarded back to the Authentication Worker by ADFS.
  4. An iCM site user is created (or updated if it already exists), and, if appropriately configured, ADFS groups are mirrored as iCM site user groups.
  5. The user's browser is forwarded back to the appropriate location on the website by the Authentication Worker, now having logged in.

Setup

To configure the ADFS provider three main property values are required, a clientId, a relyingPartyTrustId, and the adfsServerHost (the base host of the ADFS server).

The relyingPartyTrustId is the primary identifier of the relying party trust and can be any textual value that is unique to the relyingPartyTrusts on the system. It is simply the name that one refers to the relyingPartyTrust by. The corresponding relyingPartyTrust essentially defines where the user data being authenticating against is held (eg AD) and the claims to be returned to the caller once the user has authenticated. If ADFS is already being used then there may very well already be a relying party trust, however it is recommended to create a separate relying party trust for use with the Auth worker integration.

The clientId is the identifier of the client that allows OAuth2 access to the relyingPartyTrustId.

In Windows Server 2012R2 relying party trusts must be defined and then a client created for it via a PowerShell command. Configuration for Windows Server 2016 is different - a single entity called an "application group" must be created instead which creates both a relying party trust and a client behind the scenes.

Windows Server 2012R2

  1. Open AD FS Manager.
  2. Create a relying party trust, but if a suitable RPT already exists then this can be skipped. Select "Relying Party Trusts", then "Add Relying Party Trust".
  3. Select start.
  4. Choose "Enter data about the Relying Party Manually". Select next.
  5. Enter a display name for the RPT, then select next.
  6. Choose "AD FS Profile", then select next.
  7. Optionally configure a certificate if you wish, otherwise select next.
  8. Select next, leaving both "WS-Federation Passive" and "SAML 2.0 WebSSO" both unchecked.
  9. Add at least one relying party trust identifier - this will be the value of therelyingPartyTrustIdprovider parameter.
  10. Choose "I do not want to configure multi-factor authentication settings for this relying party trust at this time", and select next.
  11. Choose "Permit all users to access this relying party'" The access policy may be configured later. Select next.
  12. Select next at the summary screen.
  13. Leave the "Open the Edit Claim Rules dialogue for this relying party trust when the wizard closes" option checked, and select close.
  14. On the "Issuance Transform Rules" tab, select "Add Rule...".
  15. In the new dialogue, choose "Send LDAP Attributes as Claims".
  16. The LDAP attributes which will be made available to the authentication worker after a user is successfully authenticated must now be configured. Map the available LDAP attributes on the left to claim names on the right. Arbitrary claim names can be entered manually, but the standard claim names (prepopulated in the drop down) are preferred if possible. See the table below for some common mappings. Spaces in the claim name will be converted to underscores in the mapping. Claim names marked with an asterisk are custom. Note that the user's AD groups are mapped to the "ADGroups" claim. As this value must be handled specially, the name of the mapping value that contains this information must be specified via the 'groupAttribute' parameter if mirrorGroups is true
    LDAP AttributeClaim NameMapping Value
    User-Principal-NameUPNUPN
    SAM-Account-NameWindows account nameWINACCOUNTNAME
    TITLETitleTITLE
    Given-NameGiven NameGIVEN_NAME
    SurnameSurnameFAMILY_NAME
    E-Mail-AddressesE-Mail AddressEMAIL
    Token-Groups - Unqualified NamesADGroups*ADGROUPS
  17. Select finish when all the necessary LDAP attributes are configured.
  18. Now a suitable AD FS Client must be configured. Open a PowerShell terminal with administrator rights and run the following command, substituting suitable values for the Name, ClientId, and RedirectUri parameters.
    Add-ADFSClient -Name "Test OAuth2 Client" -ClientId "oauth2testclient" -RedirectUri "http://site-proxy-path-to-apiserver/apiserver/auth/http/reentry"See here for the official Add-ADFSClient command documentation.

Windows Server 2016

  1. Open AD FS Manager.
  2. Select application groups, "Add Application Group...", and choose "Web-browser accessing a web application". Enter an application name and description and hit next.
  3. Enter a unique client identifier. A UUID is automatically generated for you. Also enter the public URL to the Auth worker's /reentry end point, eg http://serverhostname/apiserver/auth/http/reentry Note down the "Client Identifier" - this will need to be set in the Auth worker's ADFS provider params as both "clientId" and "relyingPartyTrustId"
  4. Select an access control policy. Using ACPs the application can be configured to only authenticate certain users based on a set of criteria - ActiveDirectory groups that they're a member of, for example.
  5. Select next on the application group creation summary page to create the application group with the given details.
  6. Now the user properties (title, email address, etc) that will be passed through to the worker from LDAP (ActiveDirectory) upon authentication must be configured. Double click the "test" application. Click "test - Web application" and then select "Edit".
  7. Select the "Issuance Transform Rules" tab in the new modal dialogue, then select "Add Rule..."
  8. Select "LDAP attributes as Claims" to source the attribute values from the LDAP (ActiveDirectory) server, and select next.
  9. The LDAP attributes which will be made available to the authentication worker after a user is successfully authenticated must now be configured. Map the available LDAP attributes on the left to claim names on the right. Arbitrary claim names can be entered manually, but the standard claim names (prepopulated in the drop down) are preferred if possible. See the table above
Last modified on 31 October 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon