--- title: Configuring OIDC SSO to PingFederate from an external IdP description: You can configure OpenID Connect (OIDC) single sign-on (SSO) for signing on to the PingFederate administrative console. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_configure_oidc_sso_to_pf_from_external_idp canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configure_oidc_sso_to_pf_from_external_idp.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: February 2, 2023 section_ids: before-you-begin: Before you begin about-this-task: About this task mapping-the-policy-contract-for-grant-fulfillment: Mapping the policy contract for grant fulfillment steps: Steps configuring-an-access-token-manager: Configuring an access token manager steps-2: Steps configuring-access-token-mapping: Configuring access token mapping steps-3: Steps creating-the-oidc-policy: Creating the OIDC policy steps-4: Steps creating-the-client: Creating the client steps-5: Steps creating-an-oauth-set-authentication-selector: Creating an OAuth Set Authentication selector steps-6: Steps creating-an-authentication-policy: Creating an authentication policy steps-7: Steps exporting-the-signing-certificate: Exporting the signing certificate steps-8: Steps importing-the-certificate-to-trusted-cas: Importing the certificate to trusted CAs steps-9: Steps configuring-properties-files: Configuring properties files steps-10: Steps example: Example: --- # Configuring OIDC SSO to PingFederate from an external IdP You can configure OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* single sign-on (SSO) *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* for signing on to the PingFederate administrative console. ## Before you begin Make sure you have the following in place: * A valid signing certificate. See [Manage digital signing certificates and decryption keys](help_certmanagementtasklet_dsigsigningcert_certmanagementstate.html). * An openID and a profile scope. See [Defining scopes](pf_defining_scopes.html). * A policy contract with at least the following attributes: `sub`, `admin_role`, `iss`, `memberOf`. See [Managing policy contracts](pf_managing_policy_contracts.html). * An identity provider (IdP) *(tooltip: \
\

A service that manages identity information and provides authentication services to relying clients or SPs within a federated or distributed network.\

\
)* connection in your PingFederate instance with the following attributes: `SAML_SUBJECT`, `memberOf` – fulfilled by the policy contract authentication source. See [Managing IdP connections](pf_manag_idp_connect.html). * An service provider (SP) *(tooltip: \
\

In SAML, an entity that receives and accepts an authentication assertion issued by an IdP, typically for the purpose of allowing access to a protected resource.\

\
)* connection in your external IdP with the following attributes: `SAML_SUBJECT`, `memberOf` – fulfilled by whichever authentication source is appropriate and using whatever authentication flows you require (for example, username/password and multi-factor authentication (MFA) *(tooltip: \
\

An electronic authentication method where a user is granted access only after presenting two or more verification factors for authentication.\

\
)*). See [Accessing SP connections](pf_accessing_sp_connections.html). ## About this task Configuring OIDC SSO for the PingFederate administrative console allows you to use an external IdP to authenticate administrative users. You can also use OIDC SSO to enable MFA because the administrative users are taken through an authentication policy flow that invokes an MFA adapter. Other console authentication types don't use authentication policies. ## Mapping the policy contract for grant fulfillment Complete the contract fulfillment. ### Steps 1. Go to **Authentication > OAuth > Policy Contract Grant Mapping**. 2. In the **Policy Contract** menu, select your policy contract, and click **Add Mapping**. 3. On the **Attribute Sources & User Lookup** tab, click **Next**. 4. On the **Contract Fulfillment** tab, map the **User\_Key** to the username from the policy contract. 1. Beside **User\_Key**, select **Authentication Policy Contract** in the **Source** menu and the policy contract's username in the **Value** menu. 2. Beside **User\_Name**, select **Authentication Policy Contract** in the **Source** menu and the policy contract's username in the **Value** menu. 3. Click **Next**. 5. On the **Issuance Criteria** tab, click **Next**. 6. On the **Summary** tab, verify your configuration, and click **Save**. ![Screen capture of the Policy Contract Mapping tab in which you configure the User\_Key and the User\_Name.](_images/pnv1657655969341.png) ## Configuring an access token manager Create a JSON Web Token (JWT) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* access token management instance. ### Steps 1. Go to **Applications > OAuth > Access Token Management**. 2. To create a new access token management instance, click **Create New Instance**. 3. On the **Type** tab: 1. Enter a name for the instance in the **Instance Name** field and an ID in the **Instance ID** field. 2. In the **Type** menu, select **JSON Web Tokens**. 3. Click **Next**. 4. On the **Instance Configuration** tab: 1. In the **Certificates** section, click **Add a new row to 'certificates'**. 2. In the **Key ID** field, enter an ID for the key. 3. In the **Certificate** menu, select your signing certificate, and click **Update**. 4. In the **JWS Algorithm** menu, select **RSA using SHA-256**. 5. In the **Active Signing Certificate Key ID** menu, select the key ID you entered in step b. ![Screen capture of the Instance Configuration tab, on which you select your certificate and give it a Key ID.](_images/eea1657822465791.png) 1. Click **Next**. 5. On the **Session Validation** tab, click **Next**. 6. On the **Access Token Attribute Contract** tab: 1. Make sure **User\_Key** is selected in the **Subject Attribute Name** menu. 2. In the **Extend the Contract** field, enter `admin_role`, and click **Add**. 3. Repeat step b to add the `iss`, `memberOf`, and `sub` attributes. 4. Click **Next**. 7. On the **Resource URIs** and **Access Control** tabs, click **Next**. 8. On the **Summary** tab, review your configuration. Click **Save**. ## Configuring access token mapping Map your policy contract context to the JWT access token manager. ### Steps 1. Go go **Applications > OAuth > Access Token Mappings**. 2. On the **Access Token Mappings** page in the **Context** menu, select your policy contract. 3. In the **Access Token Manager** menu, select your JWT ATM. 4. Click **Add Mapping**. 5. On the **Attribute Sources & User Lookup** tab, click **Next**. 6. On the **Contract Fulfillment** tab, select a **Source** and a **Value** to map into the `admin_role`, `iss`, `memberOf`, and `sub` attributes in the **Contract** list. ![Screen capture of the Contract Fulfillment tab, on which you select a source and a value to map into the admin\_role, iss, memberOf, and sub attributes.](_images/pjo1657817842645.png) 1. For the `admin_role` attribute, select **Expression** in the **Source** menu and, in the **Value** field, enter the following expression: ``` #filter1 = "^pf_admins.*", #filter2 = "^pf_cryptoadmins.*", #filter3 = "^pf_useradmins.*", #filter4 = "^pf_datacollectionadmins.*", #role1 = "admin", #role2 = "cryptoadmin", #role3 = "useradmin", #role4 = "expressionadmin", #role5 = "datacollectionadmin", #outboundattribute = new java.util.ArrayList(), #groups = #this.get("apc.memberOf")!=null?#this.get("apc.memberOf").getValues():{}, #i = 0, #groups.{ #group = #this, #group = new javax.naming.ldap.LdapName(#groups[#i]), #cn = #group.getRdn(#group.size() - 1).getValue().toString(), #cn.matches(#filter1)?#outboundattribute.add(#role1):null, #cn.matches(#filter1)?#outboundattribute.add(#role4):null, #cn.matches(#filter2)?#outboundattribute.add(#role2):null, #cn.matches(#filter3)?#outboundattribute.add(#role3):null, #cn.matches(#filter4)?#outboundattribute.add(#role5):null, #i = #i + 1}, #outboundattribute.size() > 0 ? new org.sourceid.saml20.adapter.attribute.AttributeValue(#outboundattribute):null ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This example OGNL expression gets the `memberOf` value from the policy contract, looks for group distinguished name (DN) *(tooltip: \
\

A name uniquely identifying an object within the hierarchy of a directory tree.\

\
)* that match the filters, and assigns a role when a filter is matched. In the expression, anyone that is in the Admins group is assigned both the Admin and Expression Admin role, because the Expression Admin role requires the Admin role assignment. Using this expression to map roles allows you to control access with groups from your identity provider's data source. Match your filter values in the expression to the group names created in your LDAP directory to assign those roles. | 2. For the `iss` attribute, select **Text** in the **Source** menu, and enter a text string in the **Value** field. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------ | | | Make a note of the text string. The value entered here is the issuer claim value and should identify the organization as the issuer. | 3. For the `memberOf` attribute, select **Authentication Policy Contract** in the **Source** menu, and **memberOf** in the **Value** menu. 4. For the `sub` attribute, select **Persistent Grant** in the **Source** menu, and **USER\_KEY** in the **Value** menu. 5. Click **Next**. 7. On the **Issuance Criteria** tab, click **Next**. 8. On the **Summary** tab, review your mappings. Click **Save**. ## Creating the OIDC policy ### Steps 1. Go to **Applications > OAuth > OpenID Connect Policy Management**. 2. Click **Add Policy**. 3. On the **Manage Policy** tab: 1. In the **Policy ID** field, enter the policy identifier. 2. In the **Name** field, enter the policy name. 3. In the **Access Token Manager** menu, select your JWT access token manager. 4. Click **Next**. 4. On the **Attribute Contract** tab, add the `admin_role`, `iss`, and `memberOf` attribute contracts. 1. In the **Extend the Contract** field, enter `admin_role`, and click **Add**. 2. Repeat step a. to add the `iss` and `memberOf` attributes. 3. Click the **Edit** action for `admin_role`. Select the **Override Default Delivery** and **ID Token** checkboxes, then click the **Update** action. 4. Repeat step c for `iss`, selecting the **ID Token** checkbox, and for `memberOf`, selecting the **UserInfo** checkbox. ![SCreen capture of the Attribute Contract tab, on which you extend the contract to include the admin\_role, iss, and memberOf attributes.](_images/bpw1657820858510.png) 5. Click **Next**. 5. On the **Attribute Scopes** tab, add the `admin_role` and `iss` attributes to the openid scope and the `memberOf` attribute to the profile scope. ![Screen capture of the Attribute Scopes tab, on which you add the admin\_role and iss attributes to the openid scope and the memberOf attribute to the profile scope.](_images/xrw1657824094263.png) 1. In the **Scope** menu, select **openid**. Select the `admin_role` attribute's checkbox, and click **Add**. The `iss` attribute should already be selected. 2. In the **Scope** menu, select **profile**. Select the `memberOf` attribute's checkbox, and click **Add**. 3. Click **Next**. 6. On the **Attribute Sources & User Lookup** tab, click **Next**. 7. On the **Contract Fulfillment** tab, select a **Source** and a **Value** to map into the `admin_role`, `iss`, `memberOf`, and `sub` items in the **Attribute Contract** list. ![Screen capture of the Contract Fulfillment tab, on which you select a source and a value for the admin\_role, iss, memberOf, and sub attributes.](_images/txv1657828359690.png) 1. For the `admin_role` attribute contract, select **Access Token** in the **Source** menu and **admin\_role** in the **Value** menu. 2. For the `iss` attribute contract, select **Access Token** in the **Source** menu and **iss** in the **Value** menu. 3. For the `memberOf` attribute contract, select **Access Token** in the **Source** menu and **memberOf** in the **Value** menu. 4. For the `sub` attribute contract, select **Access Token** in the **Source** menu and **sub** in the **Value** menu. 5. Click **Next**. 8. On the **Issuance Criteria** tab, click **Next**. 9. On the **Summary** tab, review your configuration. Click **Save**. ## Creating the client ### Steps 1. Go to **Applications > OAuth > Clients**, and click **Add Client**. 2. In the **Client ID** field, enter an ID for the client. 3. In the **Name** field, enter a name for the client. 4. In the **Client Authentication** section, select **Client Secret**. 5. In the **Client Secret** section, select the **Change Secret** checkbox and enter a password in the field. If preferred, you can click **Generate Secret**. 6. In the **Redirect URIS** field, enter the following URI, and click **Add**. `https:///pingfederate/app?service=finishsso` 7. For **Bypass Authorization Approval**, select the **Bypass** checkbox. 8. For **Allowed Grant Types**, select the **Authorization Code** checkbox. 9. In the **Default Access Token Manager** menu, select your JSON access token manager. 10. For **Restrict to Default Access Token Manager**, select the **Restrict** checkbox. 11. In the **OpenID Connect** section, in the **Policy** menu, select your OIDC policy. 12. Click **Save**. ## Creating an OAuth Set Authentication selector Create an OAuth Set Authentication selector and add your client to it. ### Steps 1. Go to **Authentication > Policies > Selectors**. 2. On the **Selectors** page, click **Create New Instance**. 3. On the **Type** tab, do the following. 1. In the **Instance Name** field, enter a name for the instance. 2. In the **Instance ID** field, enter an ID for the instance. 3. In the **Type** menu, select **OAuth Client Set Authentication Selector**. 4. Click **Next**. 4. On the **Authentication Selector** tab: 1. Click **Add a new row to Clients**. 2. In the **Client ID** menu, select your client, and click the **Update** action. 3. Click **Next**. 5. On the **Summary** tab, review your configuration. Click **Save**. ## Creating an authentication policy Create an authentication policy that is triggered by the selector, sends the user to the external IdP, and fulfills the policy contract. ### Steps 1. Go to **Authentication > Policies > Policies**. 2. Click **Create New Instance**. 3. Click **Add Policy**. 4. On the **Policy** page In the **Name** field, enter a name for the policy. 5. (Optional) In the **Description** field, enter a description for the policy. 6. Click in the **Policy** field, and select **Selectors** in the menu. ![Screen capture of the Policy menu with Selectors selected.](_images/qsd1658246087907.png) 7. Select your selector. 8. For the **No** option, click **Continue**. 9. For the **Yes** option, select **IdP Connections** in the menu, and select your IdP connection. 10. For the **Fail** option, click **Done**. 11. For the **Success** option, select **Policy Contracts** in the menu, and select your policy contract. 12. Click **Contract Mapping**. 13. On the **Attribute Sources & User Lookup** tab, click **Next**. 14. On the **Contract Fulfillment** tab, map the `memberOf`, `subject`, and `username` attributes. If your policy contract has additional attributes, select **No Mapping** in the **Source** menu for those attributes. 1. For the `memberOf` attribute, select **IdP Connection** in the **Source** menu and `memberOf` in the **Value** menu. 2. For the `subject` attribute, select **IdP Connection** in the **Source** menu and **SAML\_SUBJECT** in the **Value** menu. 3. For the `username` attribute, select **IdP Connection** in the **Source** menu and **SAML\_SUBJECT** in the **Value** menu. 15. On the **Issuance Criteria** tab, click **Next**. 16. On the **Summary** tab, review your configuration. Click **Done**. 17. On the **Policy** page, click **Done**. 18. On the **Policies** tab, click **Save**. ## Exporting the signing certificate When your PingFederate server is redirected to its own token endpoint, it must trust the certificate used to sign its tokens. ### Steps 1. Go go **Security > Certificate & Key Management > Signing & Decryption Keys & Certificates**. 2. In the **Action** menu for the certificate that PingFederate will use to sign its tokens, select **Export**. 3. On the **Export Certificate** tab, select **Certificate Only**, and click **Next**. 4. On the **Export & Summary** tab, click **Export**. 5. Click **Done**. ## Importing the certificate to trusted CAs After you have exported the signing certificate, you must import it to trusted certificate authorities. ### Steps 1. Go to **Security > Certificate & Key Management > Trusted CAs**. 2. Click **Import**. 3. On the **Import Certificate** tab, click **Choose File**. 4. Navigate to the location of the certificate that you exported, select it, and click **Open**. 5. On the **Import Certificate** page, click **Next**. 6. On the **Summary** tab, review your certificate information, and click **Save**. ## Configuring properties files Configure required parameters in PingFederate's `oidc.properties` and `run.properties` files. ### Steps 1. Configure the required parameters in the `/pingfederate/bin/oidc.properties` file. You'll need the client ID and secret from the client you created, and you should obfuscate the secret. You'll also need the `iss` attribute value you used in the access token manager mappings. Use the authorization and token endpoints with your PingFederate base URL. ### Example: An example configuration is shown here: ``` client.id=pfadminconsole client.authn.method=client_secret_basic client.secret=********* authorization.endpoint=https\://pingfed-idp.ad.jibboo.org\:9031/as/authorization.oauth2 token.endpoint=https\://pingfed-idp.ad.jibboo.org\:9031/as/token.oauth2 issuer=jibbooidp scopes=openid username.attribute.name=sub role.attribute.name=admin_role role.admin=admin role.cryptoManager=cryptoadmin role.userAdmin=useradmin role.expressionAdmin=expressionadmin role.dataCollectionAdmin=datacollectionadmin ``` 2. Configure the `pf.console.authentication` parameter in the `/pingfederate/bin/run.properties` file as follows: `pf.console.authentication=oidc` 3. Restart your PingFederate server.