Use OAuth 2.0 Authorization Code

Before you begin

To use the OAuth 2.0 authentication, you must first create an OAuth app with the remote service where you're going to connect.

Procedure

To add OAuth 2.0 authentication using the Authorization Code grant type:

  1. Click the Overview tab.

  2. Click Set up authentication.

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

  4. For the Grant Type dropdown, select Authorization Code.

  5. Add values to the following fields:

Field Definition
Paths
Authorization URL The authorization URL for the service.

This field should be a fully qualified URL. For example, https://account.box.com/api/oauth2/authorize.
Token URL The location where the flow exchanges an authorization code for access and refresh tokens.

This field should be a fully qualified URL. For example, https://api.box.com/oauth2/token.
Refresh URL (Optional) The refresh token path is often the same as the access token path.

However, if your service uses a separate endpoint for refreshing the access token, then it can be entered here.
Credentials
Redirect URI When registering a new app, you usually register basic information such as the application name or web site. In addition, you must register a redirect URL to be used for redirecting authentication back to Okta Workflows.

Copy the provided Redirect URI for your connector into your new OAuth app to register your connector with the service.

Use the following redirect URLs to connect to Okta preview and production sites, respectively:

  • https://oauth.workflows.oktapreview.com/oauth/{{auth.connector_key}}/cb

  • https://oauth.workflows.okta.com/oauth/{{auth.connector_key}}/cb

Your connector Key can be found on the Settings pane of the connector.

Registration is required for both preview and production environments.
Client Ownership This setting determines the type of user who manages the OAuth application. Options are Developer and Customer.

  • Developer: The connector builder who creates the application and manages its settings. The connector builder also supplies the values for the Client ID and Client Secret fields.

  • Customer: The end user of the application manages the client and provides the values for the Client ID and Client Secret fields. If you choose this option, the Client ID and Client Secret fields are automatically added to the New Connection dialog.
Client ID A publicly exposed string provided by the service that is used to identify the OAuth application and build authorization URLs.
Client Secret A private value provided by the service. This value is used to authenticate the application identity to the service.
Scopes (Optional)
Scopes Scopes specify the precise level of access provided to Okta Workflows. For a CAPIA card to hit all endpoints on an API, typically all scopes must be enabled in your app.

Click Add Scope for each scope you want to add for your connection.

Check your API documentation to verify whether a special scope is needed to retrieve a refresh token (such as refresh_token or offline_access).

Scopes Delimiter Specify a delimiter for how scopes are separated. Options are space and comma.

When passing multiple scopes are often space or comma separated, but this can depend on the service.

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: Shows a plain text field to the user. This is an open text field with no redaction.

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

  • Dropdown List: A manually created dropdown list of values that the user can select.
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: Shows a plain text field to the user. This is an open text field with no redaction.

  • Password: Shows 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

Add option fields to connector cards