Creating a Custom OAuth Application

CData embeds OAuth Application Credentials with CData branding that can be used when connecting to PingOne via a desktop application or a headless machine. These connections do not require the use of a custom OAuth application.

However, the creation of a custom OAuth application is required for connecting to PingOne via the Web, and does seamlessly support all three commonly-used auth flows. And since custom OAuth applications seamlessly support all three commonly-used auth flows, you might want to create custom OAuth applications (use your own OAuth Application Credentials) for those auth flows anyway.

Custom OAuth applications are useful if you want to:

• Control branding of the authentication dialog.
• Control the redirect URI that the application redirects the user to after the user authenticates.
• Customize the permissions that you are requesting from the user.

This topic describes how to create and configure a custom OAuth application. For further information about the post-creation steps, see these PingOne manuals:

• Editing an application - Worker
• Editing an application - OIDC
• Configuring roles for a Worker application

Creating the Custom Application

1. Sign in to your PingOne organization's admin console with your administrator account. Your organization's home page displays.
2. In the left navigation pane, click Environments. A list of environments displays.
3. Click the environment where you want your custom OAuth application to reside. (This should probably be the Administrators environment.)
4. Click Manage Environment. The home page of the environment you just chose displays.
5. In the left navigation pane, click Applications.
6. To create a new application, click the + button at the top left corner of the page. The console displays the New Application form.
7. Provide an Application Name for the custom OAuth application.
8. Set Application Type to Worker.
9. Click Save. The console displays the Application Details for your new custom OAuth application.

Post-Creation Steps

Still in the Application Details form:

1. In the Overview tab:
   • Copy the values for Client ID and Client Secret for future use. These are used to set the OAuthClientId and OAuthClientSecret parameters.
   • Optional: If you have not configured a custom domain for the environment you chose, copy the value for the Environment ID for future use. This is used to set the WorkerAppEnvironmentId.
2. In the Configuration tab, click the pencil icon to the right of a field to edit its values. Edit the following fields:
   • Response Type: Select only the Code option.
   • Grant Type: Is authentication-dependent. Note that multiple options/grant types can be configured at the same time, so you can use different authentication schemes with the same OAuth application.
     • For OAuth authentication, select both the Authorization Code and Refresh Token options. Make sure that PKCE Enforcment is set to Optional (default).
     • For OAuthClient authentication, select Client Credentials.
   • Redirect URIs: Depends on the type of OAuth flow.
     • For desktop applications and headless machines, use http://localhost:33333 or another port number of your choice. The URI you set here becomes the CallbackURL property.
     • For web applications, set the callback URL to a trusted redirect URL. This URL is the web location the user returns to with the token that verifies that your application has been granted access.

     Note: The Refresh Duration, Refresh Token Rolling Duration and Refresh Token Rolling Grace Period fields are all optional. For detailed information about these fields, see Editing an application - OIDC.

3. In the Advanced section, we recommend that you enable the Additional Refresh Token Replay Protection field, as a good security practice. You can leave every other field as is.
4. To save your changes, click Save.

Assigning Roles

The Roles tab of your Application Details enables you to assign administrator roles to your new application. The administrator roles assigned to an OAuth/Worker application apply only when the server requests access on behalf of the application, and not the user. (For example, when using the OAuthClient authentication scheme.) If no administrative roles are assigned to the application, the user account's administrator roles are used.

To configure the administrator roles, click Grant Roles.

When you are finished, click Save.

For further information about configuring administrator roles, see Administrator Roles.

Restricting Access

The Access tab of your Application Details enables you to configure the application to restrict access to user accounts in certain groups.

These configurations are optional. If you are using a redirect-based OAuth authentication scheme such as OAuth, the account you use for signing in the authorization URL must have proper access configured to the custom application you just created, or OAuth initialization fails.

Click the pencil icon to the right of the fields in the Group Membership Policy section to edit their values as needed.

When you are finished, click Save.