PingFederate Server

Configuring OIDC SSO to PingFederate from an external IdP

You can configure OpenID Connect (OIDC) single sign-on (SSO) 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.

  • An openID and a profile scope. See Defining scopes.

  • A policy contract with at least the following attributes: sub, admin_role, iss, memberOf. See Managing policy contracts.

  • An identity provider (IdP) connection in your PingFederate instance with the following attributes: SAML_SUBJECT, memberOf – fulfilled by the policy contract authentication source. See Managing IdP connections.

  • An service provider (SP) 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)). See Accessing SP connections.

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.

Configuring an access token manager

Create a JSON Web Token (JWT) 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.

    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.

    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.*",
#role1 = "admin",
#role2 = "cryptoadmin",
#role3 = "useradmin",
#role4 = "expressionadmin",

#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,

#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) 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 check boxes, then click the Update action.

    4. Repeat step c for iss, selecting the ID Token check box, and for memberOf, selecting the UserInfo check box. SCreen capture of the Attribute Contract tab, on which you extend the contract to include the admin_role, iss, and memberOf attributes.

    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.

    1. In the Scope menu, select openid. Select the admin_role attribute’s check box, and click Add. The iss attribute should already be selected.

    2. In the Scope menu, select profile. Select the memberOf attribute’s check box, 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.

    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 check box 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://<your PingFederate admin server hostname>/pingfederate/app?service=finishsso

  7. For Bypass Authorization Approval, select the Bypass check box.

  8. For Allowed Grant Types, select the Authorization Code check box.

  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 check box.

  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.

  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 <pf_install>/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

  2. Configure the pf.console.authentication parameter in the <pf_install>/pingfederate/bin/run.properties file as follows: pf.console.authentication=oidc

  3. Restart your PingFederate server.