Use Cases

Setting up an OIDC application in PingFederate

Create a new OAuth or OpenID Connect (OIDC) application in PingFederate.

Before you begin

Component

  • PingFederate 10.1

Do the following:

Steps

  1. In the PingFederate administrative console, go to Applications > OAuth > Clients, and click Add Client.

  2. In the Client ID field, provide a client ID.

    The client ID is a unique identifier and cannot have the same ID as another OAuth client.

    You cannot change a client ID after it is set.

  3. In the Name field, enter a name for the client.

    The name value is a descriptive name displayed for end users that indicates the purpose of the client.

  4. In the Description field, provide a description that gives additional detail on the use of the client.

  5. Select a Client Authentication method:

    Choose from:

    • None

    • Client TLS Certificate

      1. In the Issuer list, select the certificate for a trusted issuer if the client should expect certificates from a specific issuer. If certificates from any issuer should be allowed, select Trust Any.

      2. In the Subject DN field, enter the subject DN for the certificate or extract it from a file by clicking Choose File, selecting an appropriate certificate, and then clicking Extract.

    • Private Key JWT

      1. Select the Replay Prevention checkbox if the client should require a unique JSON web token (JWT) for each request.

      2. From the Signing Algorithm list, select the specific algorithm for the incoming JWT, or to allow any supported signing algorithm to be used, select Allow Any.

    • Client Secret

      If selected as the authentication method, you must provide a client secret. If you select another method for authentication, you don’t need a client secret.

      1. Select the Change Secret checkbox.

      2. In the Client Secret field, enter a client secret, or to have a random value provided, click Generate secret. Make a copy of this value because it won’t be visible after the client is saved.

        Screen capture showing the different Client Authentication options. The options are None, Client Secret, Client TLS Certificate, and Private Key JWT. Each option has a radio button next to it. After the Client Authentication section is the Client Secret section. The field says, 'No Secret Defined', and to the right of the field is the Generate Secret button. After the field is the Change Secret checkbox.

  6. If the client requires all requests to be signed, select the Require Signed Requests checkbox.

  7. If you selected Require Signed Requests checkbox, select the expected signing algorithm or select Allow Any.

  8. If you selected Private Key JWT as the authentication method, or if you selected the Require Signed Requests checkbox, complete either the JWKS URL or JWKS fields:

    1. To use a JSON web key set (JWKS) URL, enter the URL of the JWKS.

    2. To provide the JWKS directly, copy and paste the contents of the JWKS in the JWKS field.

  9. If the client will be configured to support the OAuth authorization code or implicit flows, in the Redirection URI section, enter at least one URI.

    The redirection URI values specify the valid redirection locations that an application might request post authorization. The redirection URI value must be a fully qualified URL. Wildcards can be used to allow redirection into any sub-path. Make redirection URIs as restrictive as possible.

    1. In the Redirection URI field, enter a value.

    2. Click Add.

    3. Repeat steps 9a and 9b for each valid redirection URI.

  10. In the Logo URL field, enter a fully qualified URL.

    This is the URL for the logo image that displays on the User Grant Authorization and Revocation pages.

  11. If the client will use the PingFederate authentication API for authentication and will require an experience that doesn’t use HTTP redirections, select the Allow Authentication API OAuth Initiation checkbox.

    • The Bypass Authorization Approval checkbox is automatically selected and can’t be changed because this flow doesn’t support the user-facing grant consent page.

    • The Restrict Common Scopes checkbox is automatically selected and can’t be changed because this flow doesn’t support the user-facing grant consent page.

    • Any configured Common Scopes and the default openID scope is displayed and can be selected as valid scopes for the client.
    Screen capture showing the Allow Authentication API OAuth Initiation, Bypass Authorization Approval, and Restrict Common Scopes options. Each option as a checkbox. All three checkboxes are selected. The Bypass and Restrict checkboxes are grayed out to show that they are selected by default and cannot be changed.

  12. If any exclusive scopes are defined and the client should be allowed to use them, select the Exclusive Scopes checkbox.

    Any defined exclusive scopes are displayed and can be selected as available to this client.

  13. In the Allowed Grant Types list, select at least one option.

    Screen capture showing the options for Allowed Grant Types. Each option has a checkbox next to it. The options are Authorization Code, Implicit, Refresh Token, Client Credentials, Device Authorization Grant, CIBA, Token Exchange, Resource Owner Password Credentials, Assertion Grants, Access Token Validation (Client is a Resource Server).

    Learn more about each grant type in Grant Types.

  14. If the client should restrict the available response types requested by the application, select the Restrict Response Types checkbox.

    1. In the list of available response types, select at least one option.

      Screen capture the Restrict Response Types option with the checkbox for Restrict selected. After this checkbox is a list of options and checkboxes for response types to restrict. The options are code, code id_token, code id_token token, code token, id_token, id_token token, token.

  15. In the Default Access Token Manager list, select the default access token manager (ATM) for this client.

    The Default ATM can either be the default ATM configured in Access Token Mappings or a specific ATM.

  16. Optional: For resource server clients that won’t receive a specific request for an ATM, select the Validate Against All Eligible Access Token Managers checkbox to instruct PingFederate to validate access tokens against all available ATMs.

  17. If the client should require PKCE, select the Require Proof Key for Code Exchange (PKCE) checkbox.

    This checkbox isn’t displayed unless Authorization Code is selected under Allowed Grant Types.

  18. Override the global setting for the Persistent Grants Max Lifetime set in System > OAuth Settings > Authorization Server Settings:

    Choose from:

    • To use the global setting (default), click Use Global Setting.

    • For grants that should not have an expiration, click Grants Do Not Expire.

    • To enter a custom duration for this client’s grants, click the radio button below Grants Do Not Expire.

  19. Override the global setting for the Refresh Token Rolling Policy set in System > OAuth Settings > Authorization Server Settings.

    The client can override the global setting.

    Choose from:

    • To use the global setting (default), click Use Global Setting.

    • To tell the client to never roll the refresh token, click Don’t Roll.

    • To tell the client to roll the refresh token, click Roll.

  20. Change the default option for the token signing algorithm by selecting a different value in the ID Token Signing Algorithmlist.

  21. If the content of the ID token should be encrypted, then in the ID Token Key Management Encryption Algorithm list, select the algorithm that will be used to encrypt the content encryption key.

  22. (Optional) If an ID Token Key Management Encryption Algorithm is selected, then in the ID Token Content Encryption Algorithm list, select the value of the encryption algorithm used to encrypt the plaintext content of the ID token.

  23. To have the client use a specific OIDC policy, in the Policy list, select a specific value.

    By default, the client uses the OIDC policy configured as default in Applications > OAuth > OpenID Connect Policy Management.

  24. To enable pairwise pseudonymous identifiers for open banking support, select the Use Pairwise Identifier checkbox.

    • In the Sector Identifier URI field, enter a single HTTPS URI.

  25. To send logout requests to an OIDC endpoint in PingAccess as part of the logout process, select the PingAccess Logout Capable checkbox.

    This checkbox only displays if the Track User Sessions for Logout option is selected in System > OAuth Settings > Authorization Server Settings.

  26. Enter a fully qualified URI in the Logout URIs field and click Add for each endpoint desired.

    The Logout URIs field is displayed only if the Track User Sessions for Logout option is selected in System > OAuth Settings > Authorization Server Settings.

    PingFederate sends logout requests to each relying party listed.

    Screen capture of the OpenID Connect section and the fields for ID Token Signing Algorithm, ID Token Key Management Encryption Algorithm, Policy, and Logout URIs. The ID Token Signing Algorithm field is set to Default. The ID Token Key Management Encryption Algorithm field is set to No Encryption. The Policy field is set to Default. After the Policy field are two checkboxes. One checkbox is for the Use Pairwise Identifier option. One checkbox is for the Logout Capable option. The Logout URIs field is blank. To the right of this field is an Add button.

  27. To allow the client to use the back-channel session revocation API, select the Allow Access to Session Revocation API checkbox.

  28. To allow the client to use the session management API, select the Allow Access to Session Management API checkbox.

  29. Override the global values set by clicking Override in System > OAuth Settings > Authorization Server Settings.

    The Device Authorization Grant settings section is only displayed If Device Authorization Grant is selected in Allowed Grant Types.

    1. To allow the client to override the global value for the user authorization URL, in the User Authorization URL field, enter a fully qualified URL.

    2. To allow the client to override the global value for an activation code, in the Pending Authorization Timeout (seconds) field, specify a timeout value.

    3. To allow the client to override the global value for the device’s polling interval to the PingFederate token endpoint, in the Device Polling Interval (seconds) field, enter an interval value.

    4. To allow the client to override the global setting for bypassing the confirmation of an activation code, select the Bypass Activation Code Confirmation checkbox.

      Screen capture of the Device Authorization Grant section. The section starts with radio buttons for the Use Global Settings and Override options. After the radio buttons are the User Authorization URL, Pending Authorization Time (seconds), and Device Polling Interval (seconds)fields. After the fields is the Bypass Activation Code Confirmation checkbox.

  30. Configure the following CIBA settings:

    The CIBA section is displayed only if CIBA is selected in Allowed Grant Types.

    1. In the Token Delivery Method field, specify token delivery method for the client:

      • If the client can check authorization results at the token endpoint, select Poll.

      • If the client expects a callback when authorization results are available, select Ping.

    2. If you selected Ping, in the Notification Endpoint field that displays, enter the client notification endpoint for PingFederate to provide call back messages for this client.

    3. If you selected Poll, to override the default polling interval, in the Polling Interval field, specify a value..

      The default polling interval for Poll clients is 3 seconds.

    4. To override the default CIBA request policy configured in Applications > OAuth > CIBA > Request Policies, in the Policy list, select a different request policy.

    5. To enable support for the user code in the client, select the User Code Support checkbox.

    6. To require CIBA signed requests, select the Require CIBA Signed Requestscheckboxx.

    7. To select a specific algorithm, in the CIBA Request Object Signing Algorithm list, select a specific value.

      By default, the client supports any signing algorithm for the CIBA request object.

      Screen capture of the CIBA section and the corresponding fields. The section starts with Poll and Ping radio button options for Token Delivery Mode. After the radio buttons is the Polling Interval (seconds) field. Next is the Policy list with checkboxes below for User Code Support and Require CIBA Signed Requests. Finally is the CIBA Request Object Signing Algorithm list.

  31. To override the default processor policy configured in Applications > Processor Policies, in the Processor Policy list, select a specific process policy.

    If Token Exchangeis selected in Allowed Grant Types, the Token Exchange section is displayed.

  32. If any extended properties are defined in System > Extended Properties, click Next to continue to the Extended Properties options for the client.

  33. Click Save.