PingOne Advanced Identity Cloud

Configure federated access for tenant administrators

Federated access lets tenant administrators use your company’s single sign-on (SSO) to log in to your PingOne Advanced Identity Cloud tenant environments.

By using federation to authenticate your tenant administrators to Advanced Identity Cloud, you can quickly and easily provision and deprovision users from your centralized identity provider instead of managing them separately in each Advanced Identity Cloud tenant environment.

The groups feature allows you to add and remove tenant administrators depending on their group membership in your identity provider. You can also specify the type of administrator access for an entire group of users.

You can configure Microsoft Azure or Microsoft AD FS as identity providers, or any other identity provider that supports OIDC.

To make your federation providers compatible with the promotion process, you must store the federation provider secrets for each of your environments in ESV secrets, set corresponding placeholders in your configuration, and promote the configuration to your environments.

Types of federation providers

Advanced Identity Cloud supports federation using the OIDC standard. You can choose one of the following as a federation identity provider:

Configure federated access across your tenant environments (high-level process)

The high-level process to set up federated access across your tenant environments is as follows:

  1. Set up a federation provider for each of your tenant environments and make a note of the client secrets.

  2. In your development environment:

    1. Configure the environment to use a federation provider, entering the federation provider client secret for your development environment. The client secret will be replaced by an ESV in the following steps.

    2. Create an ESV secret containing the federation provider client secret for your development environment:

    3. Restart Advanced Identity Cloud services.

    4. Insert the ESV placeholder into the configuration for the federation provider. Refer to Configure a federation provider secret.

  3. (Optional) If you have a UAT[1] environment, adapt the next step to suit the revised promotion order. Refer to Additional UAT environments.

  4. In your staging environment:

    1. Repeat step 2b for your staging environment. Ensure the ESV name is the same as you set up in the development environment.

    2. Run a promotion to move the configuration change from your development environment to your staging environment. Refer to:

  5. In your production environment:

    1. Repeat step 2b for your production environment. Ensure the ESV name is the same as you set up in the development environment.

    2. Run a further promotion to move the configuration change from your staging environment to your production environment.

  6. (Optional) If you have a sandbox[2] environment:

    1. Repeat step 2a for your sandbox environment.

    2. (Optional) Repeat step 2b–d for your sandbox environment.

  7. Configure federation login requirements in each environment.

Ensure that the federation provider for each environment is configured with a redirect URL. If you are using the same federation provider for your sandbox[2], development, UAT[1], staging, and production environments, ensure that it is configured with redirect URLs for each environment.

Set up a federation provider

To set up a federation provider, refer to the following guides:

Configure a mutable environment to use a federation provider

After you have set up a federation provider, you can configure it in a mutable environment (development or sandbox[2]) to provide federated access to tenant administrators.

To understand how the instructions in this section fit into the process of configuring federated access across your tenant environments, refer to step 2a in the high-level process.

  1. Log into the Advanced Identity Cloud admin UI of your mutable environment (development or sandbox[2]) as a super administrator[3].

  2. Go to Tenant settings.

  3. Click Federation.

  4. Click + Identity Provider.

  5. Select the federation provider to use:

    • Microsoft Azure

    • ADFS

    • OIDC

  6. Click Next.

  7. Follow the steps on the Configure Application page and click Next.

  8. On the Identity Provider Details page, complete the following fields:

    • Name: The name of the provider.

    • Application ID: The ID for the application.

    • Application Secret: The client secret for the application.

      Set the client secret directly in the Application Secret field only for testing purposes; you must configure the client secret as an ESV before you can promote configuration.

    • Well-known Endpoint:

      • If you are setting up Azure, this is the URL from the OpenID Connect metadata document field. In the URL, make sure to replace organization with the actual tenant ID for your tenant.

      • If you are setting up AD FS, this is the endpoint from the OpenID Connect section.

        Values for the following fields are automatically obtained from the Well-known Endpoint field value:

        • Authorization Endpoint: The endpoint for authentication and authorization. The endpoint returns an authorization code to the client.

        • Token Endpoint: The endpoint that receives an authorization code. The endpoint returns an access token.

        • User Info Endpoint: The endpoint that receives an access token. The endpoint returns user attributes.

    • (For OIDC only): OAuth Scopes: The scopes the application uses for user authentication. The default scopes are openid, profile, and email.

    • (For OIDC only): Client Authentication Method: Options are client_secret_post and client_secret_basic. The default option is client_secret_post.

    • Button Text: The text for the application button.

    • To use group membership to enable federation:

      1. Set up your identity provider:

      2. Select one of the following options:

        • For Microsoft Azure: Enable Use Microsoft Azure group membership to allow federated login to ForgeRock.

        • For AD FS: Enable Use ADFS group membership to allow federated login to ForgeRock.

      3. Enter the name of the group claim in the Group Claim Name field.

        By default, Azure sends the ID of the group. You may need to configure Azure to send the name of the group.

      4. To apply specific administrator access to a group, perform one of the following sets of steps:

        • Apply Super administrator access to a group: To the left of Super Admins, in the Group Identifiers field, enter the identifiers of the group(s).

        • Apply Tenant administrator access to a group: To the left of Tenant Admins, in the Group Identifiers field, enter the identifiers of the group(s).

  9. Click Save.

Configure federation login requirements

After you have enabled federated access to your tenant environments, you can choose how strictly to enforce it. It can be enforced for just tenant administrators or for both tenant administrators and super administrators[3]. These settings are stored in dynamic configuration, so need to be configured per environment.

To understand how the instructions in this section fit into the process of configuring federated access across your tenant environments, refer to step 5 in the high-level process.

  1. Log into the Advanced Identity Cloud admin UI as a super administrator[3].

  2. Go to Tenant settings, then click the Federation tab.

  3. In the Enforcement section, click Edit.

  4. On the Edit Tenant Federation Enforcement page, select one of the following items:

    • Optional for All Admins: Allow all administrators to use either their Advanced Identity Cloud credentials or federation to sign in.

    • Required for All Admins Except Super Admins: Allow all administrators that are not super administrators to use federation to sign in. Super admins can use their Advanced Identity Cloud credentials or federation to sign in.

    • Required for All Admins: Allow all administrators to use federation to sign in. If you choose this option, to switch to a lower enforcement level, you must submit a Backstage Support ticket.

  5. Click Update. It may take about ten minutes for the changes to take effect.

  6. On the Change Federation Enforcement? modal:

    • To confirm your changes, click Confirm.

    • To cancel your changes, click Cancel.

Deactivate a federation provider

You can deactivate a federation provider and reactivate it later. You may want to deactivate a federation provider if the provider is experiencing technical issues. If you deactivate all federation providers for a tenant, tenant administrators can no longer use federation to log into the tenant.

You can only deactivate a federation provider if one of the following is true:

  • Optional for All Admins is selected as the federation enforcement level (for background, refer to Configure federation login requirements).

  • More than one federation provider is enabled in the Advanced Identity Cloud tenant.

To deactivate a federation provider:

  1. Log into the Advanced Identity Cloud admin UI of your development environment as a super administrator[3].

  2. Go to Tenant settings, then click Federation.

  3. Perform one of the following actions:

    • To deactivate a federation provider, click the ellipsis icon () to the right of an active federation provider, then click Deactivate.

    • To activate a federation provider, click the ellipsis icon () to the right of a deactivated federation provider, then click Activate.

  4. Run a series of promotions to move the updated configuration to your staging and production environments.

Rotate a federation provider secret

If you have set up Microsoft Azure or AD FS as a federation provider, you must create and use a new client secret before the old one expires. If the client secret is stored in an ESV, you can rotate it by creating a new secret version.

For your development, staging, or production environment:

  1. In the federation provider configured for the environment, create a new secret and make a note of it:

    • For Azure AD, add a new client secret to the application.

    • For AD FS, reset the client secret for the application group.

  2. Add a new secret version to the ESV secret using the value of the new federation provider secret from the previous step. Refer to Update an ESV referenced by a configuration placeholder.

  3. Restart Advanced Identity Cloud services.

Set up Microsoft Azure AD as a federation identity provider

To set up Azure AD as a federation identity provider for PingOne Advanced Identity Cloud, perform the steps in the following sections in the order presented.

Azure AD is also known by the new name Microsoft Entra ID. Learn more in New name for Azure Active Directory.

Step 1: Complete Azure AD prerequisites

Before setting up Azure AD as a federation identity provider, you must set up an instance of Azure AD.

Step 2: Configure 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 Advanced 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/<azure-tenant-id>/v2.0/.well-known/openid-configuration.

Step 3: Use group membership to enable federation in Azure AD

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

Create groups containing Advanced Identity Cloud tenant administrators

Follow these steps to create a group in Azure AD that contains the Advanced 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 take effect in Advanced Identity Cloud.

Include additional claims in the tokens for Advanced 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: The groups the user belongs to.

  8. Select Add.

Set up Microsoft AD FS as a federation identity provider

To use AD FS as a federation identity provider for PingOne Advanced Identity Cloud, 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.

Step 1: Complete AD FS prerequisites

Before setting up AD FS as a federation identity provider, you must set up a self-hosted instance of AD FS version 4.0, running on Windows Server 2016 or higher.

Step 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 a relying party trust identifier for each of your tenant environments using the following URL format:

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

    For example, if one of your tenant environment FQDNs is "openam-mycompany-ew2.id.forgerock.io", use "https://openam-mycompany-ew2.id.forgerock.io/am" as the URL for that environment.

  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.

Step 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 Advanced 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 tenant Redirect URIs for each of your tenant environments using the following URL format:

        https://<tenant-env-fqdn>/login/admin

        For example, if one of your tenant environment FQDNs is "openam-mycompany-ew2.id.forgerock.io", use "https://openam-mycompany-ew2.id.forgerock.io/login/admin" as the URL for that environment.

    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.

Step 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 Advanced Identity Cloud.

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

Perform the following steps to instruct AD FS to include additional claims in the tokens that Advanced 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 Advanced 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 Advanced 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.

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

After you include any additional identity claims in tokens, you need to identify the well-known URI that the AD FS OpenID 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.

Step 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 identity 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 containing Advanced Identity Cloud tenant administrators

You need to 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.

Set up an OIDC-compliant federation identity provider

To set up an OIDC-compliant federation identity provider in PingOne Advanced Identity Cloud, 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-compliant identity provider. You will enter this URL when you enable the provider in Advanced Identity Cloud.

1. A UAT environment is an add-on capability.
2. A sandbox environment is an add-on capability.
3. A super administrator is a tenant administrator with elevated permissions for configuring tenant administrators and tenant federation. Refer to Types of administrators.