Use OAuth 2.0 Authorization Code

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

As an added security layer, an OAuth 2.0 authorization server can return an authorization code to the client, which is exchanged for the access token.

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

Before you begin

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

Start this task

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

  1. Click the Overview tab.

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

  3. For the Grant Type dropdown menu, select Authorization Code.

  4. Add values to the following fields:

Field Definition

Paths

Base URL

The base URL for your OAuth server. The connector appends the access token paths to the Base URL value.

However, this field can be left blank if your Authorize Path, Token Path, and Refresh Token Path entries contain a fully qualified URL. This scenario is better if these access tokens are processed using different URLs.

Authorize Path

The location where the connector can retrieve access tokens for the service. For example, /authorize.

If Base URL is empty, this field must be a fully qualified URL. For example, https://account.example.com/api/oauth2/authorize.

Token Path

The location where the flow exchanges an authorization code for access and refresh tokens. For example, /oauth2/token.

If Base URL is empty, this field must be a fully qualified URL. For example, https://api.example.com/oauth2/token.

Refresh Token Path (Optional)

The location where the connector can obtain a new access token after the previous one expires.

The refresh token path is often the same as the access token path. If your service uses a separate endpoint for refreshing the access token however, then enter it here. For example, https://account.example.com/api/oauth2/reauthorize.

Credentials

Redirect URI

When registering a new app, you usually register basic information such as the app name or website. 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 in 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 created the application and manages its settings. The builder also supplies the values for the Client ID and Client Secret fields.

  • Customer: The end user of the application manages the client OAuth application. This person 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)

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, then 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.

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

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.

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.