Set up Microsoft Active Directory Federation Services as a federation IdP

To use Microsoft Active Directory Federation Services (AD FS) as a federation IdP for a PingOne Advanced Identity Cloud tenant environment, you must create a relying party trust. The trust is a set of identifiers, names, and rules that identify the partner or web-application to the federation service.

Afterward, you must create an application group that uses single sign-on (SSO) to access applications that are outside the corporate firewall.

The instructions in this document assume that you have a self-hosted instance of AD FS version 4.0, running on Windows Server 2016 or higher.

Step 1: Create a relying party trust

In this step, you create a relying party trust. The trust is a set of identifiers, names, and rules that identify the partner or web-application to the federation service.

Open the Server Manager console by clicking Server Manager on the Start screen or clicking Server Manager in the taskbar on the desktop.
In AD FS Management, select Tools > AD FS.
On the AD FS dialog, in the left panel, click Relying Party Trusts.
In the Actions pane, select Add Relying Party Trust.
On the Welcome page of the Add Relying Party Trust wizard, select Claims aware.
On the Select Data Source page, select Enter data about the relying party manually.
On the Specify Display Name page, enter a display name.
Complete the steps in the wizard until you reach the Configure Identifiers page.
On the Configure Identifiers page, add a relying party trust identifier for each of your tenant environments using the following URL format:

https://<tenant-env-fqdn>/am

For example, if your tenant environment FQDN is openam-mycompany-ew2.id.forgerock.io, use https://openam-mycompany-ew2.id.forgerock.io/am.
On the Choose Access Control Policy page, select the appropriate settings according to your corporate policy.
Complete the steps in the wizard until you reach the Finish page.

Step 2: Create an application group

In this step, you create an application group that uses single sign-on (SSO) to access applications.

In the AD FS editor, select Application Groups.
In the Actions pane, select Add Application Group.
Complete the Add Application Groups wizard as follows:
1. On the Welcome page of the Add Application Groups wizard, provide a name and a description and select the Server application accessing a web API template.
2. On the Server application page:
  - Accept the proposed Name.
  - Note the Client Identifier.
    
    In Advanced Identity Cloud, enter this value in an application’s Application ID field (or set in an ESV mapped to that field).
  - Add tenant Redirect URIs for each of your tenant environments using the following URL format:
    
    https://<tenant-env-fqdn>/login/admin
    
    For example, if your tenant environment FQDN is openam-mycompany-ew2.id.forgerock.io, use https://openam-mycompany-ew2.id.forgerock.io/login/admin.
3. Click Register to create the application.
4. On the Configure Application Credentials page:
  1. Select Generate a shared secret. The secret acts as a password for the application.
  2. Use the Copy to clipboard button to copy the secret.
    
    In Advanced Identity Cloud, enter this value in an application’s Application Secret field (or set in an ESV mapped to that field).
5. Click Next.
6. On the Configure Web API page, add the client identifier you noted earlier.
7. Click Next.
8. On the Choose Access Control Policy page, select the appropriate settings according to your corporate policy.
9. Click Next.
10. On the Configure Application Permissions page, check the following permitted scopes:
  - allatclaims: Lets the application request the claims in the access token that is added to the ID token.
  - email: Lets the application request an email claim for the signed-in user.
  - openid: Lets the application request use of the OpenID Connect authentication protocol.
  - profile: Lets the application request profile-related claims for the signed-in user.
11. Click Next.
12. On the Summary page, review your selections.
13. Click Next.
14. On the Complete page, click Close.

Step 3: Include additional identity claims in tokens

In this step, you configure AD FS to include additional claims in the identity tokens it issues. This is necessary because AD FS does not support the /userinfo endpoint.

In the AD FS editor, select Application Groups.
In the Actions pane, select Add Application Group.
Double-click your application group.
In the Applications section, in the Web API area, select your application, and click Edit.
Click the Issuance Transform Rules tab, and click Add Rule.
To include active directory attributes of the users that are accessing Advanced Identity Cloud, in the Claim rule template drop-down field, select Send LDAP Attributes as Claims.
In the Claim rule name field, enter a name for the claim rule. For example, Profile Attributes.
In the Attribute store drop-down field, select Active Directory.
To map LDAP attributes to name spaces in Advanced Identity Cloud, complete the Mapping of LDAP attributes to outgoing claim types table:

LDAP Attribute (Select or type to add more) Outgoing Claim Type (Select or type to add more)

E-Mail Addresses

mail

Given-Name

givenName

Surname

sn
Click Finish.
On the Issuance Transform Rules tab, click Apply.
Click OK twice.

LDAP Attribute (Select or type to add more)	Outgoing Claim Type (Select or type to add more)
E-Mail Addresses	mail
Given-Name	givenName
Surname	sn

Step 4: Obtain the well-known endpoint for the AD FS OpenID Connect service

In this step, you identify the well-known URI that the AD FS OpenID Connect service uses.

In the AD FS editor, select Service > Endpoints.
In the middle pane, scroll down to the OpenID Connect section.
In the OpenID Connect section, note the URL path. The well-known end point URL is the concatenation of the host name of the machine running AD FS and the URL path you just noted.

In Advanced Identity Cloud, enter this value in an application’s Well-known Endpoint field (or set in an ESV mapped to that field).

Step 5: Use group membership to enable federation in AD FS

Groups let you add and remove sets of administrators based on their group membership in your IdP. You can also specify the level of administrator access (super administrator^[1] or tenant administrator) for groups of users.

Create groups containing Advanced Identity Cloud tenant administrators

You must create two groups of administrators in AD FS for each of your Advanced Identity Cloud environments:

For each tenant:

The first group should consist of the users that will be super administrators in your Advanced Identity Cloud tenant.
The second group should consist of the users that will be tenant administrators in your Advanced Identity Cloud tenant.

When naming each group, use a prefix that identifies the group as relevant for Advanced Identity Cloud; this allows the AD FS claim scripts to only include relevant groups. Make sure to include the tenant name as part of the group name to help you identify the tenant the group is for.

Example: group name template

<prefix>-<tenant identifier>-<admin type>.

Example: group name

aic-dev-superadmin

In this example:

aic represents the prefix.
dev represents the tenant identifier.
superadmin represents the admin type.

Example: All group names for a standard promotion group of tenants and a sandbox tenant.

aic-dev-superadmin
aic-dev-tenantadmin
aic-staging-superadmin
aic-staging-tenantadmin
aic-prod-superadmin
aic-prod-tenantadmin
aic-sandbox-superadmin
aic-sandbox-tenantadmin

Include additional claims in the tokens for Advanced Identity Cloud

To use group membership to enable federation, you must add issuance transform rules to enable AD FS to add additional group claims.

You must add the following two rules in AD FS:

Store Groups rule: A rule that collects all the user groups and stores them in a claim with the indicated name. The script produces a potentially large claim.
Issue Groups rule: A rule that takes the long list of groups that the Store Groups script creates and only selects the groups with the Group Name Prefix that is relevant for the claim.
1. In the AD FS editor, select Application Groups.
2. In the Actions pane, select the group you previously created.
3. Right-click the group and select Properties.
4. In the Applications section, in the Web API area, select your application, and click Edit.
5. Click the Issuance Transform Rules tab.
6. Click Add Rule.
7. To include active directory attributes of the users that are accessing Advanced Identity Cloud, in the Claim rule template drop-down field, select Send Claims Using a Custom Rule.
8. In the Custom rule field, enter the rule definition for the Store Groups rule.
  - Store Groups rule template:
    
    c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] ⇒ add(store = "Active Directory", types = ("<Groups Claim Name>"), query = ";tokenGroups;{0}", param = c.Value);
  - Store Groups rule example:
    
    c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] ⇒ add(store = "Active Directory", types = ("groups"), query = ";tokenGroups;{0}", param = c.Value);
    
    "groups" is the name of the resulting claim that you enter into the Groups Claim Name field on the Identity Provider Details page in the Advanced Identity Cloud.
9. Click Finish.
10. Click Add Rule.
11. To include active directory attributes of the users that are accessing Advanced Identity Cloud, in the Claim rule template drop-down field, select Send Claims Using a Custom Rule.
12. In the Custom rule field, enter the rule definition for the Issue Groups rule.
  - Issue Groups rule template:
    
    c:[Type == "<Groups Claim Name>", Value =~ "^<Group Name Prefix>-.+"] ⇒ issue(claim = c);
  - Issue Groups rule example:
    
    c:[Type == "groups", Value =~ "^aic-.+"] ⇒ issue(claim = c);
    
    "groups" is the name of the resulting claim that you enter into the Groups Claim Name field on the Identity Provider Details page in the Advanced Identity Cloud.
    
    "aic" is the prefix you chose for the group names.
13. Click Finish.

1. A super administrator is a tenant administrator with elevated permissions for configuring tenant administrators and federated tenant access. Learn more in Types of administrators.