OAuth Module Reference | MuleSoft Documentation
# OAuth Module Reference
OAuth Module v1.1
OAuth Module is an extension to hook OAuth2 to HTTP extension connectors.
## Configurations
### Config
Default configuration
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Name for this configuration. Connectors reference the configuration with this name.  
## Operations
  * Invalidate Oauth Context
  * Retrieve Access Token
  * Retrieve Custom Token Response Param
  * Retrieve Expires In
  * Retrieve Refresh Token
  * Retrieve State
### Invalidate Oauth Context
`<oauth:invalidate-oauth-context>`
Clears the OAuth context for a token manager and a resource owner ID.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
**Token Manager** |  Token Manager Config |  The token manager that holds the credentials to invalidate..  
**Resource Owner Id** |  The resource owner ID to invalidate. This attribute is allowed only for authorization code grant type.  
### Retrieve Access Token
`<oauth:retrieve-access-token>`
Returns the access token of the token manager for the parametrized resource owner ID.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
**Token Manager** |  Token Manager Config |  The token manager that holds the access token.  
**Resource Owner Id** |  The resource owner ID to invalidate. This attribute is allowed only for authorization code grant type.  
**Output Mime Type** |  The MIME type of the payload that this operation outputs.  
**Target Variable** |  Name of the variable that stores the operation’s output.  
**Target Value** |  Expression that evaluates the operation’s output. The expression outcome is stored in the **Target Variable**.  
#### Output
### Retrieve Custom Token Response Param
`<oauth:retrieve-custom-token-response-param>`
Returns the value of the parameter that is extracted during the OAuth dance from the token manager for the parametrized resource owner ID.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
**Token Manager** |  Token Manager Config |  The token manager that holds the access token.  
**Resource Owner Id** |  The resource owner ID to invalidate. This attribute is allowed for authorization code grant type.  
A key to look in the elements that are extracted after the OAuth dance.  
**Output Mime Type** |  The MIME type of the payload that this operation outputs.  
**Target Variable** |  Name of the variable that stores the operation’s output.  
**Target Value** |  Expression that evaluates the operation’s output. The expression outcome is stored in the **Target Variable**.  
#### Output
### Retrieve Expires In
`<oauth:retrieve-expires-in>`
Returns the expiration of the OAuth context for the parametrized resource owner ID.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
**Token Manager** |  Token Manager Config |  The token manager that holds the access token.  
**Resource Owner Id** |  The resource owner ID to invalidate. This attribute is allowed for authorization code grant type.  
**Output Mime Type** |  The MIME type of the payload that this operation outputs.  
**Target Variable** |  Name of the variable that stores the operation’s output.  
**Target Value** |  Expression that evaluates the operation’s output. The expression outcome is stored in the **Target Variable**.  
#### Output
### Retrieve Refresh Token
`<oauth:retrieve-refresh-token>`
Returns the refresh token of the OAuth context for the parametrized resource owner ID.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
**Token Manager** |  Token Manager Config |  The token manager that holds the refresh token.  
**Resource Owner Id** |  The resource owner ID to invalidate. This attribute is allowed for authorization code grant type.  
**Output Mime Type** |  The mime type of the payload that this operation outputs.  
**Target Variable** |  Name of the variable that stores the operation’s output.  
**Target Value** |  Expression that evaluates the operation’s output. The expression outcome is stored in the **Target Variable**.  
#### Output
### Retrieve State
`<oauth:retrieve-state>`
Returns the state of the OAuth context for the parametrized resource owner ID.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
**Token Manager** |  Token Manager Config |  The token manager that holds the access token.  
**Resource Owner Id** |  The resource owner ID to invalidate. This attribute is allowed for authorization code grant type.  
**Output Mime Type** |  The MIME type of the payload that this operation outputs.  
**Target Variable** |  Name of the variable that stores the operation’s output.  
**Target Value** |  Expression that evaluates the operation’s output. The expression outcome is stored in the **Target Variable**.  
#### Output
## Types
### Token Manager Config
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
**Object Store** |  Object Store |  An object store to store the OAuth context data.  
### Authorization Code Grant Type
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
**Local Callback Config** |  Listener configuration to use instead of `localCallbackUrl`. Note that if using this configuration you must also provide a `localCallbackConfigPath` separately.  
**Local Callback Config Path** |  Local path for the listener created according to `localCallbackConfig`, not required if you use `localCallbackUrl`.  
**Local Callback Url** |  URL that enables Mule runtime engine (Mule) to automatically create an endpoint in the configured URL that stores the authentication code unless there is an endpoint already registered to manually extract the authorization code.  
**External Callback Url** |  The OAuth authentication server uses the URL to provide the authentication code to the Mule server in order to retrieve the access token. Note that the URL must be the externally visible address of the callback, not the local address.  
State parameter for holding state between the authentication request and the callback done by the OAuth authorization server to the `redirectUrl`.  
**Local Authorization Url Resource Owner Id** |  Identifier to store the OAuth authentication attributes (accessToken, refreshToken, etc). This attribute is required only when applications access resources from more than one user in the OAuth authentication server.  
**Local Authorization Url** |  URL that enables Mule to automatically create an endpoint in the host server for the user to authenticate and grant access to the application for their account.  
**Authorization Url** |  The OAuth authentication server URL to authorize the app for a certain user.  
**Custom Parameters** |  Custom parameters to send to the authorization request URL or the OAuth authorization sever.  
**Resource Owner Id** |  Identifier to store the OAuth authentication attributes (accessToken, refreshToken, etc). This attribute is required only when applications access resources from more than one user in the OAuth authentication server.  
**Encode Client Credentials In Body** |  If `true`, the client ID and client secret are sent in the request body. Otherwise, the client ID and client secret are sent as basic authentication.  
Application identifier defined in the OAuth authentication server.  
**Client Secret** |  Application secret defined in the OAuth authentication server.  
Scope required by the application to execute. Scopes define permissions over resources.  
**Token Manager** |  Token Manager Config |  The token manager configuration to use for the grant type.  
The OAuth authentication server URL to get access to the token. Mule calls this URL to get the access token, after receiving the authentication code from the OAuth server through the `redirectUrl`.  
**Response Access Token** |  Expression to extract the access token parameter from the response of the call to `tokenUrl`. |  `#[payload.access_token]`  
**Response Refresh Token** |  Response refresh token. |  `#[payload.refresh_token]`  
**Response Expires In** |  Expression to extract the expires in parameter from the response of the call to `tokenUrl`. |  `#[payload.expires_in]`  
**Custom Parameter Extractors** |  Array of Parameter Extractor  
**Refresh Token When** |  Enables expressions to evaluate against the HTTP response of the API callback to determine if the request failed because it was done using an expired token. If the evaluation returns `true` (access token expired), Mule automatically triggers a refresh token flow and retries the API callback using a new access token. Default value evaluates if the response status code is `401` or `403`. |  `#[attributes.statusCode == 401 or attributes.statusCode == 403]`  
**Tls Context** |  A TLS configuration to receive incoming HTTP requests and do HTTP requests during the OAuth dance.  
### Parameter Extractor
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
**Param Name** |  Parameter extractor name.  
Value for this type.  
Configures TLS to provide secure communications for the Mule app.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
**Enabled Protocols** |  Comma-separated list of protocols enabled for this context.  
**Enabled Cipher Suites** |  Comma-separated list of cipher suites enabled for this context.  
**Trust Store** |  Configures the TLS truststore.  
Configures the TLS keystore.  
**Revocation Check** | 
  * Standard Revocation Check
  * Custom OCSP Responder
|  Revocation check configuration.  
### Truststore
Configures the truststore for TLS.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Path to the truststore. Mule resolves the path relative to the current classpath and file system.  
Password used to protect the truststore.  
Type of store.  
Encryption algorithm that the truststore uses.  
If `true`, Mule stops performing certificate validations. Setting this attribute to `true` make connections vulnerable to attacks.  
### Keystore
Configures the keystore for the TLS protocol. The keystore you generate contains a private key and a public certificate.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Path to the keystore. Mule resolves the path relative to the current classpath and file system.  
Type of store.  
Alias of the key to use when the keystore contains multiple private keys. By default, Mule uses the first key in the file.  
**Key Password** |  Password used to protect the private key.  
Password used to protect the keystore.  
Encryption algorithm that the keystore uses.  
### Standard Revocation Check
Configures standard revocation checks for TLS certificates.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
**Only End Entities** |  Which elements to verify in the certificate chain:
  * `true` Verifies only the last element in the certificate chain.
  * `false` Verifies all the elements in the certificate chain.

  
**Prefer Crls** |  How to check certificate validity:
  * `true`+ Checks the Certification Revocation List (CRL) for certificate validity.

Checks the Online Certificate Status Protocol (OCSP) for certificate validity.  
**No Fallback** |  Whether to use the secondary method to check certificate validity: Uses the method not specified in the **Prefer Crls** field to check the certificate validity. Does not use the method specified in the **Prefer Crls** field to check certificate validity.  
What to do if the revocation server can’t be reached or is busy: Avoids verification failure. Enables the verification to fail.  
### Custom OCSP Responder
Configures a custom OCSP responder for certification revocation checks.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
URL of the OCSP responder.  
**Cert Alias** |  Alias of the signing certificate for the OCSP response. If specified, the alias must be configured in the truststore.  
### CRL File
Specifies the location of the certification revocation list (CRL) file.
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Path to the CRL file.  
### Client Credentials Grant Type
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
**Encode Client Credentials In Body** |  If true, the client ID and client secret are sent in the request body. Otherwise, the client ID and client secret are sent as basic authentication.  
Application identifier defined in the OAuth authentication server.  
**Client Secret** |  Application secret defined in the OAuth authentication server.  
Scope required by the application to execute. Scopes define permissions over resources.  
**Token Manager** |  Token Manager Config |  The token manager configuration to use for the grant type.  
The OAuth authentication server URL to get access to the token. Mule calls this URL to get the access token, after receiving the authentication code from the OAuth server through the `redirectUrl`.  
**Response Access Token** |  Expression to extract the access token parameter from the response of the call to `tokenUrl`. |  `#[payload.access_token]`  
**Response Refresh Token** |  Response refresh token. |  `#[payload.refresh_token]`  
**Response Expires In** |  Expression to extract the expires in parameter from the response of the call to `tokenUrl`. |  `#[payload.expires_in]`  
**Custom Parameter Extractors** |  Array of Parameter Extractor |  Custom parameter extractors configuration.  
**Refresh Token When** |  Enables expressions to evaluate against the HTTP response of the API callback to determine if the request failed because it was done using an expired token. If the evaluation returns `true` (access token expired), Mule automatically triggers a refresh token flow and retries the API callback using a new access token. Default value evaluates if the response status code is `401` or `403`. |  `#[attributes.statusCode == 401 or attributes.statusCode == 403]`  
**TLS Context** |  A TLS configuration to receive incoming HTTP requests and do HTTP requests during the OAuth dance.  
## See Also
  * MuleSoft Help Center