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.

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.
   
   
    
   
   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 Attribute	Claim Name	Mapping Value
    User-Principal-Name	UPN	UPN
    SAM-Account-Name	Windows account name	WINACCOUNTNAME
    TITLE	Title	TITLE
    Given-Name	Given Name	GIVEN_NAME
    Surname	Surname	FAMILY_NAME
    E-Mail-Addresses	E-Mail Address	EMAIL
    Token-Groups - Unqualified Names	ADGroups*	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