---
schema_version: "1"
id: de00a590088a8d49accf2c437f8b2303b4c2594f91789aed1a1ec246eed41427
title: Configuring OAuth 2.0 for Connectors
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/connectors/introduction/intro-config-oauth2.md
canonical_url: https://docs.mulesoft.com/connectors/introduction/intro-config-oauth2
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 968d7d1a8b41d94a05c8384452228d5176dcde3d6678d0d6821375bda8eaa05f
description: MuleSoft Documentation Site
latest: true
---
---
product: Connectors
---

# Configuring OAuth 2.0 for Connectors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Many services enable you to use an OAuth 2.0 authentication scheme for increased security when
interacting with their APIs. Many connectors support configuring a standard OAuth 2.0 setup.

## Prerequisites

To configure OAuth 2.0 for a connector, you must have access to the following:

- OAuth provider (Okta, Azure AD, Google, PingFederate, and so on)

- Anypoint Studio

## OAuth 2.0 Configuration Fields

Here are the configuration fields typically available for OAuth 2.0 for connectors. For more
information, see [OAuth](https://docs.mulesoft.com/mule-sdk/latest/oauth).

**OAuth 2.0 Authorization Code:**

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><p><strong>Consumer Key</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>OAuth consumer key, as registered with the service provider.</p></div></div></td><td><div></div></td><td><div><div><p>X</p></div></div></td></tr><tr><td><p><strong>Consumer Secret</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>OAuth consumer secret, as registered with the service provider.</p></div></div></td><td><div></div></td><td><div><div><p>X</p></div></div></td></tr><tr><td><p><strong>Authorization URL</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>URL of the service provider’s authorization endpoint in which the user is redirected to provide their user credentials. This URL typically ends with <code>/authorize</code>.</p></div></div></td><td><div></div></td><td><div><div><p>X</p></div></div></td></tr><tr><td><p><strong>Access Token Url</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>URL of the service provider’s access token endpoint in which the app automatically exchanges an authorization code for an access token.</p></div></div></td><td><div></div></td><td><div><div><p>X</p></div></div></td></tr><tr><td><p><strong>Scopes</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>Space-delimited list of OAuth scopes to request during the OAuth dance. This value defaults to the scopes in the annotation.</p></div></div></td><td><div><div><p><code>offline_access</code></p></div></div></td><td><div></div></td></tr><tr><td><p><strong>Resource Owner ID</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>ID of the resource owner’s account that authorizes the connector to access their resources.</p></div></div></td><td><div></div></td><td><div></div></td></tr><tr><td><p><strong>Auth Server Tls Context</strong></p></td><td><div><div><p>TLS Context</p></div></div></td><td><div><div><p>TLS context to use for HTTP requests to the authorization server during the OAuth dance. Available in Mule runtime 4.10.0 and later.</p></div></div></td><td><div></div></td><td><div></div></td></tr><tr><td><p><strong>Auth Server Proxy Config</strong></p></td><td><div><div><p>Proxy Config</p></div></div></td><td><div><div><p>Proxy configuration to use for HTTP requests to the authorization server during the OAuth dance. Available in Mule runtime 4.10.0 and later.</p></div></div></td><td><div></div></td><td><div></div></td></tr></tbody></table>

**OAuth 2.0 Callback Configuration:**

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Name</th><th>Type</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><p><strong>Callback Path</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>Server path to which the user’s browser is redirected to after the OAuth provider successfully authenticates the user. The callback path is typically <code>/callback</code>. This configuration uses your <strong>HTTP Listener</strong> setup to build the callback path, for example, <code>http://0.0.0.0:{port}/callback</code>.</p></div></div></td><td><div></div></td><td><div><div><p>X</p></div></div></td></tr><tr><td><p><strong>Authorize Path</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>Server path in which the user begins the OAuth dance. The authorize path is typically <code>/authorize</code>.</p></div></div></td><td><div></div></td><td><div><div><p>X</p></div></div></td></tr><tr><td><p><strong>External Callback Url</strong></p></td><td><div><div><p>String</p></div></div></td><td><div><div><p>Full, publicly accessible URL on your server in which the user’s browser is redirected to when authorization is successful with the OAuth provider. This field enables you to override the <strong>Callback path</strong> field, for example, <code>http://my.server.com/callback</code>.</p></div></div></td><td><div></div></td><td><div></div></td></tr></tbody></table>

## OAuth 2.0 Flow Overview

Anypoint Connectors use the Authorization Code Grant flow for their OAuth 2.0 dance. The following
steps show a typical flow for configuring OAuth 2.0 for a connector:

1.  In your browser, navigate to the path specified in the **Authorize Path** field to begin the
    OAuth dance. For example, if you are running the connector on `localhost` and your path is set
    to `/authorize` with port `8080`, navigate to `http://localhost:8080/authorize`.

2.  Provide values for the **Authorization URL**, **Scopes**, **Resource Owner ID**, and **Callback
    Path** fields. The following conditions must be true for the OAuth provider to accept the
    authorization request:

    - The **Authorization URL** is reachable from the user’s browser.

    - The provided scopes for **Scopes** are supported.

    - The **Resource Owner ID** (if provided) is registered with the OAuth provider.

    - The full **Callback Path** is registered with the OAuth provider.

3.  Enter your username, password, and other credentials that the OAuth provider accepts, such as
    2FA requests. If the authentication is successful, the OAuth provider might ask permission for
    the app to access your account. This typically occurs the first time you authenticate.

4.  Once the OAuth provider authenticates the user and authorizes access to the connector, the
    user’s web browser is redirected to the callback URL that is registered with the OAuth provider,
    for example, `http://localhost:8080/callback`.

    Ensure that the user running the flow has access to the server and endpoint; otherwise, the
    authorization approval will not reach the connector.

    You can use `localhost` for testing locally, but you cannot use `localhost` for production
    environments and cloud deployment. For example, if your connector app is running on
    `http://my.server.com`, you must specify the **External Callback Url** field with the
    `http://my.server.com/callback` value. The `http://my.server.com/callback` URL must also be
    registered with the OAuth provider.

5.  Once the user’s browser successfully reaches the callback URL, the connector obtains an
    authorization code that is automatically exchanged for an access token using the URL configured
    in the **Access Token URL** field. This token is long-lived and is automatically refreshed by
    the connector indefinitely (if allowed by the OAuth provider).

The connector is now fully authorized and can use any service that accepts the new access token
issued by the OAuth provider.

## Example: How to Configure OAuth 2.0 For Gmail Connector

The following example shows how to configure OAuth 2.0 for Gmail Connector.

### Configuring the OAuth Provider

To configure the OAuth provider for Gmail Connector, you can use Google Cloud Console. The following
steps show how to configure the OAuth provider:

> [!NOTE] If you haven’t enabled the Gmail API previously, you must create a new project and enable
> the Gmail API in the **Enabled APIs & Services** menu section.

1.  Add a new client (your connector app) to Google OAuth 2.0. To do so, navigate to **APIs &
    Services > Credentials > Create Credentials > OAuth Client ID**.

2.  Create a new web application by using the **Web Application** field.

3.  Enter a name, for example, `OAuthDemoApp`.

4.  Add the following URL to the **Authorized redirect URIs** field:
    `http://127.0.0.1:8080/callback`.

5.  Click **Create** and copy the new client ID and client secret for later use.

6.  Click **OK**.

### Configuring the Connector

Configure the connector with OAuth 2.0 using Anypoint Studio or XML.

#### Configuring the Connector Using Anypoint Studio

The following steps show how to configure the connector with OAuth 2.0 using Anypoint Studio.

1.  In Studio, create a Mule project.

2.  In the Mule Palette view, click **(X) Search in Exchange**.

3.  In **Add Dependencies to Project**, enter `gmail` in the search field.

4.  Click **Gmail Connector - Mule 4** in **Available modules**.

5.  Click **Add**.

6.  Click **Finish**.

7.  Configure the OAuth 2.0 authorization code. Create a new Gmail Connector connection and use the
    client ID and the client secret from the previous section as your **Consumer Key** and
    **Consumer Secret** respectively. You can leave the **Resource Owner ID** field empty.

    > [!NOTE] Gmail Connector comes with pre-filled values for the **Authorization URL**, **Access
    > Token URL**, and **Scopes** fields, so no further action is required. However, if you are
    > setting up a different connector that uses a third-party OAuth provider such as Okta or Ping,
    > you must use their respective **Authorization URL**, **Access Token URL**, and **Scopes**
    > fields.

    ![Gmail Connector Configuration window](/mulesoft/current/en-us/connectors/_images/intro-config-oauth2-gmail-config.png)

8.  Configure the OAuth 2.0 callback configuration. Drag a new **HTTP Listener** to the message flow
    and set **Protocol** to `HTTP (Default)`, **Host** to `localhost`, and **Port** to `8080`.

    ![HTTP Listener Configuration window](/mulesoft/current/en-us/connectors/_images/intro-config-oauth2-gmail-http-listener.png)

9.  Select this **HTTP Listener** in the Gmail Connector connection configuration.

10. Set **Callback path** to `callback` and **Authorize path** to `authorize`. You can leave the
    **External Callback Url** field empty.

    ![Gmail OAuth 2.0 Callback Configuration window](/mulesoft/current/en-us/connectors/_images/intro-config-oauth2-gmail-callback.png)

11. Run the app.

#### Configuring the Connector Using XML

The following steps show how to configure the connector with OAuth 2.0 using XML.

1.  Add the following dependency into your pom.xml.

    ```xml
    <dependency>
        <groupId>com.mulesoft.connectors</groupId>
        <artifactId>mule4-gmail-connector</artifactId>
        <version>1.0.5</version>
        <classifier>mule-plugin</classifier>
    </dependency>
    ```

2.  Configure the OAuth 2.0 authorization code. Create a new Gmail Connector connection and use the
    client ID and the client secret from the previous section as your **Consumer Key** and
    **Consumer Secret** respectively. You can leave the **Resource Owner ID** field empty.

    > [!NOTE] Gmail Connector comes with pre-filled values for the **Authorization URL**, **Access
    > Token URL**, and **Scopes** fields, so no further action is required. However, if you are
    > setting up a different connector that uses a third-party OAuth provider such as Okta or Ping,
    > you must use their respective **Authorization URL**, **Access Token URL**, and **Scopes**
    > fields.

    ![Gmail Connector Configuration window](/mulesoft/current/en-us/connectors/_images/intro-config-oauth2-gmail-config.png)

3.  Configure the OAuth 2.0 callback configuration. Create a new **HTTP Listener** configuration and
    set **Protocol** to `HTTP (Default)`, **Host** to `localhost`, and **Port** to `8080`.

    Here is the XML for this **HTTP Listener**:

    ```xml
    <http:listener-config name="HTTP_Listener_config" >
    		<http:listener-connection host="localhost" port="8080" />
    </http:listener-config>
    ```

4.  Select this **HTTP Listener** in the Gmail Connector connection configuration.

5.  Set **Callback path** to `callback` and **Authorize path** to `authorize`. You can leave the
    **External Callback Url** field empty.

    Here is the XML for the OAuth 2.0 callback configuration for Gmail Connector:

    ```xml
    <gmail:config name="Gmail_Connector_Config" >
        <gmail:oauth2c-connection >
            <gmail:oauth-authorization-code consumerKey="YOUR_CLIENT_ID" consumerSecret="YOUR_CLIENT_SECRET" />
            <gmail:oauth-callback-config listenerConfig="HTTP_Listener_config" callbackPath="callback" authorizePath="authorize"/>
        </gmail:oauth2c-connection>
    </gmail:config>
    ```

6.  Run the app.

### Performing the OAuth Dance

Perform the OAuth dance and authorize your app to access your Gmail account via the connector. The
following steps show how to perform the OAuth dance:

1.  In your browser, navigate to the path specified in the **Authorize Path** field to begin the
    OAuth dance. In this example, the path is `http://localhost:8080/authorize`. If everything is
    configured correctly, you will see a Google Authentication screen in which you select your user
    account and give permission to the app to access your account. Google shows a list of
    permissions that require approval, for example:

    ![Window that asks the user permission for Gmail to access their account](/mulesoft/current/en-us/connectors/_images/intro-config-oauth2-gmail-permissions.png)

    > [!NOTE] These permissions are dependent on the **Scopes** field configured in the Gmail
    > Connector connection configuration. You can accept the defaults, but if you want to limit the
    > access, you can remove the unwanted scopes. For example, remove the
    > `https://www.googleapis.com/auth/gmail.send` scope to disallow the connector from sending new
    > emails from your account, however, doing so limits connector functionality, such as the
    > ability to use the **Send Message** or **Send Draft** operations.

2.  Click **Allow**. The OAuth provider redirects you to `http://127.0.0.1:8080/callback`, which is
    the redirect URI that you configured in the OAuth provider and is open in the connector
    configuration. If the OAuth dance is successful, a `Successfully retrieved access token` message
    shows up on the browser, which means the connector is now fully authorized and ready to use your
    Gmail account.

    You do not need to authorize the app again unless you restart Anypoint Studio or the access
    token expires. Access tokens are automatically refreshed if the refresh token flow is enabled in
    your OAuth provider. Google supports this automatically, so your tokens are refreshed
    indefinitely.

    > [!NOTE] If you want your authorization to persist over restarts, you can configure an object
    > store in the Gmail Connector connection configuration.

### Testing the Connector

Now that your connector is functional and authorized, you can test a flow using the connector. The
following steps show how to retrieve some of your emails:

1.  Drag an **HTTP Listener** to the flow. Set **Path** to `/messages`.

2.  Drag the **List Messages** operation to the flow. The only required field is **User Id**, which
    contains the user’s email address that you want to access. For example, this is useful for
    corporate email servers with multiple users registered under one company account. Set **User
    Id** to `me` to retrieve emails from your main account directly. You can also set **Max
    Results** to a lower number if you want.

3.  Restart the project.

4.  Navigate to `http://localhost:8080/messages`. You should see a JSON formatted list of message
    IDs and thread IDs. You can retrieve the details of these messages or threads using the **Get
    Message** or the **Get Thread** operations.

#### XML for this Example

Paste this code into the Studio XML editor to quickly load the flow for this testing example into
your Mule app:

```xml
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:gmail="http://www.mulesoft.org/schema/mule/gmail" xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/gmail http://www.mulesoft.org/schema/mule/gmail/current/mule-gmail.xsd">
	<http:listener-config name="HTTP_Listener_config" >
		<http:listener-connection host="localhost" port="8080" />
	</http:listener-config>
	<gmail:config name="Gmail_Connector_Config">
		<gmail:oauth2c-connection >
			<gmail:oauth-authorization-code consumerKey="300484156412-lnrscnoef6d4tbla0itv4b7pej0dpr3j.apps.googleusercontent.com" consumerSecret="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" scopes="https://mail.google.com/ https://www.googleapis.com/auth/gmail.addons.current.action.compose https://www.googleapis.com/auth/gmail.addons.current.message.action https://www.googleapis.com/auth/gmail.addons.current.message.readonly https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/gmail.insert https://www.googleapis.com/auth/gmail.labels https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/gmail.readonly"/>
			<gmail:oauth-callback-config listenerConfig="HTTP_Listener_config" callbackPath="callback" authorizePath="authorize"/>
		</gmail:oauth2c-connection>
	</gmail:config>

	<flow name="oauthFlow" >
		<http:listener config-ref="HTTP_Listener_config" path="/messages"/>
		<gmail:gmailusersmessageslist config-ref="Gmail_Connector_Config" userIdUriParam="me" maxResultsQueryParam="5"/>
	</flow>
</mule>
```

## See Also

- [Configuring OAuth 2.0 for Connectors on CloudHub](https://docs.mulesoft.com/connectors/introduction/intro-config-oauth2-cloudhub)

- [Salesforce Help](https://help.salesforce.com)