Configure HTTP Request Authentication | MuleSoft Documentation
# Configure HTTP Request Authentication
The Anypoint Connector for HTTP (HTTP Connector) **Request** operation supports connecting a Mule client app to a service that requires any of the following types of authentication:
  * Basic Authentication
  * Digest Authentication
  * NTLM Authentication
  * OAuth2 Authorization Code Grant Type Authentication
  * OAuth2 Client Credentials Grant Type Authentication


If the target HTTP service of your request requires that you authenticate, provide the necessary credentials in the HTTP **Request** operation global configuration element. Mule runtime engine (Mule) uses the credentials you configured in the authorization header of the HTTP request.
You can also configure Transport Layer Security (TLS) to encrypt the OAuth credentials.
To protect your API or Mule app from receiving requests from an unauthorized source, use an API Manager policy. Refer to the OAuth 2.0 Access Token Enforcement Using External Provider documentation.
In Anypoint Studio HTTP **Request** operation global configuration, do not use the **Expression** option for the **Authentication** field.   
---  
## HTTP XML Authentication Setup
XML values for HTTP Connector authentication:
Authentication Type | XML Value  
---|---  
Basic Authentication |  ```
<http:authentication >
 <http:basic-authentication
 username="UN" password="PW"/>
</http:authentication>
```
  
NTLM Authentication |  ```
<http:authentication >
 <http:ntlm-authentication
 domain="DM" workstation="WS"
 username="UN" password="PW" />
</http:authentication>
```
  
Digest Authentication |  ```
<http:authentication >
 <http:digest-authentication
 username="UN" password="PW"/>
</http:authentication>
```
  
In addition, adding an OAuth component’s operation to the canvas in Studio automatically adds the following dependency to the project’s `pom.xml` file:
```
<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-oauth-module</artifactId>
  <version>1.1.8</version>
  <classifier>mule-plugin</classifier>
</dependency>
```

## Configure Basic Authentication
The basic authentication method enables an HTTP user agent to provide a username and password when making an HTTP request.
The following Mule app example illustrates how to configure basic authentication for the HTTP **Request** operation by sending a request to the GitHub API for user information. In this example, the GitHub API accepts requests for user information on port 443 to `https://api.github.com/user`. To comply with basic authentication requirements, the Mule app provides the GitHub user name and password. You configure the HTTP **Request** operation to provide these credentials.
Note that this example requires that you have a GitHub account.
  1. In Studio > **Mule Palette** , select **HTTP > Listener**.
  2. Drag **Listener** to the Studio canvas.
  3. Set **Path** to `/path`.
  4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app.
  5. In the **HTTP Listener config** window, set the following fields:
     * **Protocol** : `HTTP (Default)`
     * **Host** : `All Interfaces [0.0.0.0] (default)`
     * **Port** : `8081`
  6. Click **OK**.
  7. In the **Advanced** tab, set **Allowed methods** to `GET`.
  8. Drag an HTTP **Request** operation next to the HTTP **Listener** source.
  9. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the operation in the app.
  10. In the **HTTP Request configuration** window, set the following fields:
     * **Name** : `HTTP_Request_configuration`
     * **Protocol** : `HTTPS`
     * **Host** : `api.github.com`
  11. Set **Authentication** to **Basic authentication**.
  12. Set **Username** to your GitHub username account.
  13. Set **Password** to either your GitHub password account or a personal access token.
  14. Set **Preemptive** to **True (Default)**.
  15. In the HTTP **Request** configuration window, set **Method** to **GET (Default)**.
  16. Set **Path** to `/user`.
  17. In the **Mule Palette** , select **Core > Transform message**.
  18. Drag the **Transform message** component to the right of the HTTP **Request** operation.
  19. In the **Output** properties window, change the output to the following DataWeave code:
```
%dw 2.0
output application/json
---
payload
```

  20. Save your Mule app.
  21. Click **Run > Run as > Mule Application**.
  22. To call the API, type `http://localhost:8081/` in your internet browser.
The GitHub API returns your user information, for example:
```
{
  "login":"kahn",
  "id":16xxx343,
  "avatar_url":"https://avatars.githubusercontent.com/u/16xxx343?v=3"`
  ...
}
```



If the browser returns `HTTP GET on resource 'https://api.github.com:443/user' failed: unauthorized (401)`, use a personal access token instead of specifying your GitHub password. If you are generating a new token, you need only the **user** > **read:user** scope.
### XML for Configuring Basic Authentication Example
Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app:
```
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core" 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/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
	<http:listener-config name="HTTP_Listener_config" >
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<http:request-config name="HTTP_Request_configuration" >
		<http:request-connection protocol="HTTPS" host="api.github.com" port="443" >
			<http:authentication >
				<http:basic-authentication username="GitHubusername" password="GitHubpassword" />
			</http:authentication>
		</http:request-connection>
	</http:request-config>
	<flow name="Authenticaterequests" >
		<http:listener config-ref="HTTP_Listener_config" path="/path">
		</http:listener>
		<http:request method="GET" config-ref="HTTP_Request_configuration" path="/user"/>
		<ee:transform >
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
	</flow>
</mule>
```

## Configure Digest Authentication
The digest authentication method enables a web server to verify user credentials via the user’s web browser.
The following example shows how to configure the digest authentication for the HTTP **Request** operation by sending a `GET` request to the URL `http://www.example.com/test`, adding an authorization header with the provided username and password.
  1. In Studio, select the HTTP **Request** operation from your flow.
  2. Set **Method** to `GET` and **Path** to `test`.
  3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the operation in the app.
  4. In the **HTTP Request configuration** window, set the following fields:
     * **Name** : `HTTP_Request_configuration`
     * **Protocol** : `HTTPS`
     * **Host** : `example.com`
     * **Port** : `8081`
  5. Set **Authentication** to **Digest authentication**.
  6. Set **Username** to `Username`.
  7. Set **Password** to `Password`.


### XML for Configuring Digest Authentication Example
The following code shows how to configure the digest authentication in XML:
```
...
<http:request-config name="HTTP_Request_configuration"
   doc:name="HTTP Request configuration" >
  <http:request-connection host="example.com" port="8081" >
    <http:authentication >
      <http:digest-authentication
       username="Username"
       password="Password" />
    </http:authentication>
  </http:request-connection>
</http:request-config>
<flow name="digest_flow">
  ...
  <http:request config-ref="HTTP_Request_configuration"
  path="test"
  method="GET" />
</flow>
```
### XML for Configuring Digest Authentication Example
The following code shows how to configure the digest authentication in XML:
```
...
<http:request-config name="HTTP_Request_configuration"
   doc:name="HTTP Request configuration" >
  <http:request-connection host="example.com" port="8081" >
    <http:authentication >
      <http:digest-authentication
       username="Username"
       password="Password" />
    </http:authentication>
  </http:request-connection>
</http:request-config>
<flow name="digest_flow">
  ...
  <http:request config-ref="HTTP_Request_configuration"
  path="test"
  method="GET" />
</flow>
```

## Configure NTLM Authentication
NT LAN Manager (NTLM) authentication replaces the authentication protocol in Microsoft LAN Manager (LANMAN), an older Microsoft product.
The following example shows how to configure the NTLM authentication for the HTTP **Request** operation by sending a `GET` request to the URL `http://www.example.com/test`, adding an authorization header with the provided username and password.
  1. In Studio, select the HTTP **Request** operation from your flow.
  2. Set **Method** to `GET` and **Path** to `test`.
  3. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the operation in the app.
  4. In the **HTTP Request configuration** window, set the following fields:
     * **Name** : `HTTP_Request_configuration`
     * **Protocol** : `HTTPS`
     * **Host** : `example.com`
     * **Port** : `8081`
  5. Set **Authentication** to **Ntlm authentication**.
  6. Set **Username** to `Username`.
  7. Set **Password** to `Password`.
  8. Optionally, set **Domain** and **Workstation**.


### XML for Configuring NTLM Authentication
The following code shows how to configure the NTLM authentication in XML:
```
<http:request-config name="HTTP_Request_configuration"
   doc:name="HTTP Request Configuration" >
 <http:request-connection
   host="example.com"
   port="8081" >
   <http:authentication >
    <http:ntlm-authentication username="Username" password="Password" />
   </http:authentication>
 </http:request-connection>
</http:request-config>
<flow name="digest_flow">
  ...
  <http:request method="GET" doc:name="Request"
  config-ref="HTTP_Request_configuration"
  path="test"
   />
</flow>
```

## Configure OAuth2 Authorization Code Grant Type Authentication
The OAuth2 authorization code configures the OAuth 2.0 authorization code grant type. The OAuth authentication server holds the resources protected by OAuth. For example, API calls to the GitHub API can be authenticated through GitHub server using OAuth.
Note that HTTP Connector supports only OAuth 2.0.
The following example shows how to configure the OAuth2 Authorization code grant type authentication for the HTTP **Request** operation by creating a Mule app to access a protected resource, GitHub user data, on the GitHub OAuth authentication server. The example covers how to:
  * Set up authorization
  * Create a Mule app
  * Run the Mule app


This example requires that you have a GitHub account.
Before you create the Mule app, review the following diagrams that show the procedure of getting OAuth access token and returning token for data:
  1. Submit an HTTP request for GitHub access to the client app.
  2. The client app redirects the request to the GitHub authentication server.
  3. GitHub requests login credentials.
  4. Log in an authorize the client app.
  5. The GitHub authentication server returns an access token.
  6. The client app listens for the next request.


  1. Request the secured user data using the access token.
  2. Redirect user data request.
  3. The client app gets the user data from the GitHub authentication server.
  4. The client app listens for the next request.


### Set Up Authorization
To set up the authorization, follow these steps:
  1. Register the client application on the authentication server. The authentication server assigns a client ID and client secret to the Mule app. The app uses these credentials to identify itself to the authentication server. During the registration, provide the URL to the Mule app home page and the application callback URL.
  2. Log in to GitHub.
  3. Register the application in your GitHub personal settings.
  4. On the **Register a new OAuth application** page, complete the following fields:
     * **Application name** : `oauth-grant-code`
     * **Homepage URL** : `http://localhost:8082`
     * **Authorization callback URL** : `http://localhost:8082/callback`
  5. Click **Register application**.
GitHub creates a page for the registered application on `https://github.com/settings/applications/<app number>` that includes the GitHub-assigned client ID and client secret.


### Create the Mule App
Create a Mule app that uses the GitHub assigned client ID and client secret to access the user data on the GitHub OAuth2 authentication server.
The Mule app consists of an HTTP **Listener** source, an HTTP **Request** operation, and a DataWeave **Transform message** component to transform plain text to JSON. In the HTTP **Request** operation, you configure access to the authentication server. To create the Mule app:
  1. In Studio > **Mule Palette** , select **HTTP > Listener**.
  2. Drag **Listener** to the Studio canvas.
  3. Set **Path** to `/`.
  4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of the source in the app.
  5. In the **HTTP Listener config** window, set the following fields:
     * **Protocol** : `HTTP (Default)`
     * **Host** : `All Interfaces [0.0.0.0] (default)`
     * **Port** : `8081`
  6. Drag an **HTTP > Request** operation to the right of the **Listener** source.
  7. Expand the **Package Explorer** window.
  8. Expand your Mule app project.
  9. Open the `pom.xml` file.
  10. At the end of the `<dependencies>` section and before the `</dependencies>` statement, add the following statement to enable OAuth options for the **Request** operation:
```
<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-oauth-module</artifactId>
  <version>1.1.8</version>
  <classifier>mule-plugin</classifier>
</dependency>
```

  11. Select the HTTP **Request** operation from your flow, and in the properties editor for **Connector Configuration** , click the plus sign (**+**).
  12. Set **Authentication** to **Authorization code grant type**.
  13. Set the following required fields:
     * **External callback url** : `http://myapp.mycompany.com:8082/callback` The OAuth authentication server uses this URL to provide the authentication code to the Mule server so that the Mule server can retrieve the access token. This must be the externally visible address of the callback, not the local one.
     * **Local authorization url** : `https://localhost:8082/login` This URL enables you to authenticate and grant access to the app for your account.
     * **Authorization url** : `https://github.com/login/oauth/authorize` This URL redirects the user request from the Mule app to the authorization URL of the GitHub authentication server.
     * **Client id** The client ID that GitHub provided when you registered the app.
     * **Client secret** The client secret that GitHub provided when you registered the app.
     * **Token Manager** To access authorization information for client credentials and authorization codes, configure a token manager. If you don’t configure a token manager, the OAuth Module re-initializes every time a new request is made.
     * **Token url** : `https://github.com/login/oauth/access_token` The Mule client app sends the token to the token URL.
Additionally, you can set these optional fields:
     * **Local callback url** : `http://localhost:8082/callback` This URL matches the value you configured for **External callback URL** when registering the app in GitHub. This is the configuration of the server that Mule creates to receive the requests that a remote host sends to the **External callback URL**. External and internal callback URLs are the same, one URL enables you to create a server in the runtime (internal) and the other URL enables the internet (external) to see the server.
     * **Response Access Token** : `#[payload.access_token]` This DataWeave expression extracts an access token.
     * **Response Refresh Token** : `[payload.access_token]` If the provider you use sends a refresh token, use a DataWeave expression for the refresh token as the following `[payload.refresh_token]`. In this example, however, GitHub doesn’t actually use a refresh token.
  14. Click **OK**.
  15. Save your Mule app.
### Run the Mule Client App
To run the Mule client app and get the GitHub user data, perform the following steps before the access token expires:
  1. In the **Package Explorer** window, right-click the project name and choose **Run as > Mule Application**.
The console shows the Mule app deploying.
  2. In a browser, enter the local authorization URL `http://localhost:8082/login` to initiate the OAuth2 dance.
GitHub prompts you to log in.
  3. Log in using your GitHub username and password.
GitHub prompts you to authorize the application you registered to run.
  4. Click **Authorize application**.
`Successfully retrieved access token` appears as body text in the browser you used to initiate the OAuth2 dance.
  5. For the token to get data, enter the following URL in a browser: `http://localhost:8081/github`
The GitHub API returns your user information:
```
{
  "login":"kahn",
  "id":16xxx343,"avatar_url":"https://avatars.githubusercontent.com/u/16xxx343?v=3"`
  ...
}
```



### XML for Configuring OAuth2 Authorization Code Example
The following code shows how to configure OAuth2 Authorization Code in XML:
```
<http:listener-config name="HTTP_Listener_Configuration"
           host="0.0.0.0" port="8081" basePath="/github"/>
<http:request-config name="HTTP_Request_Configuration"
           protocol="HTTPS" host="api.github.com" port="443">
  <http:authentication>
    <oauth:authorization-code-grant-type
    externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
    localAuthorizationUrl="http://localhost:8082/login"
    authorizationUrl="https://github.com/login/oauth/authorize"
    clientId="CLIENT_ID"
    clientSecret="CLIENT_SECRET"
    tokenUrl="https://github.com/login/oauth/access_token" />
  </http:authentication>
</http:request-config>
```

### Configure OAuth2 Authorization Scopes
Scopes in OAuth are like security roles. Configure scopes for the OAuth2 Authorization code grant type in the **Scopes** field by defining a comma-separated list of OAuth scopes available in the authentication server.
  1. In Studio, select the HTTP **Request** operation from your flow.
  2. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element.
  3. Set **Authentication** to **Authorization code grant type**.
  4. Set **Scopes** to `access_user_details, read_user_files`.
  5. Click **OK**.


In the **Configuration XML** editor, the `scopes` configuration looks like this:
```
<http:authentication>
  <oauth:authorization-code-grant-type
    localCallbackUrl="http://localhost:8082/redirectUrl"
    externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
    localAuthorizationUrl="https://localhost:8082/authorization"
    authorizationUrl="https://www.box.com/api/oauth2/authorize"
    clientId="your_client_id"
    clientSecret="your_client_secret"
    tokenUrl="https://www.box.com/api/oauth2/token"
    tlsContextFactory="TLS_Context"
    scopes="access_user_details, read_user_files" />
</http:authentication>
```

### Configure OAuth2 Authorization Custom Parameters
There are OAuth implementations that require or allow extra query parameters to be sent when calling the Authentication URL of the OAS. Configure these parameters for the OAuth2 authorization code grant type in the **Custom parameters** field:
  1. In Studio, select the HTTP **Request** operation from your flow.
  2. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element.
  3. Set **Authentication** to **Authorization code grant type**.
  4. Set the following fields:
     * **External callback url** : `http://myapp.mycompany.com:8082/callback`
     * **Local authorization url** : `http://localhost:8082/login`
     * **Authorization url** : `https://github.com/login/oauth/authorize`
     * **Client id** : Client ID from your GitHub account
     * **Client secret** : Client secret from your GitHub account
     * **Token url** : `https://github.com/login/oauth/access_token`
  5. Set **Custom parameters** to **Edit inline**.
  6. Click the plus sign (**+**) to add a new custom parameter.
  7. Set **Key** to `box_device_id` and **Value** to `123142`.
  8. Repeat Step 6.
  9. Set **Key** to `box_device_name` and **Value** to `my-phone`.
  10. Click **OK**.


In the **Configuration XML** editor, the `oauth:custom-parameter` configuration looks like this:
```
<http:request-config name="HTTP_Request_Configuration"
    host="api.box.com" port="443" basePath="/2.0">
  <http:authentication>
    <oauth:authorization-code-grant-type
    externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
    localAuthorizationUrl="http://localhost:8082/login"
    authorizationUrl="https://github.com/login/oauth/authorize"
    clientId="CLIENT_ID"
    clientSecret="CLIENT_SECRET"
    tokenUrl="https://github.com/login/oauth/access_token" />
    <oauth:custom-parameters>
      <oauth:custom-parameter
        key="box_device_id" value="123142"/>
      <oauth:custom-parameter
        key="box_device_name" value="my-phone"/>
    </oauth:custom-parameters>
  </http:authentication>
</http:request-config>
```

### Configure OAuth2 Authorization Redirect URI
The OAuth 2.0 specification describes checking the redirect URI from the destination site of the redirect. The OAuth authentication server uses the URL to provide the authentication code to the Mule server for retrieving the access token. If you provide this URL, Mule creates an endpoint at the URL for storing the authentication code unless there’s already an endpoint registered to manually extract the authorization code.
To override the redirect URI (external `redirect_uri`), configure the external redirect URI in the **External callback url** field, which is useful for actions such as deploying applications to CloudHub. When you configure authentication, you can optionally configure the **Local callback url** field as well.
For CloudHub, Mule has to create an endpoint with a format similar to the following:
`https://<app>.cloudhub.io/<redirect Uri>`
To instruct Mule to create the endpoint for CloudHub in the correct format, include the **External callback url** field in your OAuth2 authorization code grant type configuration.
### Configure OAuth2 Authorization Extract Parameters
After you obtain an authorization code from the authentication server, OAuth requests an access token from the token URL of the server.
The format of the response to the token URL is not defined in the OAuth specification. Each implementation can return different response formats. By default, Mule expects the response to be in JSON format. When this is the case, HTTP requests know how to extract the required information, as long as the following fields are specified:
  * **Response access token** The JSON field is `access_token`.
  * **Response refresh token** The JSON field is `refresh_token`.
  * **Response expires in** The JSON field is `expires_in`.


When the response is in JSON format, the parameters are automatically extracted and you can use DataWeave expressions to reference these values in the response to the token URL.
When the response is not in JSON format, then you must first configure the connector so that it knows how to extract these values.
In the following example, HTTP Connector expects the response to have a `Content-Type` of `application/x-www-form-urlencoded`, so the body of the response is transformed into a map in the payload. You extract the values from the map through DataWeave expressions, such as `#[payload.access_token]` (the default value for the **Response access token** and **Response refresh token**).
  1. In Studio, select the HTTP **Request** operation from your flow and in the properties editor for **Connector Configuration** , click the plus sign (**+**).
  2. Set **Authentication** to **Authorization code grant type**.
  3. Verify the default options for the following fields:
     * **Response access token** : `#[payload.access_token]`
     * **Response refresh token** : `#[payload.refresh_token]`
     * **Response expires in** : `#[payload.expires_in]`


In the **Configuration XML** editor, the `responseAccessToken`, `responseRefreshToken` and `responseExpiresIn` configurations look like this:
```
<http:request-config name="HTTP_Request_Configuration"
          host="api.box.com" port="443" basePath="/2.0">
   <http:authentication>
     <oauth:authorization-code-grant-type
       localCallbackUrl="http://localhost:8082/redirectUrl"
       externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
       localAuthorizationUrl="http://localhost:8082/authorization"
       authorizationUrl="http://www.box.com/api/oauth2/authorize"
       clientId="your_client_id"
       clientSecret="your_client_secret"
       tokenUrl="http://www.box.com/api/oauth2/token"
       responseAccessToken="#[payload.access_token]"
       responseRefreshToken="#[payload.refresh_token]"
       responseExpiresIn="#[payload.expires_in]" />
   </http:authentication>
</http:request-config>
```
In the **Configuration XML** editor, the `responseAccessToken`, `responseRefreshToken` and `responseExpiresIn` configurations look like this:
```
<http:request-config name="HTTP_Request_Configuration"
          host="api.box.com" port="443" basePath="/2.0">
   <http:authentication>
     <oauth:authorization-code-grant-type
       localCallbackUrl="http://localhost:8082/redirectUrl"
       externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
       localAuthorizationUrl="http://localhost:8082/authorization"
       authorizationUrl="http://www.box.com/api/oauth2/authorize"
       clientId="your_client_id"
       clientSecret="your_client_secret"
       tokenUrl="http://www.box.com/api/oauth2/token"
       responseAccessToken="#[payload.access_token]"
       responseRefreshToken="#[payload.refresh_token]"
       responseExpiresIn="#[payload.expires_in]" />
   </http:authentication>
</http:request-config>
```

### Configure OAuth2 Authorization Refresh Token When
The access token you obtain from the token URL eventually expires. The length of time the token is valid depends on the authentication server implementation. After the access token expires, instead of going through the whole process once again, you can retrieve a new access token by using the refresh access token provided by the token URL response.
Mule manages this behavior automatically. By default, when an HTTP request is executed, if the response has a status code of 401, Mule calls the token URL and gets a new access token.
You can configure when Mule performs one of these requests to obtain a new access token using a DataWeave expression. The expression is evaluated against the response of the HTTP Request call.
  1. In Studio, select the HTTP **Request** operation from your flow and in the properties editor for **Connector Configuration** , click the plus sign (**+**).
  2. Set **Authentication** to **Authorization code grant type**.
  3. Set **Request Token When** to **Expression**.
  4. In the expression box, add the following DataWeave expression: `#[payload.response.status == 'unauthorized']`


In the **Configuration XML** editor, the `refreshTokenWhen` configuration looks like this:
```
<http:request-config name="HTTP_Request_Configuration"
    host="api.box.com" port="443" basePath="/2.0">
  <http:authentication>
    <oauth:authorization-code-grant-type
    localCallbackUrl="http://localhost:8082/redirectUrl"
    externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
    localAuthorizationUrl="http://localhost:8082/authorization"
    authorizationUrl="http://www.box.com/api/oauth2/authorize"
    clientId="your_client_id"
    clientSecret="your_client_secret"
    tokenUrl="http://www.box.com/api/oauth2/token"
    refreshTokenWhen="#[payload.response.status == 'unauthorized']" />
  </http:authentication>
</http:request-config>
```

When a request authorization fails, the response contains an XML node named `status` with value `'unauthorized'`. In the previous example, the DataWeave expression evaluates that condition. When the condition evaluates to true, Mule sends a request to the token URL to retrieve a new access token.
### Configure HTTPS for OAuth Authorization
When you need to use HTTPS for the communication with the authentication server, such as in a production environment, apply HTTPS encoding to the OAuth credentials in all requests, including those for the:
  * **Local authorization url**
  * **Authorization url**
  * **Redirect url**
  * **Token url**


To configure HTTPS for OAuth Authorization code grant type:
  1. In Studio, select the HTTP **Request** operation from your flow and, in the properties editor for **Connector Configuration** , click the plus sign (**+**).
  2. Set **TLS Configuration** to **Global Reference**.
  3. Click the green plus sign (**+**) next to the field to create a new TLS context.
  4. For **Trust Store Configuration** , set the following fields:
     * **Path** : `your_trust_store`
     * **Password** : `your_password`
  5. For **Key Store Configuration** , set the following fields:
     * **Path** : `your_keystore_path`
     * **Key Password** : `your_key_password`
     * **Password** : `your_password`


In the **Configuration XML** editor, the `tls:context`, `tls:trust-store` and `tls:key-store` configurations look like this:
```
<http:request-config name="HTTP_Request_Configuration_HTTPS"
     host="api.box.com" port="443" basePath="/2.0"
     tlsContext-ref="TLS_Context" protocol="HTTPS">
  <http:authentication>
    <oauth:authorization-code-grant-type
      localCallbackUrl="http://localhost:8082/redirectUrl"
      externalCallbackUrl="http://myapp.mycompany.com:8082/callback"
      localAuthorizationUrl="https://localhost:8082/authorization"
      authorizationUrl="https://www.box.com/api/oauth2/authorize"
      clientId="your_client_id"
      clientSecret="your_client_secret"
      tokenUrl="https://www.box.com/api/oauth2/token"
      tlsContextFactory="TLS_Context"
      scopes="access_user_details, read_user_files" />
  </http:authentication>
</http:request-config>
  <tls:context name="TLS_Context">
    <tls:trust-store path="your_trust_store"
      password="your_password"/>
    <tls:key-store path="your_keystore_path"
      password="your_password" keyPassword="your_key_password"/>
  </tls:context>
```

## Configure OAuth2 Client Credentials Grant Type Authentication
The OAuth authentication server (OAS) is a server that holds the resources that are protected by OAuth. For example, the Box server provides an API with OAuth authentication.
Note that HTTP Connector supports only OAuth 2.0.
The client application (CA) is the server that tries to access a protected resource that belongs to a resource owner (RO). For example, a Mule server tries to access the resources that belong to a Box user, and the resources are in a Box server.
In this case, the RO is also the CA. This means that the CA is implicitly authorized by the RO, which makes the whole procedure a lot simpler.
The following diagram illustrates the relationship between both CA and OAS:
To access protected resources:
  1. The CA must register an app to the OAS server. When this occurs, the OAS assigns credentials to the CA that it can later use to identify itself: `client ID` and `client secret`. The OAS must also provide a `Token URL`, to which the CA can later send HTTP requests to retrieve an `access token` that is required when accessing the protected resources.
  2. The CA makes a request to the `Token URL` of the OAS, containing its client ID to prove its identity. As a response, the OAS grants it an `access token`.
  3. With the access token, the CA is now free to access the protected resources in the OAS as long as it includes the access token in the requests. Depending on the policies defined by the OAS, the token may eventually expire.


Client credentials grant type is meant to be used by a client application to grant access to an application on behalf of itself, rather than on behalf of resource owner in the OAS. To get an access token, all you need is the application credentials.
To configure the OAuth2 authorization code grant type for the HTTP **Request** operation, set the **Authentication** field to **Client credentials grant type** :
  1. In Studio, select the HTTP Request Configuration global element where you want to use the OAuth client credentials grant type.
  2. Set **Authentication** to **Client credentials grant type**.
  3. Set the following fields:
     * **Client id** The client ID that GitHub provided when you registered the app.
     * **Client secret** The client secret that GitHub provided when you registered the app.
     * **Scopes** Scopes in OAuth are like security roles.
     * **Token URL** The Mule client app sends the token to the token URL.


When the Mule app is deployed, it tries to retrieve an access token. If the Mule app is not able to retrieve an access token, deployment fails.
### XML for Configuring Client Credentials Grant Type Authentication
The following code shows how to configure client credentials grant type authentication in XML:
```
<http:request-config name="HTTP_Request_configuration" >
	<http:request-connection host="some.api.com" port="80" >
	<http:authentication>
		<oauth:client-credentials-grant-type
		clientId="your_client_id"
		clientSecret="your_client_secret"
		tokenUrl="http://some.api.com/api/1.0/oauth/token"
		scopes="access_user_details, read_user_files" />
	</http:authentication>
	</http:request-connection>
</http:request-config>
```
When the Mule app is deployed, it tries to retrieve an access token. If the Mule app is not able to retrieve an access token, deployment fails.
### XML for Configuring Client Credentials Grant Type Authentication
The following code shows how to configure client credentials grant type authentication in XML:
```
<http:request-config name="HTTP_Request_configuration" >
	<http:request-connection host="some.api.com" port="80" >
	<http:authentication>
		<oauth:client-credentials-grant-type
		clientId="your_client_id"
		clientSecret="your_client_secret"
		tokenUrl="http://some.api.com/api/1.0/oauth/token"
		scopes="access_user_details, read_user_files" />
	</http:authentication>
	</http:request-connection>
</http:request-config>
```

### Configure OAuth2 Client Credential Extract Parameters
The same behavior of extracting parameters from the token URL that applies to OAuth2 authorization code grant type applies to the client credentials grant type as well:
  1. In Studio, select the HTTP **Request** operation from your flow and, in the properties editor for **Connector Configuration** , click the plus sign (**+**).
  2. Set **Authentication** to **Client credentials grant type**.
  3. Verify the default options for the following fields:
     * **Response access token** : `#[payload.access_token]`
     * **Response refresh token** : `#[payload.refresh_token]`
     * **Response expires in** : `#[payload.expires_in]`


In the **Configuration XML** editor, the `responseAccessToken`, `responseRefreshToken` and `responseExpiresIn` configurations look like this:
```
<http:request-config name="HTTP_Request_Configuration"
          host="api.box.com" port="443" basePath="/2.0">
   <http:authentication>
     <oauth:client-credentials-grant-type
       clientId="CLIENT_ID"
     		clientSecret="CLIENT_SECRET"
     		tokenUrl="http://some.api.com/api/1.0/oauth/token"
     		scopes="access_user_details, read_user_files" />
   </http:authentication>
</http:request-config>
```

### Configure OAuth2 Client Credential Refresh Access Token When
The same behavior of extracting parameters from the token URL that applies to OAuth2 authorization code grant type applies to the client credentials grant type as well:
  1. In Studio, select the HTTP **Request** operation from your flow and, in the properties editor for **Connector Configuration** , click the plus sign (**+**).
  2. Set **Authentication** to **Client credentials grant type**.
  3. Set **Request Token When** to **Expression**.
  4. In the expression box, add the following DataWeave expression: `#[payload.response.status == 'unauthorized']`


In the **Configuration XML** editor, the `refreshTokenWhen` configuration looks like this:
```
<http:request-config name="HTTP_Request_Configuration"
    host="api.box.com" port="443" basePath="/2.0">
  <http:authentication>
   <oauth:client-credentials-grant-type
     clientId="CLIENT_ID"
     clientSecret="CLIENT_SECRET"
     tokenUrl="http://some.api.com/api/1.0/oauth/token"
     scopes="access_user_details, read_user_files"
    refreshTokenWhen="#[payload.response.status == 'unauthorized']" />
  </http:authentication>
</http:request-config>
```

## Configure a Token Manager
To access authorization information for client credentials and authorization codes, configure a token manager:
  1. In Studio, select the HTTP **Request** operation from your flow and, in the properties editor for **Connector Configuration** , click the plus sign (**+**).
  2. Set **Authentication** to **Authorization code grant type**.
  3. Set **Token manager** to **Edit inline**.
  4. Click the plus sign (**+**) to create a new configuration that references an object store.


In the **Configuration XML** editor, the `tokenManager-ref` attribute references a `token-manager-config` element like this:
```
  <oauth:token-manager-config name="Token_Manager_Config"/>
  <http:request-config name="HTTP_Request_Configuration"
             host="api.box.com" port="443" basePath="/2.0">
    <http:authentication>
      <oauth:authorization-code-grant-type
      clientId="your_client_id"
      clientSecret="your_client_secret"
      localCallbackUrl="http://localhost:8082/redirectUrl"
      tokenManager-ref="Token_Manager_Config"
      localAuthorizationUrlResourceOwnerId="#[attributes.queryParams.userId]"
      resourceOwnerId="#[vars.userId]"
      authorizationUrl="https://www.box.com/api/oauth2/authorize"
      localAuthorizationUrl="https://localhost:8082/authorization"
      scopes="access_user_details, read_user_files"
      tokenUrl="https://www.box.com/api/oauth2/token" />
    </http:authentication>
  </http:request-config>
```

### Token Manager - Access Authorization
After you have a token manager associated with an authorization grant type,you can use OAuth module operations anywhere in your Mule app flows to access information from an OAuth authorization.
If you use client credentials or an authorization code with a single resource owner, use the following OAuth module operations in a flow. These operations provide access to the OAuth authorization information from a token manager:
```
<oauth:retrieve-access-token
  tokenManager="tokenManagerConfig"/>
<oauth:retrieve-refresh-token
  tokenManager="tokenManagerConfig"/>
<oauth:retrieve-expires-in
  tokenManager="tokenManagerConfig"/>
<oauth:retrieve-state
  tokenManager="tokenManagerConfig"/>
<oauth:retrieve-custom-token-response-param
  tokenManager="tokenManagerConfig"
  key="#[vars.key]"/>
```

If you use an authorization code with multiple resource owners, use the following OAuth module operations:
```
<oauth:retrieve-access-token
  tokenManager="tokenManagerConfig"
  resourceOwnerId="#[vars.resourceOwnerId]"/>
<oauth:retrieve-refresh-token
  tokenManager="tokenManagerConfig"
  resourceOwnerId="#[vars.resourceOwnerId]"/>
<oauth:retrieve-expires-in
  tokenManager="tokenManagerConfig"
  resourceOwnerId="#[vars.resourceOwnerId]"/>
<oauth:retrieve-state
  tokenManager="tokenManagerConfig"
  resourceOwnerId="#[vars.resourceOwnerId]"/>
<oauth:retrieve-custom-token-response-param
  tokenManager="tokenManagerConfig"
  resourceOwnerId="#[vars.resourceOwnerId]"
  key="#[vars.key]"/>
```

#### Token Manager Examples
The following table includes examples of how to retrieve information from a token manager. Place these OAuth module operations in your flow after the HTTP **Request** operation that manages your OAuth authentication:
Function | Result  
---|---  
`<oauth:retrieve-access-token tokenManager="tokenManagerConfig" target="accessToken"/>` | `accessToken` value accessible through `vars.accessToken` from DataWeave.  
`<oauth:retrieve-access-token tokenManager="tokenManagerConfig" resourceOwnerId="Peter" target="accessToken"/>` | `accessToken` value for the resource owner identified with the ID `Peter` accessible through `vars.accessToken` from DataWeave.  
`<oauth:retrieve-refresh-token tokenManager="tokenManagerConfig" target="refreshToken"/>` | `refreshToken` value accessible through `vars.refreshToken` from DataWeave.  
`<oauth:retrieve-expires-in tokenManager="tokenManagerConfig" target="expiresIn"/>` | Expires in value accessible through `vars.expiresIn` from DataWeave.  
`<oauth:retrieve-state tokenManager="tokenManagerConfig" target="state"/>` | State used for the authorization URL accessible through `vars.state` from DataWeave.  
`<oauth:retrieve-custom-token-response-param tokenManager="tokenManagerConfig" key="a_custom_param_name" target="customParam"/>` | Custom parameter extracted from the token URL response accessible through `vars.customParam` from DataWeave.  
`<oauth:retrieve-custom-token-response-param tokenManager="tokenManagerConfig" resourceOwnerId="Peter" key="a_custom_param_name" target="customParam"/>` | Custom parameter extracted from the token URL response for resource owner `Peter` accessible through `vars.customParam` from DataWeave.  
### Configure Token Manager Access Token Invalidation
When using a token manager, you can block a particular resource owner:
  1. In Studio, drag the OAuth module **Invalidate oauth context** operation to your flow.
  2. In the properties editor, set the token manager to point to the same token manager that your HTTP **Request** operation references when managing OAuth authentication.
  3. Set **Resource owner id** to an expression that points to the resource owner you want to clear, for example, `#[vars.resourceOwnerId]`.


In the **Configuration XML** editor, the `invalidate-oauth-context` configuration looks like this:
```
 <flow name="invalidateOauthContext" >
		<oauth:invalidate-oauth-context
   tokenManager="tokenManagerConfig"
    resourceOwnerId="#[vars.resourceOwnerId]">
		</oauth:invalidate-oauth-context>
	</flow>
```

The **Invalidate oauth context** operation removes all of the OAuth information stored in the token manager.
When using multiple resource owners with a single token manager, if you want to clear only the OAuth information of one resource owner, then specify the resource owner ID in the Invalidate OAuth Context element.
```
<flow name="invalidateOauthContextWithResourceOwnerId">
  <oauth:invalidate-oauth-context
      tokenManager="tokenManagerConfig"
      resourceOwnerId="#[vars.resourceOwnerId]"/>
</flow>
```
In the **Configuration XML** editor, the `invalidate-oauth-context` configuration looks like this:
```
 <flow name="invalidateOauthContext" >
		<oauth:invalidate-oauth-context
   tokenManager="tokenManagerConfig"
    resourceOwnerId="#[vars.resourceOwnerId]">
		</oauth:invalidate-oauth-context>
	</flow>
```

The **Invalidate oauth context** operation removes all of the OAuth information stored in the token manager.
When using multiple resource owners with a single token manager, if you want to clear only the OAuth information of one resource owner, then specify the resource owner ID in the Invalidate OAuth Context element.
```
<flow name="invalidateOauthContextWithResourceOwnerId">
  <oauth:invalidate-oauth-context
      tokenManager="tokenManagerConfig"
      resourceOwnerId="#[vars.resourceOwnerId]"/>
</flow>
```

### Configure Token Manager Object Store
By default, the token manager uses an in-memory object store to store credentials. You can configure the token manager object store by using the **Object store** field.
For further information about object stores, refer to the documentation about configuring a custom object store.
## Access Resources on Behalf of Several Users
When you need to access resources on behalf of several users, use SDK Connectors instead of using HTTP Connector in conjunction with the OAuth module.
## See Also
  * HTTP Connector Overview
  * HTTP Connector XML Reference
  *