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:
-
Microsoft Azure Active Directory (Azure AD) using OpenID Connect. For more information, refer to What is Microsoft Entra ID?.
Azure AD is also known by the new name Microsoft Entra ID. Refer to New name for Azure Active Directory. -
Microsoft Active Directory Federation Services (AD FS) using OpenID Connect. For more information, refer to Active Directory Federation Services.
-
OpenID Connect (OIDC). For more information, refer to https://openid.net/connect/.
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:
-
Set up a federation provider for each of your tenant environments and make a note of the client secrets.
-
In your development environment:
-
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.
-
Create an ESV secret containing the federation provider client secret for your development environment:
-
Create a secret using the API (for background, refer to Manage ESVs using the API).
-
Create a secret using the Advanced Identity Cloud admin UI.
-
-
Insert the ESV placeholder into the configuration for the federation provider. Refer to Configure a federation provider secret.
-
-
(Optional) If you have a UAT[1] environment, adapt the next step to suit the revised promotion order. Refer to Additional UAT environments.
-
In your staging environment:
-
Repeat step 2b for your staging environment. Ensure the ESV name is 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. Refer to:
-
-
In your production environment:
-
Repeat step 2b for your production environment. Ensure the ESV name is 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[2] 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[2], development, UAT[1], staging, and production environments, ensure that it is configured with redirect URLs for each environment. |
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. |
-
Log into the Advanced Identity Cloud admin UI of your mutable environment (development or sandbox[2]) as a super administrator[3].
-
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, 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 identity provider:
-
For Microsoft Azure: 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: 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 sends the ID
of the group. You may need to configure Azure 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[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. |
-
Log into the Advanced Identity Cloud admin UI as a super administrator[3].
-
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 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.
-
-
Click Update. It may take about ten 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. 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:
-
Log into the Advanced Identity Cloud admin UI of your development environment as a super administrator[3].
-
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 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. Refer to Update an ESV referenced by a configuration placeholder.