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
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
Parameters
As well as the parameters described in Base Provider Parameters, the following must be set in the params object.
| Name | Type | Description | |
|---|---|---|---|
| Required | |||
| adfsServerHost | String (URL) | The 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" | |
| clientId | String | The ADFS OAuth2 Client's ClientId (provided by the ADFS server you are connecting to) | |
| clientSecret | String, required for Azure | Azure ADFS web applications require a client secret to be supplied when exchanging an access token for an access code | |
| userProfileAttributeMapping | Object | Maps 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": { | |
| Optional | |||
| authorizeEndpointUrl | String(URL) | Fully qualified URL to the ADFS server's /authorize end point If 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 | |
| azure | Boolean | Set true if working with Azure | |
| clockSkew | Integer | A number of seconds to allow for discrepancies between clocks on local and remote servers. Default 0 | |
| debugLogging | Boolean | Default: 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 | |
| excludeMirroredGroups | Array<String> | By default this list is: ["BUILTIN", "NT AUTHORITY"] If | |
| excludeMirroredGroupsRegex | String (Regex) | Default: null If | |
| groupAttribute | String | Default: 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' | |
| includeMirroredGroups | Array<String> | Default: null If defined, only LDAP groups in this list of group names or those that match | |
| includeMirroredGroupsRegex | String (Regex) | Default: null If defined, only LDAP groups that are either in the | |
| mirrorGroups | Boolean | Default: 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:
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:
| |
| relyingPartyTrustId | String | The ADFS OAuth2 enabled Relying Party Trust identifier (provided by the ADFS server you are connecting to) | |
| scopes | String | Scopes will only be used when working with Azure ADFS ( 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 | |
| tokenEndpointUrl | String(URL) | Fully qualified URL to the ADFS server's /token end point If 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 | |
| tokenSigningCertFilePath | String(File path) | Default: 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 | |
| tokenSigningKey | String | A key to use instead of a certificate | |
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
- 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. - 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.
- The user's browser is forwarded back to the Authentication Worker by ADFS.
- 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.
- 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
The
The
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
- Open AD FS Manager.
- 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".
- Select start.
- Choose "Enter data about the Relying Party Manually". Select next.
- Enter a display name for the RPT, then select next.
- Choose "AD FS Profile", then select next.
- Optionally configure a certificate if you wish, otherwise select next.
- Select next, leaving both "WS-Federation Passive" and "SAML 2.0 WebSSO" both unchecked.
- Add at least one relying party trust identifier - this will be the value of therelyingPartyTrustIdprovider parameter.
- Choose "I do not want to configure multi-factor authentication settings for this relying party trust at this time", and select next.
- Choose "Permit all users to access this relying party'" The access policy may be configured later. Select next.
- Select next at the summary screen.
- Leave the "Open the Edit Claim Rules dialogue for this relying party trust when the wizard closes" option checked, and select close.
- On the "Issuance Transform Rules" tab, select "Add Rule...".
- In the new dialogue, choose "Send LDAP Attributes as Claims".
- 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 - Select finish when all the necessary LDAP attributes are configured.
- 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
- Open AD FS Manager.
- Select application groups, "Add Application Group...", and choose "Web-browser accessing a web application". Enter an application name and description and hit next.
- 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, eghttp://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" - 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.
- Select next on the application group creation summary page to create the application group with the given details.
- 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".
- Select the "Issuance Transform Rules" tab in the new modal dialogue, then select "Add Rule..."
- Select "LDAP attributes as Claims" to source the attribute values from the LDAP (ActiveDirectory) server, and select next.
- 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
Share this page
