---
schema_version: "1"
id: 2a5b6e0ae8f68b4f01e844927dd8e7fde22c7230386ea2b948edde7705c84e71
title: Configuring an OAuth-Enabled Connector or Module
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-sdk/latest/oauth-configuring.md
canonical_url: https://docs.mulesoft.com/mule-sdk/latest/oauth-configuring
source_site: docs.mulesoft.com
content_type: documentation
content_hash: a83b3c8e56941a50751163324105c6ed7db93c028733069d907a6b6c4b3ef52a
description: MuleSoft Documentation Site
release: "1.13"
latest: true
---
---
product: Mule SDK
version: 1.13
is-latest-version: true
keywords: mule, sdk, security, oauth
---

# Configuring an OAuth-Enabled Connector or Module

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

An important aspect of OAuth-enabled connectors or modules is how to use them. As much as the SDK
does to hide the complexities of the OAuth protocol, things like the OAuth dance are unavoidable.
The SDK’s approach to this problem is to standardize the experience of all OAuth modules to keep
simplifying the user experience.

This section discusses the steps a user must take to use the module.

## Synthetic Parameters

In addition to everything explicitly defined in the Connection Provider, the SDK automatically adds
some extra parameters and injects the proper behavior for them.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter Name</th><th>Required</th><th>Expressions</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><p><code>resourceOwnerId</code></p></td><td><p>NO</p></td><td><p>SUPPORTED</p></td><td><p>N/A</p></td><td><p>To support multi-tenancy, users can specify the ID of the tenant that owns the associated access and refresh tokens. When performing the authorization dance, this value will provide the ID of the obtained token. When a component needs to obtain a new connection, it acts as a default owner ID to use.</p></td></tr><tr><td><p><code>consumerKey</code></p></td><td><p>YES</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>The OAuth <code>consumerKey</code> as registered with the service provider.</p></td></tr><tr><td><p><code>consumerSecret</code></p></td><td><p>YES</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>The OAuth <code>consumerSecret</code> as registered with the service provider.</p></td></tr><tr><td><p><code>authorizationUrl</code></p></td><td><p>NO</p></td><td><p>NOT_SUPPORTED</p></td><td><p>Value provided in the <code>`@AuthorizationCode</code> annotation.</p></td><td><p>The service provider’s authorization URL.</p></td></tr><tr><td><p><code>accessTokenUrl</code></p></td><td><p>NO</p></td><td><p>NOT_SUPPORTED</p></td><td><p>Value provided in the <code>@AuthorizationCode</code> annotation.</p></td><td><p>The service provider’s access token URL.</p></td></tr><tr><td><p><code>state</code></p></td><td><p>NO</p></td><td><p>REQUIRED</p></td><td><p>N/A</p></td><td><p>A String value that you send when the OAuth dance is initiated and that is returned back by the service provider with the token callback. It is used to correlate dance initiations with token callbacks. The most common use case for this attribute is multi-tenancy.</p></td></tr><tr><td><p><code>scope</code></p></td><td><p>NO</p></td><td><p>NOT_SUPPORTED</p></td><td><p>Value provided in the <code>@AuthorizationCode</code> annotation.</p></td><td><p>The OAuth scopes to be requested during the dance. If not provided, it will default to those in the annotation.</p></td></tr><tr><td><p><code>listenerConfig</code></p></td><td><p>YES</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>A reference to an <code>&lt;http:listener-config /&gt;</code> to be used in order to create the listener that will catch the access token callback endpoint.</p></td></tr><tr><td><p><code>callbackPath</code></p></td><td><p>YES</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>The path of the access token callback endpoint.</p></td></tr><tr><td><p><code>authorizePath</code></p></td><td><p>YES</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>The path of the local HTTP endpoint that triggers the OAuth dance.</p></td></tr><tr><td><p><code>externalCallbackUrl</code></p></td><td><p>NO</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>If the callback endpoint is behind a proxy or should be accessed through a non-direct URL, use this parameter to tell the OAuth provider the URL it should use to access the callback.</p></td></tr><tr><td><p><code>resourceOwnerId</code></p></td><td><p>YES</p></td><td><p>SUPPORTED</p></td><td><p>N/A</p></td><td><p>The <code>resourceOwnerId</code> that each component should use if it does not reference otherwise.</p></td></tr><tr><td><p><code>objectStore</code></p></td><td><p>NO</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>A reference to the Object Store to user for storing each resource owner ID’s data. If not specified, the runtime will automatically provision the default one.</p></td></tr><tr><td><p><code>before</code></p></td><td><p>NO</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>The name of a flow to be executed right before starting the OAuth dance (see <a href="#before_flow">Before Flow</a>).</p></td></tr><tr><td><p><code>after</code></p></td><td><p>NO</p></td><td><p>NOT_SUPPORTED</p></td><td><p>N/A</p></td><td><p>The name of a flow to be executed right after an <code>accessToken</code> has been received (see <a href="#after_flow">After Flow</a>)</p></td></tr></tbody></table>

## About the Use of Expressions

The table above identifies many of the synthetic parameters that accept expressions. Using
expressions there has the same effect as using expressions in a regular parameter: It will turn the
configuration into a dynamic one.

## OAuth Connection DSL

This is what the generated DSL looks like:

```xml
<sfdc:config name="salesforce">
    <sfdc:oauth-connection display="PAGE" immediate="FALSE" prompt="CONSENT">
        <sfdc:oauth-authorization-code consumerKey="${sfdc.consumerkey}" consumerSecret="${sfdc.consumersecret}" authorizationUrl="http://..."
accessTokenUrl="http://..."/
localAuthorizationUrl="http://localhost:8080/.." scope="this that and those" resourceOwnerId="#[ownerId]"
before="myBeforeFlow" after="myAfterFlow" />
        <sfdc:oauth-callback-config listenerConfig="myHttpListener" callbackPath="/callback" authorizePath="/authorize" />
        <sfdc:oauth-store-config objectStore="oauthObjectStore" />
</sfdc:config>
```

- Regular and OAuth parameters are all shown at the connection provider level, just like in any
  other provider.

- The parameters related to the Authorization Code Grant type (`consumerKey`, `consumerSecret`,
  `authorizationUrl`, `accessTokenUrl`, `localAuthorizationHost`, `localAuthorizationPort`,
  `localAuthorizationPath`, `before`, `after`, `scope`, `defaultResourceOwnerId`) will be placed on
  a child element called `<oauth-authorization-code>`.

- The parameters related to the callback will be placed in a child element called
  `<oauth-callback-config>`.

- The parameters related to object store will be placed in a child element called
  `<oauth-store-config>`.

## Custom Logic Before and After the Dance

End users often want to execute some random logic just before initiating the OAuth dance or right
after it has been completed. Use cases include notifying an external system that a given owner ID
has been successfully on-boarded, keeping activity logs, and so on.

The authorization process is triggered by hitting an automatically created endpoint, so the
`<oauth-authorization-code>` child element has the `before` and `after` parameters.

These optional parameters specify the name of a `<flow>` to be invoked before or after the OAuth
dance.

### Before flow

The before flow will be executed just before the OAuth dance is started. The payload of the event
sent to that flow will be an instance of `AuthorizationCodeRequest`, which is an immutable POJO that
looks like this:

```java
public interface AuthCodeRequest {

  /**
   * @return The id of the user being authenticated
   */
  String getResourceOwnerId();

  /**
   * @return The scopes that were requested
   */
  Optional<String> getScopes();

  /**
   * @return The OAuth state that was sent
   */
  Optional<String> getState();

  /**
   * @return The external callback url that the user configured or {@link Optional#empty()} if none was provided
   */
  Optional<String> getExternalCallbackUrl();
}
```

In this flow, the user can perform any custom logic as needed. In particular, the user can set flow
variables (see [After Flow](#after_flow)).

### After Flow

The after flow is executed right after the access token has been received and stored. This flow is
executed with an event that is equivalent to what came out of the before flow (or a blank event if
no before flow was defined), except for the payload, which is replaced by the same
`AuthorizationCodeState` object that is injected in the `ConnectionProvider`. However, any variables
previously set are still there (or will be empty if no before flow was defined).

## Configuring a Custom ObjectStore

The obtained access tokens are stored in an `ObjectStore`. By default, the SDK will store them in
the apps’s default store, but users can define their own custom one, for example:

```xml
<os:object-store name="tokenStore" (1)
   entryTtl="1"
   entryTtlUnit="HOURS"
   maxEntries="100"
   persistent="true"
   expirationInterval="30"
   expirationIntervalUnit="MINUTES" />

<sfdc:config name="salesforce">
    <sfdc:oauth-connection display="PAGE" immediate="FALSE" prompt="CONSENT">
        <sfdc:oauth-authorization-code consumerKey="${sfdc.consumerkey}" consumerSecret="${sfdc.consumersecret}"
        authorizationUrl="http://..." accessTokenUrl="http://..."/
        localAuthorizationUrl="http://localhost:8080/.." />
        <sfdc:oauth-callback-config listenerConfig="myHttpListener" callbackPath="/callback" authorizePath="/authorize" />
        <sfdc:oauth-store-config objectStore="tokenStore" /> (2)
</sfdc:config>
```

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Define your custom store.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Reference it on your module’s config.</td></tr></tbody></table>

## Next Step

[Performing the OAuth Dance with an OAuth-Enabled Connector or Module](https://docs.mulesoft.com/mule-sdk/latest/oauth-dance)