Use OAuth 2.0 Client Credentials

OAuth 2.0 is an authorization protocol that grants access to a set of resources like remote APIs or user data.

For more details on OAuth 2.0, see What is OAuth 2.0?

Start this task

To add OAuth 2.0 authentication using the Client Credentials grant type:

  1. Click the Overview tab.

  2. Click Set up authentication to configure authentication for a new connection, or click Edit if you want to change the existing authentication method or parameters.

  3. In the Authentication dialog, select OAuth 2.0 from the Auth Type dropdown list.

  4. For the Grant Type dropdown menu, select Client Credentials.

  5. For the Client Authentication Type dropdown, select one of the following options:

    • Send as basic auth header (client_secret_basic): authentication sends the client credentials in the HTTP authentication header. This is the recommended option.

    • Send as basic auth body (client_secret_post): authentication sends the client credentials within the body of the request.

  6. Add values to the following fields:

Field Definition

Paths

Token URL

The location where the flow sends the client credentials.

This field should be a full URL. For example, https://api.box.com/oauth2/token.

Credentials

Client ID

A publicly exposed string provided by the service. This is used to identify the OAuth application and build authorization URLs.

The end user populates this field when they create the connection.

This field can't be removed and appears as a non-editable field in the Preview window.

Client Secret

A private value string provided by the service. This value is used to authenticate the application identity to the service.

The end user populates this field when they create the connection.

This field can't be removed and appears as a non-editable field in the Preview window.

Scopes (Optional)

Name

Each scope defines a precise level of access that the connection requests from the service. To add OAuth scopes to your connection:

  1. Click Add Scope to add the unique scopes you want to request for this connection to the service.

  2. Enter the name of the scope. For example, openid or offline_access.

    Use the toggle to indicate whether the scope is Required. To mark scopes as Required, you must first enable the Allow users to customize scopes option.

    When you mark a scope as required, it's always requested. Typically, these would be for any scopes necessary for the connector to work properly. Also, for a CAPIA card to call all the endpoints of an API generally requires that the connection has enabled all scopes.

    Each scope that you add appears on the Permissions tab of the New Connection preview.

  3. Select the Allow users to customize scopes option if you want to permit users to modify your list of scopes.

    This feature is useful when you want to allow your users to create multiple connections that call your service with different scopes. They can, for example, remove scopes to align with the principles of least privilege.

    For example, one connection to an email service might include the read-email scope for simple administration. Another, more advanced, connection to the same service could also include the delete-email and send-email scopes.

    This option adds a selector to your Permissions tab that gives your users two choices to define the scopes requested from your service.

    • Use default scopes: Requests all the scopes that you've defined.

    • Customize scopes: Users can remove any non-required scopes from your original list. Required scopes can't be cleared.

  4. Select the Allow users to request additional scopes option to permit users to add extra scope requests directly through your connector.

    They can enter scopes in the Manually add scopes field. This input field is limited to 500 characters. These can be added individually or as a list of scopes separated by either a space or a comma. The delimiter matches your selection for the Scopes Delimiter field.

    If you don't select this option, then users can ask for new scopes to be added to the connector through the Okta Ideas site. This link is included at the bottom of the Permissions tab.

    This option is available only if you enable the Allow users to customize scopes option.

When you change any component of your connector authentication including new scopes customizations, the updates don't apply to previously established action cards or connections in your development environment. However, finalized connectors provided by Okta, whether they are first or third-party connectors, don't have this restriction.

Scopes Delimiter

Specify a delimiter for how individual scopes are separated when entered by the user.

Options are Space and Comma.

Parameters (Optional)

Parameters allow you to collect additional information from the connector user that might be necessary for authentication, such as their instance or subdomain. These fields are presented to the user when they first create a connection and are required.

Label: The name for the parameter that is shown on the New Connection dialog when setting up the connector.

Key: Text value in the key-value pairing that the service uses. For example, api_key, application_key, or authentication.

Type: You can select three different field types:

  • Text: Display a plain text field to the user. This is an open text field with no redaction.

  • Password: Display a redacted text field. The user can't see what text is entered into this field.

  • Dropdown List: Display a manually created dropdown list of values that the user can select.

For a Client Credentials grant type, the Client ID and Client Secret parameters appear by default. You can add text to create a unique name for these labels, but these parameters can't be removed.

Config Values (Optional)

Other configuration values may be needed to define how a user authenticates to your connector. Click Add Config Value.

Label: The name for the configuration value that is shown on the New Connection dialog when setting up the connector.

Definition: Indicate whether this field is populated with a static value or a value from a helper flow.

  • For Static Value, enter the value in the Value field.

  • For Value from Helper Flow, select a flow from the Choose Flow dialog.

Type: You can select two different field types:

  • Text: Displays a plain text field to the user. This is an open text field with no redaction.

  • Password: Displays a redacted text field. The user can't see what text is entered into this field.

The Visible toggle determines whether the configuration value appears in the authentication dialog for the connector.

Next steps

After you create this authentication method, you need to create an httpHelper flow to manage calls through the authentication method. See Build an httpHelper flow.