Identity Cloud

Set up a federation provider

You must set up a federation provider and then enable the provider in Identity Cloud. Afterward, administrators can use single sign-on (SSO) to log in to an Identity Cloud tenant. The processes in this section include setting up Microsoft Azure or AD FS as federation providers.

For the latest documentation for Microsoft Azure or AD FS, please refer to Microsoft documentation.

Set up AD FS as a federation identity provider

To set up AD FS as a federation identity provider, perform the steps in the following sections in the order presented.

1. Complete AD FS prerequisites

Before setting up AD FS as a federation identity provider, you must complete the following process:

  1. Set up a self-hosted instance of AD FS version 4.0, running on Windows Server 2016 or higher.

  2. Set up an Identity Cloud tenant.

  3. Assign administrators in Identity Cloud to the AD FS instance.

To use AD FS as a federation identity provider, you need to 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 need to create an application group that uses single sign-on (SSO) to access applications that are outside the corporate firewall.

2. Create a relying party trust

After you complete the prerequisites of setting up AD FS, you need to create a relying part trust that identifies the partner or web-application to the federation service.

Perform the following steps to add a relying party trust by using AD FS Management.

  1. Open the Server Manager console by clicking Server Manager on the Start screen or clicking Server Manager in the taskbar on the desktop.

  2. In AD FS Management, select Tools > AD FS.

  3. On the AD FS dialog, in the left panel, click Relying Party Trusts.

  4. In the Actions pane, select Add Relying Party Trust.

  5. On the Welcome page of the Add Relying Party Trust wizard, select Claims aware.

  6. On the Select Data Source page, select Enter data about the relying party manually.

  7. On the Specify Display Name page, enter a display name.

  8. Complete the steps in the wizard until you reach the Configure Identifiers page.

  9. On the Configure Identifiers page, add your tenant URLs as relying party trust identifiers:

    • For a demo or sandbox environment: https://openam-your-env.forgeblocks.com/am.

    • For a production environment: https://openam-your-env.id.forgerock.io/am.

  10. On the Choose Access Control Policy page, select the appropriate settings according to your corporate policy.

  11. Complete the steps in the wizard until you reach the Finish page.

3. Create an application group

To use AD FS as a federation identity provider, you need to 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 need to create an application group that uses single sign-on (SSO) to access applications.

Perform the following steps to set up an application group that connects with Identity Cloud.

  1. In the AD FS editor, select Application Groups.

  2. In the Actions pane, select Add Application Group.

  3. 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.

      • Add these tenant Redirect URIs, and click Next:

        • For a demo or sandbox environment: https://openam-your-env.forgeblocks.com/login/admin.

        • For a production environment: https://openam-your-env.id.forgerock.io/login/admin.

    3. 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.

    4. Click Next.

    5. On the Configure Web API page, add the client identifier you noted earlier.

    6. Click Next.

    7. On the Choose Access Control Policy page, select the appropriate settings according to your corporate policy.

    8. Click Next.

    9. 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.

    10. Click Next.

    11. On the Summary page, review your selections.

    12. Click Next.

    13. On the Complete page, click Close.

4. Include additional identity claims in tokens

Since AD FS does not support the /userinfo endpoint, we must extract all the user information or claims from the identity token. We use rules to configure AD FS to include these additional claims in the tokens required by Identity Cloud.

The Send LDAP Attribute as Claims rule allows you to include the active directory attributes of the users that access Identity Cloud.

Perform the following steps to instruct AD FS to include additional claims in the tokens that Identity Cloud requires.

  1. In the AD FS editor, select Application Groups.

  2. In the Actions pane, select Add Application Group.

  3. Double-click your application group.

  4. In the Applications section, in the Web API area, select your application, and click Edit.

  5. Click the Issuance Transform Rules tab, and click Add Rule.

  6. To include active directory attributes of the users that are accessing Identity Cloud, in the Claim rule template drop-down field, select Send LDAP Attributes as Claims.

  7. In the Claim rule name field, enter a name for the claim rule. For example, Profile Attributes.

  8. In the Attribute store drop-down field, select Active Directory.

  9. To map LDAP attributes to name spaces in Identity Cloud, complete the Mapping of LDAP attributes to outgoing claim types table:

    federation map ldap attributes
    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

  10. Click Finish.

  11. On the Issuance Transform Rules tab, click Apply.

  12. Click OK twice.

5. Obtain the well-known endpoint for the AD FS Open ID Connect service

After you include any additional identity claims in tokens, you need to identify the well-known URI that the AD FS Open ID Connect service uses.

  1. In the AD FS editor, select Service > Endpoints.

  2. In the middle pane, scroll down to the OpenID Connect section.

  3. 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.

6. Enable federation in AD FS using group membership

Groups let you add and remove sets of administrators based on their group membership in your identify provider (Microsoft Azure, AD FS, or OIDC). You can also specify the administrator access for an entire group of users: super administrators or tenant administrator.

Create groups with the Identity Cloud tenant administrators

You need to create two groups of administrators for each of your four Identity Cloud environments:

  • Sandbox

  • Development

  • Staging

  • Production

This means you must create a total of eight groups for each Identity Cloud tenant.

For each tenant:

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

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

When naming each group, use a prefix that identifies the group as relevant for ForgeRock 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 ID>-<admin type>.

Example: group name

fidc-cust-use1-dev-superadmin

In this example:

  • fidc-cust represents the ForgeRock Identity Cloud customer.

  • use1-dev represents the tenand id.

  • superadmin represents the admin type.

Example: All group names for a tenant

  • fidc-cust-use1-dev-superadmin

  • fidc-cust-use1-dev-tenantadmin

  • fidc-cust-use1-staging-superadmin

  • fidc-cust-use1-staging-tenantadmin

  • fidc-cust-use1-superadmin

  • fidc-cust-use1-tenantadmin

  • fidc-cust-use1-sandbox-superadmin

  • fidc-cust-use1-sandbox-tenantadmin

Include additional claims in the tokens for 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 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 Identity Cloud.

    9. Click Finish.

    10. Click Add Rule.

    11. To include active directory attributes of the users that are accessing 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 =~ "^fidc-.+"] ⇒ 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 Identity Cloud.

        • "fidc" is the prefix you chose for the group names.

    13. Click Finish.

Set up Microsoft Azure AD as a federation identity provider

To set up Microsoft Azure as a federation identity provider, perform the steps in the following sections in the order presented.

1. Complete Microsoft Azure prerequisites

Before setting up Microsoft Azure AD as a federation identity provider, you must complete the following process:

  1. Set up a self-hosted instance of Microsoft Azure AD.

  2. Set up an Identity Cloud tenant.

  3. Assign administrators in Identity Cloud to the AD FS instance.

2. Configure Microsoft Azure AD as a federation provider

  1. In a browser, navigate to the Microsoft Azure portal dashboard.

  2. On the Azure Active Directory admin center page, navigate to Azure Active Directory > App registrations.

  3. Click + New registration.

  4. On the Register an application page, enter the application Name.

  5. Select one or more Supported account types that can use the application or access the API.

    federation register an application

  6. In the Redirect URI (optional) section, in the drop-down list, select Web.

  7. Enter the Redirect URI (from the Redirect URI field on the Identity Cloud azure page).

  8. Click Register.

    federation redirect uri register

  9. Click Add a certificate or secret.

  10. Add a new client secret.

  11. Copy or make note of your application client ID and client secret.

  12. Save your changes.

  13. On the Azure Active Directory admin center page, navigate to Azure Active Directory > App registrations.

  14. Click Endpoints at the top of the page.

  15. Make note of your OpenID Connect metadata document endpoint, ensuring it contains your Azure tenant ID. For example: https://login.microsoftonline.com/XXXXXX /v2.0/.well-known/openid-configuration.

3. Use group membership to enable federation in Microsoft Azure

Groups let you add and remove sets of administrators based on their group membership in your identify provider (Microsoft Azure, AD FS, or OIDC). You can also specify the administrator access (super administrators or tenant administrator) for an entire group of users.

Create groups with the Identity Cloud tenant administrators

Follow these steps to create a group that contains the Identity Cloud tenant administrators.

  1. On the Azure Active Directory admin center page, navigate to Azure Active Directory.

  2. In the left menu pane, under Manage, select Groups.

  3. On the top menu bar, select New group.

  4. In the New Group pane, enter values for:

    • Group type. The group type - specify Microsoft 365.

    • Group name. The name of the group.

    • Group description: A description of the group.

  5. Select Create.

  6. Add users to the group.

If you modify group membership in Azure, it can take a few minutes for those changes to appear in Identity Cloud.

Include additional claims in the tokens for Identity Cloud

Complete the following steps to acquire claims from the application instead of the user info endpoint.

  1. On the Azure Active Directory admin center page, navigate to Azure Active Directory.

  2. In the left menu pane, under Manage, select App registrations.

  3. Choose your application.

  4. Under Manage, select Token configuration.

  5. Select Add optional claim.

  6. Select the token type you want to configure.

  7. Select the optional claims to add:

    • email: The email address for the user.

    • family_name: The last name, surname, or family name of the user.

    • given_name: The first or "given" name of the user.

    • groups: Optional formatting for group claims.

  8. Select Add.

Set up OIDC as a federation identity provider

To set up OIDC as a federation identity provider, perform the following steps:

  1. Configure an OIDC client profile:

    1. Choose a client id or note the automatically generated client id. Some OIDC providers let you choose the client id while others autogenerate it for you.

    2. Choose a client secret or note the automatically generated client secret. Some OIDC providers let you choose the client secret while others autogenerate it for you.

    3. Configure the allowed scopes. Recommended scopes: openid, profile, and email.

    4. Configure the client authentication method. Supported authentication methods: client_secret_post and client_secret_basic.

  2. Obtain the well-known URL from the OIDC provider. You will enter this URL when you enable the provider in Identity Cloud.

Next step

Copyright © 2010-2023 ForgeRock, all rights reserved.