Configure federated access for tenant administrators
Federated access lets tenant administrators use your company’s single sign-on (SSO) to sign on 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 (IdP) 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 IdP. You can also specify the type of administrator access for an entire group of users.
Advanced Identity Cloud lets you configure federated access in two main ways:
-
You can use PingOne to configure PingOne itself as an IdP for Advanced Identity Cloud. Learn more in Configure a federation provider using PingOne.
-
You can use the Advanced Identity Cloud admin UI to configure Microsoft Azure Active Directory (Azure AD)[1] or Microsoft Active Directory Federation Services (AD FS) as IdPs, or any other IdP that’s OpenID Connect (OIDC) compliant. Learn more in Configure a federation provider using PingOne Advanced Identity Cloud.
Configure a federation provider using PingOne
You can configure PingOne as a federation IdP for PingOne Advanced Identity Cloud. To do this, configure it in PingOne itself. Learn more in Set up SSO to PingOne Advanced Identity Cloud.
After you configure PingOne as a federation IdP, each configured tenant environment in Advanced Identity Cloud automatically displays PingOne in its list of federation IdPs:
-
Sign on to the Advanced Identity Cloud admin UI for any of the environments you configured for federated access using PingOne.
-
Go to Tenant settings.
-
Click Federation.
-
If configured correctly in PingOne, the list contains a PingOne federation IdP:
-
Click the PingOne list item to view its configuration settings page. For PingOne, this is a basic page containing the Status and the Well-Known Endpoint of the PingOne federation IdP:
If you configure a federation IdP in PingOne, the corresponding Advanced Identity Cloud tenant environments are configured automatically. You do not need to promote configuration changes.
Configure a federation provider using PingOne Advanced Identity Cloud
You can configure the following federation IdPs using the Advanced Identity Cloud admin UI:
-
Microsoft Azure AD[1] using OpenID Connect.
-
Microsoft AD FS using OIDC.
-
Any other federation IdP that’s OIDC compliant.
If you configure a federation IdP using the Advanced Identity Cloud admin UI, you must do so in your development environment and promote the configuration changes. You must also store the federation provider secrets for each of your environments in ESV secrets and set corresponding placeholders in your configuration. Learn more in Configure federated access across your tenant environments.
Configure federated access across your tenant environments
The high-level process to set up federated access across your tenant environments is as follows:
-
Set up a federation provider for each of your tenant environments and note the client secrets.
-
In your development environment:
-
Configure the environment to use a federation provider, entering the federation provider values for your development environment. These values will be replaced by ESVs in the following steps.
-
Create ESVs for these federation provider fields:
Federation provider field ESV type Well-known endpoint
Variable
Authorization endpoint
Variable
Token endpoint
Variable
Client secret
Secret
Redirect URI
Variable
-
Create a variable or create a secret using the API.
-
Create a variable or create a secret using the Advanced Identity Cloud admin UI.
-
-
Insert ESV placeholders into the configuration for the federation provider. Learn more in Configure a federation provider.
-
-
(Optional) If you have a UAT[2] environment, adapt the next step to suit the revised promotion order. Learn more in Additional UAT environments.
-
In your staging environment:
-
Repeat step 2b for your staging environment. Ensure the ESV names are the same as you set up in the development environment.
-
Run a promotion to move the configuration change from your development environment to your staging environment. Learn more in:
-
-
In your production environment:
-
Repeat step 2b for your production environment. Ensure the ESV names are the same as you set up in the development environment.
-
Run a further promotion to move the configuration change from your staging environment to your production environment.
-
-
(Optional) If you have a sandbox[3] environment:
-
Repeat step 2a for your sandbox environment.
-
(Optional) Repeat step 2b – d for your sandbox environment.
-
-
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[3], development, UAT[2], staging, and production environments, ensure that it is configured with redirect URLs for each environment. |
Set up a federation provider
You can find instructions for setting up a federation provider in the following guides:
Configure a mutable environment to use a federation provider
After you’ve set up a federation provider, you can configure it in a mutable environment (development or sandbox[3]) 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. |
-
Sign on to the Advanced Identity Cloud admin UI of your mutable environment (development or sandbox[3]) as a super administrator[4].
-
Go to Tenant settings.
-
Click Federation.
-
Click + Identity Provider.
-
Select the federation provider to use:
-
Microsoft Azure
-
ADFS
-
OIDC
-
-
Click Next.
-
Follow the steps on the Configure Application page and click Next.
-
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 AD, 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
, andemail
. -
(For OIDC only): Client Authentication Method: Options are
client_secret_post
andclient_secret_basic
. The default option isclient_secret_post
. -
Button Text: The text for the application button.
-
To use group membership to enable federation:
-
Set up your IdP:
-
For Microsoft Azure AD: Follow the instructions in Use group membership to enable federation in Azure AD.
-
For AD FS: Follow the instructions in Enable federation in AD FS using group membership.
-
-
Select one of the following options:
-
For Microsoft Azure AD: 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.
-
-
Enter the name of the group claim in the Group Claim Name field.
By default, Azure AD sends the ID
of the group. You might need to configure Azure AD to send thename
of the group. -
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).
-
-
-
-
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[4]. 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. |
-
Sign on to the Advanced Identity Cloud admin UI as a super administrator[4].
-
Go to Tenant settings, then click the Federation tab.
-
In the Enforcement section, click Edit.
-
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 on.
-
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 on.
-
Required for All Admins: Allow all administrators to use federation to sign on. If you choose this option, to switch to a lower enforcement level, you must submit a Backstage Support ticket.
-
-
Click Update. It can take about 10 minutes for the changes to take effect.
-
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. For example, you might 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 sign on to 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 (learn more in Configure federation login requirements). -
More than one federation provider is enabled in the Advanced Identity Cloud tenant.
To deactivate a federation provider:
-
Sign on to the Advanced Identity Cloud admin UI of your development environment as a super administrator[4].
-
Go to Tenant settings, then click Federation.
-
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.
-
-
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 AD 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:
-
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.
-
-
Add a new secret version to the ESV secret using the value of the new federation provider secret from the previous step. Learn more in Update an ESV referenced by a configuration placeholder.
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
-
In a browser, navigate to the Microsoft Azure portal dashboard.
-
On the Azure Active Directory admin center page, navigate to Azure Active Directory > App registrations.
-
Click + New registration.
-
On the Register an application page, enter the application Name.
-
Select one or more Supported account types that can use the application or access the API.
-
In the Redirect URI (optional) section, in the drop-down list, select Web.
-
Enter the Redirect URI (from the Redirect URI field on the Advanced Identity Cloud azure page).
-
Click Register.
-
Click Add a certificate or secret.
-
Add a new client secret.
-
Copy or make note of your application client ID and client secret.
-
Save your changes.
-
On the Azure Active Directory admin center page, navigate to Azure Active Directory > App registrations.
-
Click Endpoints at the top of the page.
-
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.
-
On the Azure Active Directory admin center page, navigate to Azure Active Directory.
-
In the left menu pane, under Manage, select Groups.
-
On the top menu bar, select New group.
-
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.
-
-
Select Create.
-
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.
-
On the Azure Active Directory admin center page, navigate to Azure Active Directory.
-
In the left menu pane, under Manage, select App registrations.
-
Choose your application.
-
Under Manage, select Token configuration.
-
Select Add optional claim.
-
Select the ID token type.
-
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.
-
-
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.
-
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 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.
-
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 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.
-
In the AD FS editor, select Application Groups.
-
In the Actions pane, select Add Application Group.
-
Complete the Add Application Groups wizard as follows:
-
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.
-
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.
-
-
On the Configure Application Credentials page:
-
Select Generate a shared secret. The secret acts as a password for the application.
-
Use the Copy to clipboard button to copy the secret.
-
-
Click Next.
-
On the Configure Web API page, add the
client identifier
you noted earlier. -
Click Next.
-
On the Choose Access Control Policy page, select the appropriate settings according to your corporate policy.
-
Click Next.
-
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.
-
-
Click Next.
-
On the Summary page, review your selections.
-
Click Next.
-
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.
-
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.
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.
-
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.
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.
-
In the AD FS editor, select Application Groups.
-
In the Actions pane, select the group you previously created.
-
Right-click the group and select Properties.
-
In the Applications section, in the Web API area, select your application, and click Edit.
-
Click the Issuance Transform Rules tab.
-
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 Claims Using a Custom Rule.
-
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.
-
-
-
Click Finish.
-
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 Claims Using a Custom Rule.
-
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.
-
-
-
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:
-
Configure an OIDC client profile:
-
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.
-
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.
-
Configure the allowed scopes. Recommended scopes:
openid
,profile
, andemail
. -
Configure the client authentication method. Supported authentication methods:
client_secret_post
andclient_secret_basic
.
-
-
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.