# mulesoft HTTP Connector - Full Documentation --- product: HTTP Connector version: 1.10 keywords: http, https, request, requester --- # About HTTP Connector Migration > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Connector for HTTP (HTTP Connector) contains the following key behavior differences: - The `http:listener-config` element has a new inner connection element `http:listener-connection`. - The `http:request-config` element has a new inner connection element `http:request-connection`. - The HTTP body parameter replaces the source parameter in the request and is incorporated into the listener’s response and error response. - The HTTP **Listener** source and HTTP **Request** operation return attributes. - The HTTP **Request** configuration has the **Enabled Cookie** parameter set to `true` (default). - HTTP parsing has been removed because DataWeave now manages special MIME types. Use DataWeave syntax to read and write payloads. - The HTTP **Load static resource** operation XML code `static-resource-handler` is renamed to `load-static-resource`. - To access HTTP listener and HTTP request attributes, the following DataWeave syntax replaces the Mule Expression Language (MEL) expressions for accessing past properties: `#[attributes.]` For expression mapping details, refer to the [HTTP Connector XML Reference](https://docs.mulesoft.com/http-connector/1.10/http-connector-xml-reference) documentation. - The following constructs are removed in Mule 4: - Request and response builders, `http:request-builder` and `http:response-builder` - Worker threading profile The request, response, and error-response replace the builders. Using DataWeave expressions eliminates the need for building parameters. ## See Also - [HTTP Connector XML Reference](https://docs.mulesoft.com/http-connector/1.10/http-connector-xml-reference) - [HTTP Connector Reference](https://docs.mulesoft.com/http-connector/1.10/http-documentation) --- product: HTTP Connector version: 1.11 keywords: http, https, request, requester --- # About HTTP Connector Migration > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Connector for HTTP (HTTP Connector) contains the following key behavior differences: - The `http:listener-config` element has a new inner connection element `http:listener-connection`. - The `http:request-config` element has a new inner connection element `http:request-connection`. - The HTTP body parameter replaces the source parameter in the request and is incorporated into the listener’s response and error response. - The HTTP **Listener** source and HTTP **Request** operation return attributes. - The HTTP **Request** configuration has the **Enabled Cookie** parameter set to `true` (default). - HTTP parsing has been removed because DataWeave now manages special MIME types. Use DataWeave syntax to read and write payloads. - The HTTP **Load static resource** operation XML code `static-resource-handler` is renamed to `load-static-resource`. - To access HTTP listener and HTTP request attributes, the following DataWeave syntax replaces the Mule Expression Language (MEL) expressions for accessing past properties: `#[attributes.]` For expression mapping details, refer to the [HTTP Connector XML Reference](https://docs.mulesoft.com/http-connector/1.11/http-connector-xml-reference) documentation. - The following constructs are removed in Mule 4: - Request and response builders, `http:request-builder` and `http:response-builder` - Worker threading profile The request, response, and error-response replace the builders. Using DataWeave expressions eliminates the need for building parameters. ## See Also - [HTTP Connector XML Reference](https://docs.mulesoft.com/http-connector/1.11/http-connector-xml-reference) - [HTTP Connector Reference](https://docs.mulesoft.com/http-connector/1.11/http-documentation) --- product: HTTP Connector version: 1.12 is-latest-version: true keywords: http, https, request, requester --- # About HTTP Connector Migration > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Connector for HTTP (HTTP Connector) contains the following key behavior differences: - The `http:listener-config` element has a new inner connection element `http:listener-connection`. - The `http:request-config` element has a new inner connection element `http:request-connection`. - The HTTP body parameter replaces the source parameter in the request and is incorporated into the listener’s response and error response. - The HTTP **Listener** source and HTTP **Request** operation return attributes. - The HTTP **Request** configuration has the **Enabled Cookie** parameter set to `true` (default). - HTTP parsing has been removed because DataWeave now manages special MIME types. Use DataWeave syntax to read and write payloads. - The HTTP **Load static resource** operation XML code `static-resource-handler` is renamed to `load-static-resource`. - To access HTTP listener and HTTP request attributes, the following DataWeave syntax replaces the Mule Expression Language (MEL) expressions for accessing past properties: `#[attributes.]` For expression mapping details, refer to the [HTTP Connector XML Reference](https://docs.mulesoft.com/http-connector/latest/http-connector-xml-reference) documentation. - The following constructs are removed in Mule 4: - Request and response builders, `http:request-builder` and `http:response-builder` - Worker threading profile The request, response, and error-response replace the builders. Using DataWeave expressions eliminates the need for building parameters. ## See Also - [HTTP Connector XML Reference](https://docs.mulesoft.com/http-connector/latest/http-connector-xml-reference) - [HTTP Connector Reference](https://docs.mulesoft.com/http-connector/latest/http-documentation) --- product: HTTP Connector version: 1.10 --- # Configure HTTP Listener Source > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The Anypoint Connector for HTTP (HTTP Connector) **Listener** source enables you to set up an HTTP server and trigger flows when receiving HTTP requests. You can choose what methods the source accepts, such as `GET` and `POST` or a list of methods. You can also choose in which path to receive HTTP requests, thereby allowing requests to be routed through different flows. When the HTTP **Listener** source receives an HTTP request, the source triggers the flow by using the request data. The HTTP body is set as the payload, and the remaining HTTP data is set as attributes, such as headers and query parameters. When the flow finishes its execution, the HTTP **Listener** source sends an HTTP response based on whether the flow execution was successful or not, which returns different status codes. You can also customize how the source generates HTTP responses in the connector source configuration. ## Configure HTTP Listener Connection To use an HTTP **Listener** source, you must configure a connection with these settings: - **Host** Indicates where the requests are received. Also, the host can be a hostname, such as `localhost`, `www.mulesoft.com`, or an IP, for example `127.0.0.1`, `::1`. - **Port** Indicates where the requests are received. - **Protocol** Indicates the protocol for communication, either HTTP for plain connections or HTTPS for TLS secure connections. To enable secure connections through HTTPS, you must define a TLS context in the connection and provide: - A keystore for the server - A truststore if you need two-way authentication To learn about TLS configuration, refer to the [Configure TLS with Keystores and Truststores](https://docs.mulesoft.com/mule-runtime/latest/tls-configuration) documentation. Additionally, you can configure the **Base path** field that applies to all HTTP **Listener** sources using the configuration. The following example shows how to configure the HTTP **Listener** connection in Studio: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/path`. ![HTTP Listener configuration window and Path field set to /test](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-1.png) 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of HTTP **Listener** in the app. 5. Set **Host** to `0.0.0.0` and **Port** to `8081`. ![HTTP Listener global configuration window with Host field set to 0.0.0.0 and Port field to 8081](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-2.png) 6. Click the **TLS** tab. 7. Set **TLS configuration** to **Edit inline**. 8. In the **Trust Store Configuration** section, set **Path** to `keystore.jks` and **Password** to `MyP455W0rD`. ![Trust Store Configuration window with Path field set to keystore.jks and Password field to MyP455W0rD](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-3.png) 9. Click **OK**. In the **Configuration XML** editor, the `host`, `port`, `path` and `trust-store` configurations look like these: ```xml

``` To configure the **Base path** field for the source: 1. In the HTTP **Listener** configuration screen, click the plus sign (**+**) next to the **Connector configuration** field to configure a global element. 2. In **HTTP Listener config**, set **Base path** to `api/v1`. ![HTTP Listener global configuration window with Base path field set to api/v1](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-4.png) 3. Click **OK**. In the **Configuration XML** editor, the `basePath` configuration looks like this: ```xml

``` > [!NOTE] If you deploy a project to CloudHub, set **Host** to **0.0.0.0** so the connection listens > to all the interfaces of the machine. > If you deploy locally for testing purposes, set **Host** to **localhost** to receive only requests > that are generated locally. The app is not vulnerable to external threats. You can also configure advanced settings that can define whether the connections are persistent and, if they are not, the timeout the connections will have. ## Configure Paths Because an HTTP **Listener** source acts as an event trigger within flows, it must reference the configuration to use and the path where the source listens for HTTP requests. Paths can be either static, which requires exact matches, or feature placeholders. Placeholders can be: - Wildcards (`*`) Match anything they are compared to. Wildcards at the end of a path can help provide better error messages by capturing requests to unmanaged resources. - Parameters (`{param}`) Match not only anything they are compared to but also capture those values on a URI parameters map. The following examples show different path configurations for three HTTP **Listener** sources, the paths are defined in the **Path** field and the **Base path** field is set to `api/v1`: - `account/mulesoft/main-contact` Matches only the exact path request `http://awesome-company.com/api/v1/account/mulesoft/main-contact`. - `account/{accountId}/main-contact` Matches all path requests structured similarly, such as `http://awesome-company.com/api/v1/account/salesforce/main-contact`, and saves `salesforce` as the value of `accountId`. - `account/{accountId}/*` Matches all path requests different from `main-contact`, such as `http://awesome-company.com/api/v1/account/mulesoft/users`, and saves `mulesoft` as the value of `accountId`. When the Mule app has multiple HTTP **Listener** sources, HTTP requests are always routed to the most specific source. In the previous examples, the first HTTP **Listener** source receives a request with `accountId: mulesoft` and suffix `main-contact`, and the second source receives any different `accountId` value. ## Configure Allowed Methods HTTP requests are routed based on the HTTP method received. By default, an HTTP **Listener** source supports all methods, but you can restrict the available methods or even configure custom ones. The following example shows how to configure the **Allowed methods** field in Studio: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. In the HTTP **Listener** source configuration screen, click the **Advanced** tab. 4. Set **Allowed methods** to `GET`. ![HTTP Listener configuration window and Allowed methods field set to GET](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-5.png) In the **Configuration XML** editor, the `allowedMethods` configuration looks like this: ```xml ``` When a Mule app has multiple HTTP **Listener** sources, requests are routed to the first source matching the method, so default sources should always be defined last. The following example shows different HTTP **Listener** source configurations, in which the **Allowed method** field is set to `GET`, `POST` and `PUT`. These different configurations cause HTTP requests to be routed to different flows, enabling you to specify and restrict user access to your data: ```xml

``` ## Configure Response Streaming Mode When HTTP Connector manages response bodies, the connector considers the type of data to send and uses _chunked_ encoding when the body size is not clear. This causes streams with no size information. To control this behavior, configure the **Response streaming mode** field to any of these options: - **AUTO (default)** Uses `Content-Length` encoding if a size is defined for the body, otherwise uses `Transfer-Encoding: chunked`. - **ALWAYS** Uses `Transfer-Encoding: chunked` regardless of any size data present. - **NEVER** Uses `Content-Length` encoding, consuming streams if necessary to determine the data size. The following example shows how to configure the **Response streaming mode** field in Studio. In the example, the main contact data for an account always returns `Content-Length` encoding: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `account/{accountId}/main-contact`. 4. In the HTTP **Listener** source configuration screen, click the **Advanced** tab. 5. Set **Allowed methods** to `GET`. 6. Set **Response streaming mode** to `NEVER`. ![HTTP Listener configuration window with Allowed methods field set to GET and Response streaming mode field set to NEVER](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-6.png) In the **Configuration XML** editor, the `allowedMethods` and `responseStreamingMode` configurations look like this: ```xml ``` ## Configure Read Timeout The read timeout means that if the HTTP **Listener** source doesn’t read data after read timeout milliseconds, the connector raises a timeout error. Use the **Read timeout** field to prevent a client from sending an HTTP request such as: ```JSON POST /test HTTP/1.1 Host: localhost:8081 Content-Length: 10000 2 ``` Notice that you don’t specify a read timeout, the **Listener** source waits for data for ever, and the connection is not released. The **Read timeout** field defaults to a value of 30000, and the time unit in milliseconds. To configure the read timeout for the source, in the HTTP **Listener** configuration window, set the **Read timeout** field to the desired value: ![HTTP Listener configuration window with Read timeout field set to 30000](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-7.png) In the **Configuration XML** editor, the `readTimeout` configuration looks like this: ```xml

``` ## Configure Reject Invalid Transfer Encoding Headers Based on [RFC7230](https://www.rfc-editor.org/rfc/rfc7230.html) and [RFC2616](https://www.rfc-editor.org/rfc/rfc2616.html) valid Transfer-Encoding headers are `chunked`, `deflate`, `compress`, `identity`, and `gzip`. These headers are not case-sensitive. To reject requests with invalid Transfer-Encoding headers, in the HTTP **Listener** configuration window, select the **Reject invalid transfer encoding** checkbox: ![HTTP Listener configuration window with Reject invalid transfer encoding field selected](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-8.png) In the **Configuration XML** editor, the `rejectInvalidTransferEncoding` configuration looks like this: ```xml

``` ## Receiving HTTP Requests When an HTTP **Listener** source receives an HTTP request, the data from the HTTP request line includes the method, request path, query, URI parameters, and headers as attributes. The body sets the payload, and the `Content-Type` header sets the MIME type, which enables other components to inspect the payload MIME type. For example, DataWeave works with an HTTP payload without requiring any input information. You can refer to attributes, such as headers, query parameters, and so on using the `HttpRequestAttributes` syntax. When you configure an HTTP request, do not set the `Content-Type` header. Mule runtime engine automatically infers the header from the message payload. If you set the `Content-Type` header for payload formatted as `multipart/form-data`, the HTTP request fails with a 400 error status. Additionally, if an HTTP request contains any of these headers: `X-Correlation-ID` or `MULE_CORRELATION_ID`, these set the message’s correlation ID for traceability. ### HTTP Request Example The following example shows an HTTP request: ```JSON POST api/v1/account/salesforce/main-contact?overwrite=true¬ify=jane.doe¬ify=admin HTTP/1.1 Host: localhost:8081 Content-Type: application/json Content-Length: 166 X-Correlation-ID: 9cf32672-4f0b-4e8b-b988-40c13aae85b4 { "name": "John", "surname": "Doe", "role": "Senior Vice President", "organization": "Marketing", "phone": 701222369, "email": "john.doe@salesforce.com" } ``` The message’s correlation ID is `9cf32672-4f0b-4e8b-b988-40c13aae85b4`. The payload is in JSON format: ```JSON { "name": "John", "surname": "Doe", "role": "Senior Vice President", "organization": "Marketing", "phone": 701222369, "email": "john.doe@salesforce.com" } ``` The attributes include: - method: `POST` - listenerPath: `api/v1/account/{accountId}/main-contact` - requestPath: `api/v1/account/salesforce/main-contact` - relativePath: `account/salesforce/main-contact` - queryParams: a multimap with entries `overwrite=true`, `notify=jane.doe`, and `notify=admin` - uriParams: a map with entry `accountId ⇒ salesforce` - headers: a multimap with entries `Host=localhost:8081`, `Content-Type=application/json`, `Content-Length=166`, and `X-Correlation-ID=9cf32672-4f0b-4e8b-b988-40c13aae85b4` A DataWeave expression such as `#[payload.name ' ' payload.surname]` returns `John Doe` because DataWeave correctly interprets the JSON data. A DataWeave expression such as `#['Received a ' attributes.method ' request for account ' attributes.uriParams.accountId '. The following users are notified: ' ++ (attributes.queryParams.*notify joinBy ', ')]` returns `Received a POST request for account salesforce. The following users are notified: admin, jane.doe`. To access HTTP Listener attributes, use DataWeave syntax as shown in the following table:

HTTP object	Mule runtime engine 4.x
Method	#[attributes.method]
Path	#[attributes.listenerPath]
Relative Path	#[attributes.relativePath]
Request URI	#[attributes.requestUri]
Query String	#[attributes.queryString]
Query Parameters	#[attributes.queryParams]
URI Parameters	#[attributes.uriParams]
Version	#[attributes.version]
Scheme	#[attributes.scheme]
Headers	#[attributes.headers]
Remote Address	#[attributes.remoteAddress]
Client Certificate	#[attributes.clientCertificate]

> [!NOTE] _Multimaps_ are similar to maps except they allow several values for a given key. > Multimaps return the first value when using a single-value selector (`.`), but they allow to > retrieve all values when using the multiple-value selector (`.*`). ### HTTP Request Mapping to Mule Event Example The following diagram shows an example of an HTTP request and its mapping to a Mule event. ![Map of HTTP Request to Mule Event](/mulesoft/current/en-us/http-connector/1.10/_images/request-mule-msg-map.png) Use [DataWeave](https://docs.mulesoft.com/dataweave/latest/) language to access the HTTP request data attributes and payload. ### HTTP Request Multipart Form-Data Example The following example shows an HTTP request of an HTML form received by an HTTP **Listener** source. Additionally, the example shows how to use DataWeave expressions to read `multipart/form-data` content. Based on the following HTML form: ```xml ``` The HTTP **Listener** source receives the following `multipart/form-data` HTTP request: ```text POST /api/v1/account/mulesoft/logo HTTP/1.1 Content-Type: multipart/form-data; boundary=489691234097965980223899 Host: localhost:8081 content-length: 34332 --489691234097965980223899 Content-Disposition: form-data; name="name" Corporate Logo --489691234097965980223899 Content-Disposition: form-data; name="logo"; filename="MuleSoft_logo.png" Content-Type: image/png .PNG . ... IHDR.......L......~..... pHYs...#...#.x.?v.. .IDATx....q.W.6.....~".N....t....t..#.....LD0T.CF0b..:.3......Q..@...q]U*y\c.... ....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`% .$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....^6.......|..P.....IEND.B`. --489691234097965980223899 Content-Disposition: form-data; name="color" blue --489691234097965980223899-- ``` You can use DataWeave expressions to access and read each HTTP request parameter data through the `parts` object, either by name or item number. For example, to access the second part of the HTTP request that contains the `Corporate Logo` parameters data, you can use `payload.parts.logo` or `payload.parts[1]`. The latter is useful when a name is not provided. Within each part, you can access its content and headers. For example, `payload.parts.color.content` returns `blue`, while `payload.parts.logo.headers.'Content-Type'` returns `application/png`. You can also access the filename of a part. For example, the `Content-Disposition` header is parsed to allow an expression like `payload.parts.logo.headers.'Content-Disposition'.filename`, which in this case returns `MuleSoft_logo.png`. Refer to the [Formats Supported by DataWeave](https://docs.mulesoft.com/dataweave/latest/dataweave-formats) documentation to learn about reading and writing multipart content. ## Sending HTTP Responses After the triggered flow finishes its execution, the HTTP **Listener** source sends either of the following default results: - Successful execution: an HTTP response with 200 status code and the message payload as the body - Unsuccessful execution: an HTTP error response with 500 status code with the flow error’s description as the body In the HTTP **Listener** source configuration, you can customize HTTP responses by providing the following parameters: - **Body** - **Headers** - **Status code** - **Reason phrase** Note that you can use DataWeave to generate content for each parameter, and variables to propagate data from the flow. ### Create Sending HTTP Responses Mule App Example The following example shows how to configure HTTP responses for the HTTP **Listener** source in Studio. The example is a Mule app flow where an endpoint stores logos for an account: - When storage is successful, an HTTP regular response returns the status code `201`, the reason phrase `Created`, and the body `Corporate Logo has been stored as a MuleSoft logo`. - When storage fails, an HTTP error response returns a status code defined through the `errorCode` variable (if available) or `500` by default. - The custom header returns `X-Time`. - The body returns `Corporate Logo could not be stored`. - If there is a `CONNECTIVITY` error storing the logo, the returned status code is `504`, while any other errors result in a `500` status code. While a reason phrase is not defined for error responses, HTTP Connector attempts to define a reason phrase based on the status code. Thereby, a `Gateway Timeout` or `Internal Server Error` error can be returned for the previous explained HTTP responses scenarios. To test the Mule app you need a table named `logo` with two columns: `(accountId,logoName)`. You can use Mule to create the table or create it some other way. For example, the following XML code shows how to create the table using the Database Connector **Execute script** operation: ```xml ``` To create the Mule app in Studio, follow these steps: 1. In the **Mule Palette** view, select **HTTP>Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/account/{accountId}/logo`. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of HTTP **Listener** in the app. 5. Set **Host** to `0.0.0.0` and **Port** to `8081`. 6. Click **OK**. 7. In the HTTP **Listener** configuration screen, click the **Responses** tab. 8. In the **Response** section, set these values: - **Body** : `output text/plain --- vars.logoName ' has been stored as a ' vars.accountId ++ ' logo.'` - **Status code** : `201` - **Reason phrase** : `Created` 9. In the **Error Response** section, set these values: - **Body** : `vars.logoName ++ ' could not be stored.'` - **Headers** : ```DataWeave output application/java --- { "X-Time" : "50s" // 4 } ``` - **Status code** : `vars.errorCode default 500`. ![HTTP Listener Responses configuration window with Body](/mulesoft/current/en-us/http-connector/1.10/_images/http-listener-9.png) 10. Drag a **Set Variable** component to the right of HTTP **Listener**. 11. Set **Name** to `logoName`. 12. Set **Value** to the expression `payload.parts.name.content`. 13. Drag another **Set Variable** component to the right of first **Set Variable** component. 14. Set **Name** to `accountId`. 15. Set **Value** to the expression `attributes.uriParams.accountId`. 16. Drag a Database **Insert** operation to the right of the second **Set Variable** component. 17. Click the plus sign (**+**) next to the **Connector configuration** field to configure the database connection. For further information about how to configure a database connection, refer to the [configure a database connection](https://docs.mulesoft.com/db-connector/latest/database-connector-connection) documentation. 18. In the **Insert** operation configuration screen, set **SQL Query Text** to `INSERT INTO logo (accountId,logoName) VALUES (:accountId, :logoName`). 19. Set **Input parameters** to the expression `{'accountId': vars.accountId as String, 'logoName': vars.logoName as String}`. 20. Drag an **On Error Propagate** component in the **Error handling** section of the flow. 21. Set **Type** to `DB:CONNECTIVITY`. 22. Drag a **Set Variable** component into the **On Error Propagate** component. 23. Set **Name** to `errorCode`. 24. Set **Value** to `504`. 25. Save and run your Mule app. 26. Send the following CURL command: `curl -v -F 'data=@/path/to/MuleSoft_logo.svg' -F name=mulesoftlogo [http://localhost:8081/account/muley/logo](http://localhost:8081/account/muley/logo)`. Note that the complete payload has been hidden because the content length is too big to be human readable: ```json * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 8081 (#0) > POST /account/muley/logo HTTP/1.1 > Host: localhost:8081 > User-Agent: curl/7.64.1 > Accept: */* > Content-Length: 5313 > Content-Type: multipart/form-data; boundary=------------------------d96e85d23101a1c3 > Expect: 100-continue > < HTTP/1.1 100 Continue * We are completely uploaded and fine < HTTP/1.1 201 Created < Content-Type: text/plain; charset=UTF-8 < Content-Length: 45 < Date: Tue, 18 Jan 2022 20:30:20 GMT < * Connection #0 to host localhost left intact mulesoftlogo has been stored as a muley logo.* Closing connection 0 ``` ### XML for Sending HTTP Responses Mule App Example Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app: ```xml

``` ## See Also - [HTTP Connector Reference](https://docs.mulesoft.com/http-connector/1.10/http-documentation) - [HTTP Connector Troubleshooting Guide](https://docs.mulesoft.com/http-connector/1.10/http-troubleshooting) - [DataWeave Formats](https://docs.mulesoft.com/dataweave/latest/dataweave-formats) - [TLS Configuration](https://docs.mulesoft.com/mule-runtime/latest/tls-configuration) - [HTTP Request Attributes Reference](https://docs.mulesoft.com/http-connector/1.10/http-documentation#HttpRequestAttributes) - [HTTP Response Attributes Reference](https://docs.mulesoft.com/http-connector/1.10/http-documentation#HttpResponseAttributes) --- product: HTTP Connector version: 1.11 --- # Configure HTTP Listener Source > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The Anypoint Connector for HTTP (HTTP Connector) **Listener** source enables you to set up an HTTP server and trigger flows when receiving HTTP requests. You can choose what methods the source accepts, such as `GET` and `POST` or a list of methods. You can also choose in which path to receive HTTP requests, thereby allowing requests to be routed through different flows. When the HTTP **Listener** source receives an HTTP request, the source triggers the flow by using the request data. The HTTP body is set as the payload, and the remaining HTTP data is set as attributes, such as headers and query parameters. When the flow finishes its execution, the HTTP **Listener** source sends an HTTP response based on whether the flow execution was successful or not, which returns different status codes. You can also customize how the source generates HTTP responses in the connector source configuration. ## Configure HTTP Listener Connection To use an HTTP **Listener** source, you must configure a connection with these settings: - **Host** Indicates where the requests are received. Also, the host can be a hostname, such as `localhost`, `www.mulesoft.com`, or an IP, for example `127.0.0.1`, `::1`. - **Port** Indicates where the requests are received. - **Protocol** Indicates the protocol for communication, either HTTP for plain connections or HTTPS for TLS secure connections. To enable secure connections through HTTPS, you must define a TLS context in the connection and provide: - A keystore for the server - A truststore if you need two-way authentication To learn about TLS configuration, refer to the [Configure TLS with Keystores and Truststores](https://docs.mulesoft.com/mule-runtime/latest/tls-configuration) documentation. Additionally, you can configure the **Base path** field that applies to all HTTP **Listener** sources using the configuration. The following example shows how to configure the HTTP **Listener** connection in Studio: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/path`. ![HTTP Listener configuration window and Path field set to /test](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-1.png) 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of HTTP **Listener** in the app. 5. Set **Host** to `0.0.0.0` and **Port** to `8081`. ![HTTP Listener global configuration window with Host field set to 0.0.0.0 and Port field to 8081](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-2.png) 6. Click the **TLS** tab. 7. Set **TLS configuration** to **Edit inline**. 8. In the **Trust Store Configuration** section, set **Path** to `keystore.jks` and **Password** to `MyP455W0rD`. ![Trust Store Configuration window with Path field set to keystore.jks and Password field to MyP455W0rD](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-3.png) 9. Click **OK**. In the **Configuration XML** editor, the `host`, `port`, `path` and `trust-store` configurations look like these: ```xml

``` To configure the **Base path** field for the source: 1. In the HTTP **Listener** configuration screen, click the plus sign (**+**) next to the **Connector configuration** field to configure a global element. 2. In **HTTP Listener config**, set **Base path** to `api/v1`. ![HTTP Listener global configuration window with Base path field set to api/v1](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-4.png) 3. Click **OK**. In the **Configuration XML** editor, the `basePath` configuration looks like this: ```xml

``` > [!NOTE] If you deploy a project to CloudHub, set **Host** to **0.0.0.0** so the connection listens > to all the interfaces of the machine. > If you deploy locally for testing purposes, set **Host** to **localhost** to receive only requests > that are generated locally. The app is not vulnerable to external threats. You can also configure advanced settings that can define whether the connections are persistent and, if they are not, the timeout the connections will have. ## Configure Paths Because an HTTP **Listener** source acts as an event trigger within flows, it must reference the configuration to use and the path where the source listens for HTTP requests. Paths can be either static, which requires exact matches, or feature placeholders. Placeholders can be: - Wildcards (`*`) Match anything they are compared to. Wildcards at the end of a path can help provide better error messages by capturing requests to unmanaged resources. - Parameters (`{param}`) Match not only anything they are compared to but also capture those values on a URI parameters map. The following examples show different path configurations for three HTTP **Listener** sources, the paths are defined in the **Path** field and the **Base path** field is set to `api/v1`: - `account/mulesoft/main-contact` Matches only the exact path request `http://awesome-company.com/api/v1/account/mulesoft/main-contact`. - `account/{accountId}/main-contact` Matches all path requests structured similarly, such as `http://awesome-company.com/api/v1/account/salesforce/main-contact`, and saves `salesforce` as the value of `accountId`. - `account/{accountId}/*` Matches all path requests different from `main-contact`, such as `http://awesome-company.com/api/v1/account/mulesoft/users`, and saves `mulesoft` as the value of `accountId`. When the Mule app has multiple HTTP **Listener** sources, HTTP requests are always routed to the most specific source. In the previous examples, the first HTTP **Listener** source receives a request with `accountId: mulesoft` and suffix `main-contact`, and the second source receives any different `accountId` value. ## Configure Allowed Methods HTTP requests are routed based on the HTTP method received. By default, an HTTP **Listener** source supports all methods, but you can restrict the available methods or even configure custom ones. The following example shows how to configure the **Allowed methods** field in Studio: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. In the HTTP **Listener** source configuration screen, click the **Advanced** tab. 4. Set **Allowed methods** to `GET`. ![HTTP Listener configuration window and Allowed methods field set to GET](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-5.png) In the **Configuration XML** editor, the `allowedMethods` configuration looks like this: ```xml ``` When a Mule app has multiple HTTP **Listener** sources, requests are routed to the first source matching the method, so default sources should always be defined last. The following example shows different HTTP **Listener** source configurations, in which the **Allowed method** field is set to `GET`, `POST` and `PUT`. These different configurations cause HTTP requests to be routed to different flows, enabling you to specify and restrict user access to your data: ```xml

``` ## Configure Response Streaming Mode When HTTP Connector manages response bodies, the connector considers the type of data to send and uses _chunked_ encoding when the body size is not clear. This causes streams with no size information. To control this behavior, configure the **Response streaming mode** field to any of these options: - **AUTO (default)** Uses `Content-Length` encoding if a size is defined for the body, otherwise uses `Transfer-Encoding: chunked`. - **ALWAYS** Uses `Transfer-Encoding: chunked` regardless of any size data present. - **NEVER** Uses `Content-Length` encoding, consuming streams if necessary to determine the data size. The following example shows how to configure the **Response streaming mode** field in Studio. In the example, the main contact data for an account always returns `Content-Length` encoding: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `account/{accountId}/main-contact`. 4. In the HTTP **Listener** source configuration screen, click the **Advanced** tab. 5. Set **Allowed methods** to `GET`. 6. Set **Response streaming mode** to `NEVER`. ![HTTP Listener configuration window with Allowed methods field set to GET and Response streaming mode field set to NEVER](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-6.png) In the **Configuration XML** editor, the `allowedMethods` and `responseStreamingMode` configurations look like this: ```xml ``` ## Configure Read Timeout The read timeout means that if the HTTP **Listener** source doesn’t read data after read timeout milliseconds, the connector raises a timeout error. Use the **Read timeout** field to prevent a client from sending an HTTP request such as: ```JSON POST /test HTTP/1.1 Host: localhost:8081 Content-Length: 10000 2 ``` Notice that you don’t specify a read timeout, the **Listener** source waits for data for ever, and the connection is not released. The **Read timeout** field defaults to a value of 30000, and the time unit in milliseconds. To configure the read timeout for the source, in the HTTP **Listener** configuration window, set the **Read timeout** field to the desired value: ![HTTP Listener configuration window with Read timeout field set to 30000](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-7.png) In the **Configuration XML** editor, the `readTimeout` configuration looks like this: ```xml

``` ## Configure Reject Invalid Transfer Encoding Headers Based on [RFC7230](https://www.rfc-editor.org/rfc/rfc7230.html) and [RFC2616](https://www.rfc-editor.org/rfc/rfc2616.html) valid Transfer-Encoding headers are `chunked`, `deflate`, `compress`, `identity`, and `gzip`. These headers are not case-sensitive. To reject requests with invalid Transfer-Encoding headers, in the HTTP **Listener** configuration window, select the **Reject invalid transfer encoding** checkbox: ![HTTP Listener configuration window with Reject invalid transfer encoding field selected](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-8.png) In the **Configuration XML** editor, the `rejectInvalidTransferEncoding` configuration looks like this: ```xml

HTTP object	Mule runtime engine 4.x
Method	#[attributes.method]
Path	#[attributes.listenerPath]
Relative Path	#[attributes.relativePath]
Request URI	#[attributes.requestUri]
Query String	#[attributes.queryString]
Query Parameters	#[attributes.queryParams]
URI Parameters	#[attributes.uriParams]
Version	#[attributes.version]
Scheme	#[attributes.scheme]
Headers	#[attributes.headers]
Remote Address	#[attributes.remoteAddress]
Client Certificate	#[attributes.clientCertificate]

> [!NOTE] _Multimaps_ are similar to maps except they allow several values for a given key. > Multimaps return the first value when using a single-value selector (`.`), but they allow to > retrieve all values when using the multiple-value selector (`.*`). ### HTTP Request Mapping to Mule Event Example The following diagram shows an example of an HTTP request and its mapping to a Mule event. ![Map of HTTP Request to Mule Event](/mulesoft/current/en-us/http-connector/1.11/_images/request-mule-msg-map.png) Use [DataWeave](https://docs.mulesoft.com/dataweave/latest/) language to access the HTTP request data attributes and payload. ### HTTP Request Multipart Form-Data Example The following example shows an HTTP request of an HTML form received by an HTTP **Listener** source. Additionally, the example shows how to use DataWeave expressions to read `multipart/form-data` content. Based on the following HTML form: ```xml ``` The HTTP **Listener** source receives the following `multipart/form-data` HTTP request: ```text POST /api/v1/account/mulesoft/logo HTTP/1.1 Content-Type: multipart/form-data; boundary=489691234097965980223899 Host: localhost:8081 content-length: 34332 --489691234097965980223899 Content-Disposition: form-data; name="name" Corporate Logo --489691234097965980223899 Content-Disposition: form-data; name="logo"; filename="MuleSoft_logo.png" Content-Type: image/png .PNG . ... IHDR.......L......~..... pHYs...#...#.x.?v.. .IDATx....q.W.6.....~".N....t....t..#.....LD0T.CF0b..:.3......Q..@...q]U*y\c.... ....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`% .$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....^6.......|..P.....IEND.B`. --489691234097965980223899 Content-Disposition: form-data; name="color" blue --489691234097965980223899-- ``` You can use DataWeave expressions to access and read each HTTP request parameter data through the `parts` object, either by name or item number. For example, to access the second part of the HTTP request that contains the `Corporate Logo` parameters data, you can use `payload.parts.logo` or `payload.parts[1]`. The latter is useful when a name is not provided. Within each part, you can access its content and headers. For example, `payload.parts.color.content` returns `blue`, while `payload.parts.logo.headers.'Content-Type'` returns `application/png`. You can also access the filename of a part. For example, the `Content-Disposition` header is parsed to allow an expression like `payload.parts.logo.headers.'Content-Disposition'.filename`, which in this case returns `MuleSoft_logo.png`. Refer to the [Formats Supported by DataWeave](https://docs.mulesoft.com/dataweave/latest/dataweave-formats) documentation to learn about reading and writing multipart content. ## Sending HTTP Responses After the triggered flow finishes its execution, the HTTP **Listener** source sends either of the following default results: - Successful execution: an HTTP response with 200 status code and the message payload as the body - Unsuccessful execution: an HTTP error response with 500 status code with the flow error’s description as the body In the HTTP **Listener** source configuration, you can customize HTTP responses by providing the following parameters: - **Body** - **Headers** - **Status code** - **Reason phrase** Note that you can use DataWeave to generate content for each parameter, and variables to propagate data from the flow. ### Create Sending HTTP Responses Mule App Example The following example shows how to configure HTTP responses for the HTTP **Listener** source in Studio. The example is a Mule app flow where an endpoint stores logos for an account: - When storage is successful, an HTTP regular response returns the status code `201`, the reason phrase `Created`, and the body `Corporate Logo has been stored as a MuleSoft logo`. - When storage fails, an HTTP error response returns a status code defined through the `errorCode` variable (if available) or `500` by default. - The custom header returns `X-Time`. - The body returns `Corporate Logo could not be stored`. - If there is a `CONNECTIVITY` error storing the logo, the returned status code is `504`, while any other errors result in a `500` status code. While a reason phrase is not defined for error responses, HTTP Connector attempts to define a reason phrase based on the status code. Thereby, a `Gateway Timeout` or `Internal Server Error` error can be returned for the previous explained HTTP responses scenarios. To test the Mule app you need a table named `logo` with two columns: `(accountId,logoName)`. You can use Mule to create the table or create it some other way. For example, the following XML code shows how to create the table using the Database Connector **Execute script** operation: ```xml ``` To create the Mule app in Studio, follow these steps: 1. In the **Mule Palette** view, select **HTTP>Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/account/{accountId}/logo`. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of HTTP **Listener** in the app. 5. Set **Host** to `0.0.0.0` and **Port** to `8081`. 6. Click **OK**. 7. In the HTTP **Listener** configuration screen, click the **Responses** tab. 8. In the **Response** section, set these values: - **Body** : `output text/plain --- vars.logoName ' has been stored as a ' vars.accountId ++ ' logo.'` - **Status code** : `201` - **Reason phrase** : `Created` 9. In the **Error Response** section, set these values: - **Body** : `vars.logoName ++ ' could not be stored.'` - **Headers** : ```DataWeave output application/java --- { "X-Time" : "50s" // 4 } ``` - **Status code** : `vars.errorCode default 500`. ![HTTP Listener Responses configuration window with Body](/mulesoft/current/en-us/http-connector/1.11/_images/http-listener-9.png) 10. Drag a **Set Variable** component to the right of HTTP **Listener**. 11. Set **Name** to `logoName`. 12. Set **Value** to the expression `payload.parts.name.content`. 13. Drag another **Set Variable** component to the right of first **Set Variable** component. 14. Set **Name** to `accountId`. 15. Set **Value** to the expression `attributes.uriParams.accountId`. 16. Drag a Database **Insert** operation to the right of the second **Set Variable** component. 17. Click the plus sign (**+**) next to the **Connector configuration** field to configure the database connection. For further information about how to configure a database connection, refer to the [configure a database connection](https://docs.mulesoft.com/db-connector/latest/database-connector-connection) documentation. 18. In the **Insert** operation configuration screen, set **SQL Query Text** to `INSERT INTO logo (accountId,logoName) VALUES (:accountId, :logoName`). 19. Set **Input parameters** to the expression `{'accountId': vars.accountId as String, 'logoName': vars.logoName as String}`. 20. Drag an **On Error Propagate** component in the **Error handling** section of the flow. 21. Set **Type** to `DB:CONNECTIVITY`. 22. Drag a **Set Variable** component into the **On Error Propagate** component. 23. Set **Name** to `errorCode`. 24. Set **Value** to `504`. 25. Save and run your Mule app. 26. Send the following CURL command: `curl -v -F 'data=@/path/to/MuleSoft_logo.svg' -F name=mulesoftlogo [http://localhost:8081/account/muley/logo](http://localhost:8081/account/muley/logo)`. Note that the complete payload has been hidden because the content length is too big to be human readable: ```json * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 8081 (#0) > POST /account/muley/logo HTTP/1.1 > Host: localhost:8081 > User-Agent: curl/7.64.1 > Accept: */* > Content-Length: 5313 > Content-Type: multipart/form-data; boundary=------------------------d96e85d23101a1c3 > Expect: 100-continue > < HTTP/1.1 100 Continue * We are completely uploaded and fine < HTTP/1.1 201 Created < Content-Type: text/plain; charset=UTF-8 < Content-Length: 45 < Date: Tue, 18 Jan 2022 20:30:20 GMT < * Connection #0 to host localhost left intact mulesoftlogo has been stored as a muley logo.* Closing connection 0 ``` ### XML for Sending HTTP Responses Mule App Example Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app: ```xml

``` ## See Also - [HTTP Connector Reference](https://docs.mulesoft.com/http-connector/1.11/http-documentation) - [HTTP Connector Troubleshooting Guide](https://docs.mulesoft.com/http-connector/1.11/http-troubleshooting) - [DataWeave Formats](https://docs.mulesoft.com/dataweave/latest/dataweave-formats) - [TLS Configuration](https://docs.mulesoft.com/mule-runtime/latest/tls-configuration) - [HTTP Request Attributes Reference](https://docs.mulesoft.com/http-connector/1.11/http-documentation#HttpRequestAttributes) - [HTTP Response Attributes Reference](https://docs.mulesoft.com/http-connector/1.11/http-documentation#HttpResponseAttributes) --- product: HTTP Connector version: 1.12 is-latest-version: true --- # Configure HTTP Listener Source > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The Anypoint Connector for HTTP (HTTP Connector) **Listener** source enables you to set up an HTTP server and trigger flows when receiving HTTP requests. You can choose what methods the source accepts, such as `GET` and `POST` or a list of methods. You can also choose in which path to receive HTTP requests, thereby allowing requests to be routed through different flows. When the HTTP **Listener** source receives an HTTP request, the source triggers the flow by using the request data. The HTTP body is set as the payload, and the remaining HTTP data is set as attributes, such as headers and query parameters. When the flow finishes its execution, the HTTP **Listener** source sends an HTTP response based on whether the flow execution was successful or not, which returns different status codes. You can also customize how the source generates HTTP responses in the connector source configuration. ## Configure HTTP Listener Connection To use an HTTP **Listener** source, you must configure a connection with these settings: - **Host** Indicates where the requests are received. Also, the host can be a hostname, such as `localhost`, `www.mulesoft.com`, or an IP, for example `127.0.0.1`, `::1`. - **Port** Indicates where the requests are received. - **Protocol** Indicates the protocol for communication, either HTTP for plain connections or HTTPS for TLS secure connections. To enable secure connections through HTTPS, you must define a TLS context in the connection and provide: - A keystore for the server - A truststore if you need two-way authentication To learn about TLS configuration, refer to the [Configure TLS with Keystores and Truststores](https://docs.mulesoft.com/mule-runtime/latest/tls-configuration) documentation. Additionally, you can configure the **Base path** field that applies to all HTTP **Listener** sources using the configuration. The following example shows how to configure the HTTP **Listener** connection in Studio: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/path`. ![HTTP Listener configuration window and Path field set to /test](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-1.png) 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of HTTP **Listener** in the app. 5. Set **Host** to `0.0.0.0` and **Port** to `8081`. ![HTTP Listener global configuration window with Host field set to 0.0.0.0 and Port field to 8081](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-2.png) 6. Click the **TLS** tab. 7. Set **TLS configuration** to **Edit inline**. 8. In the **Trust Store Configuration** section, set **Path** to `keystore.jks` and **Password** to `MyP455W0rD`. ![Trust Store Configuration window with Path field set to keystore.jks and Password field to MyP455W0rD](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-3.png) 9. Click **OK**. In the **Configuration XML** editor, the `host`, `port`, `path` and `trust-store` configurations look like these: ```xml

``` To configure the **Base path** field for the source: 1. In the HTTP **Listener** configuration screen, click the plus sign (**+**) next to the **Connector configuration** field to configure a global element. 2. In **HTTP Listener config**, set **Base path** to `api/v1`. ![HTTP Listener global configuration window with Base path field set to api/v1](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-4.png) 3. Click **OK**. In the **Configuration XML** editor, the `basePath` configuration looks like this: ```xml

``` > [!NOTE] If you deploy a project to CloudHub, set **Host** to **0.0.0.0** so the connection listens > to all the interfaces of the machine. > If you deploy locally for testing purposes, set **Host** to **localhost** to receive only requests > that are generated locally. The app is not vulnerable to external threats. You can also configure advanced settings that can define whether the connections are persistent and, if they are not, the timeout the connections will have. ## Configure Paths Because an HTTP **Listener** source acts as an event trigger within flows, it must reference the configuration to use and the path where the source listens for HTTP requests. Paths can be either static, which requires exact matches, or feature placeholders. Placeholders can be: - Wildcards (`*`) Match anything they are compared to. Wildcards at the end of a path can help provide better error messages by capturing requests to unmanaged resources. - Parameters (`{param}`) Match not only anything they are compared to but also capture those values on a URI parameters map. The following examples show different path configurations for three HTTP **Listener** sources, the paths are defined in the **Path** field and the **Base path** field is set to `api/v1`: - `account/mulesoft/main-contact` Matches only the exact path request `http://awesome-company.com/api/v1/account/mulesoft/main-contact`. - `account/{accountId}/main-contact` Matches all path requests structured similarly, such as `http://awesome-company.com/api/v1/account/salesforce/main-contact`, and saves `salesforce` as the value of `accountId`. - `account/{accountId}/*` Matches all path requests different from `main-contact`, such as `http://awesome-company.com/api/v1/account/mulesoft/users`, and saves `mulesoft` as the value of `accountId`. When the Mule app has multiple HTTP **Listener** sources, HTTP requests are always routed to the most specific source. In the previous examples, the first HTTP **Listener** source receives a request with `accountId: mulesoft` and suffix `main-contact`, and the second source receives any different `accountId` value. ## Configure Allowed Methods HTTP requests are routed based on the HTTP method received. By default, an HTTP **Listener** source supports all methods, but you can restrict the available methods or even configure custom ones. The following example shows how to configure the **Allowed methods** field in Studio: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. In the HTTP **Listener** source configuration screen, click the **Advanced** tab. 4. Set **Allowed methods** to `GET`. ![HTTP Listener configuration window and Allowed methods field set to GET](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-5.png) In the **Configuration XML** editor, the `allowedMethods` configuration looks like this: ```xml ``` When a Mule app has multiple HTTP **Listener** sources, requests are routed to the first source matching the method, so default sources should always be defined last. The following example shows different HTTP **Listener** source configurations, in which the **Allowed method** field is set to `GET`, `POST` and `PUT`. These different configurations cause HTTP requests to be routed to different flows, enabling you to specify and restrict user access to your data: ```xml

``` ## Configure Response Streaming Mode When HTTP Connector manages response bodies, the connector considers the type of data to send and uses _chunked_ encoding when the body size is not clear. This causes streams with no size information. To control this behavior, configure the **Response streaming mode** field to any of these options: - **AUTO (default)** Uses `Content-Length` encoding if a size is defined for the body, otherwise uses `Transfer-Encoding: chunked`. - **ALWAYS** Uses `Transfer-Encoding: chunked` regardless of any size data present. - **NEVER** Uses `Content-Length` encoding, consuming streams if necessary to determine the data size. The following example shows how to configure the **Response streaming mode** field in Studio. In the example, the main contact data for an account always returns `Content-Length` encoding: 1. In the **Mule Palette** view, select **HTTP > Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `account/{accountId}/main-contact`. 4. In the HTTP **Listener** source configuration screen, click the **Advanced** tab. 5. Set **Allowed methods** to `GET`. 6. Set **Response streaming mode** to `NEVER`. ![HTTP Listener configuration window with Allowed methods field set to GET and Response streaming mode field set to NEVER](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-6.png) In the **Configuration XML** editor, the `allowedMethods` and `responseStreamingMode` configurations look like this: ```xml ``` ## Configure Read Timeout The read timeout means that if the HTTP **Listener** source doesn’t read data after read timeout milliseconds, the connector raises a timeout error. Use the **Read timeout** field to prevent a client from sending an HTTP request such as: ```JSON POST /test HTTP/1.1 Host: localhost:8081 Content-Length: 10000 2 ``` Notice that you don’t specify a read timeout, the **Listener** source waits for data for ever, and the connection is not released. The **Read timeout** field defaults to a value of 30000, and the time unit in milliseconds. To configure the read timeout for the source, in the HTTP **Listener** configuration window, set the **Read timeout** field to the desired value: ![HTTP Listener configuration window with Read timeout field set to 30000](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-7.png) In the **Configuration XML** editor, the `readTimeout` configuration looks like this: ```xml

``` ## Configure Reject Invalid Transfer Encoding Headers Based on [RFC7230](https://www.rfc-editor.org/rfc/rfc7230.html) and [RFC2616](https://www.rfc-editor.org/rfc/rfc2616.html) valid Transfer-Encoding headers are `chunked`, `deflate`, `compress`, `identity`, and `gzip`. These headers are not case-sensitive. To reject requests with invalid Transfer-Encoding headers, in the HTTP **Listener** configuration window, select the **Reject invalid transfer encoding** checkbox: ![HTTP Listener configuration window with Reject invalid transfer encoding field selected](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-8.png) In the **Configuration XML** editor, the `rejectInvalidTransferEncoding` configuration looks like this: ```xml

HTTP object	Mule runtime engine 4.x
Method	#[attributes.method]
Path	#[attributes.listenerPath]
Relative Path	#[attributes.relativePath]
Request URI	#[attributes.requestUri]
Query String	#[attributes.queryString]
Query Parameters	#[attributes.queryParams]
URI Parameters	#[attributes.uriParams]
Version	#[attributes.version]
Scheme	#[attributes.scheme]
Headers	#[attributes.headers]
Remote Address	#[attributes.remoteAddress]
Client Certificate	#[attributes.clientCertificate]

> [!NOTE] _Multimaps_ are similar to maps except they allow several values for a given key. > Multimaps return the first value when using a single-value selector (`.`), but they allow to > retrieve all values when using the multiple-value selector (`.*`). ### HTTP Request Mapping to Mule Event Example The following diagram shows an example of an HTTP request and its mapping to a Mule event. ![Map of HTTP Request to Mule Event](/mulesoft/current/en-us/http-connector/latest/_images/request-mule-msg-map.png) Use [DataWeave](https://docs.mulesoft.com/dataweave/latest/) language to access the HTTP request data attributes and payload. ### HTTP Request Multipart Form-Data Example The following example shows an HTTP request of an HTML form received by an HTTP **Listener** source. Additionally, the example shows how to use DataWeave expressions to read `multipart/form-data` content. Based on the following HTML form: ```xml ``` The HTTP **Listener** source receives the following `multipart/form-data` HTTP request: ```text POST /api/v1/account/mulesoft/logo HTTP/1.1 Content-Type: multipart/form-data; boundary=489691234097965980223899 Host: localhost:8081 content-length: 34332 --489691234097965980223899 Content-Disposition: form-data; name="name" Corporate Logo --489691234097965980223899 Content-Disposition: form-data; name="logo"; filename="MuleSoft_logo.png" Content-Type: image/png .PNG . ... IHDR.......L......~..... pHYs...#...#.x.?v.. .IDATx....q.W.6.....~".N....t....t..#.....LD0T.CF0b..:.3......Q..@...q]U*y\c.... ....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`% .$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....V"H....`%.$....^6.......|..P.....IEND.B`. --489691234097965980223899 Content-Disposition: form-data; name="color" blue --489691234097965980223899-- ``` You can use DataWeave expressions to access and read each HTTP request parameter data through the `parts` object, either by name or item number. For example, to access the second part of the HTTP request that contains the `Corporate Logo` parameters data, you can use `payload.parts.logo` or `payload.parts[1]`. The latter is useful when a name is not provided. Within each part, you can access its content and headers. For example, `payload.parts.color.content` returns `blue`, while `payload.parts.logo.headers.'Content-Type'` returns `application/png`. You can also access the filename of a part. For example, the `Content-Disposition` header is parsed to allow an expression like `payload.parts.logo.headers.'Content-Disposition'.filename`, which in this case returns `MuleSoft_logo.png`. Refer to the [Formats Supported by DataWeave](https://docs.mulesoft.com/dataweave/latest/dataweave-formats) documentation to learn about reading and writing multipart content. ## Sending HTTP Responses After the triggered flow finishes its execution, the HTTP **Listener** source sends either of the following default results: - Successful execution: an HTTP response with 200 status code and the message payload as the body - Unsuccessful execution: an HTTP error response with 500 status code with the flow error’s description as the body In the HTTP **Listener** source configuration, you can customize HTTP responses by providing the following parameters: - **Body** - **Headers** - **Status code** - **Reason phrase** Note that you can use DataWeave to generate content for each parameter, and variables to propagate data from the flow. ### Create Sending HTTP Responses Mule App Example The following example shows how to configure HTTP responses for the HTTP **Listener** source in Studio. The example is a Mule app flow where an endpoint stores logos for an account: - When storage is successful, an HTTP regular response returns the status code `201`, the reason phrase `Created`, and the body `Corporate Logo has been stored as a MuleSoft logo`. - When storage fails, an HTTP error response returns a status code defined through the `errorCode` variable (if available) or `500` by default. - The custom header returns `X-Time`. - The body returns `Corporate Logo could not be stored`. - If there is a `CONNECTIVITY` error storing the logo, the returned status code is `504`, while any other errors result in a `500` status code. While a reason phrase is not defined for error responses, HTTP Connector attempts to define a reason phrase based on the status code. Thereby, a `Gateway Timeout` or `Internal Server Error` error can be returned for the previous explained HTTP responses scenarios. To test the Mule app you need a table named `logo` with two columns: `(accountId,logoName)`. You can use Mule to create the table or create it some other way. For example, the following XML code shows how to create the table using the Database Connector **Execute script** operation: ```xml ``` To create the Mule app in Studio, follow these steps: 1. In the **Mule Palette** view, select **HTTP>Listener**. 2. Drag **Listener** to the Studio canvas. 3. Set **Path** to `/account/{accountId}/logo`. 4. Click the plus sign (**+**) next to the **Connector configuration** field to configure a global element that can be used by all instances of HTTP **Listener** in the app. 5. Set **Host** to `0.0.0.0` and **Port** to `8081`. 6. Click **OK**. 7. In the HTTP **Listener** configuration screen, click the **Responses** tab. 8. In the **Response** section, set these values: - **Body** : `output text/plain --- vars.logoName ' has been stored as a ' vars.accountId ++ ' logo.'` - **Status code** : `201` - **Reason phrase** : `Created` 9. In the **Error Response** section, set these values: - **Body** : `vars.logoName ++ ' could not be stored.'` - **Headers** : ```DataWeave output application/java --- { "X-Time" : "50s" // 4 } ``` - **Status code** : `vars.errorCode default 500`. ![HTTP Listener Responses configuration window with Body](/mulesoft/current/en-us/http-connector/latest/_images/http-listener-9.png) 10. Drag a **Set Variable** component to the right of HTTP **Listener**. 11. Set **Name** to `logoName`. 12. Set **Value** to the expression `payload.parts.name.content`. 13. Drag another **Set Variable** component to the right of first **Set Variable** component. 14. Set **Name** to `accountId`. 15. Set **Value** to the expression `attributes.uriParams.accountId`. 16. Drag a Database **Insert** operation to the right of the second **Set Variable** component. 17. Click the plus sign (**+**) next to the **Connector configuration** field to configure the database connection. For further information about how to configure a database connection, refer to the [configure a database connection](https://docs.mulesoft.com/db-connector/latest/database-connector-connection) documentation. 18. In the **Insert** operation configuration screen, set **SQL Query Text** to `INSERT INTO logo (accountId,logoName) VALUES (:accountId, :logoName`). 19. Set **Input parameters** to the expression `{'accountId': vars.accountId as String, 'logoName': vars.logoName as String}`. 20. Drag an **On Error Propagate** component in the **Error handling** section of the flow. 21. Set **Type** to `DB:CONNECTIVITY`. 22. Drag a **Set Variable** component into the **On Error Propagate** component. 23. Set **Name** to `errorCode`. 24. Set **Value** to `504`. 25. Save and run your Mule app. 26. Send the following CURL command: `curl -v -F 'data=@/path/to/MuleSoft_logo.svg' -F name=mulesoftlogo [http://localhost:8081/account/muley/logo](http://localhost:8081/account/muley/logo)`. Note that the complete payload has been hidden because the content length is too big to be human readable: ```json * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 8081 (#0) > POST /account/muley/logo HTTP/1.1 > Host: localhost:8081 > User-Agent: curl/7.64.1 > Accept: */* > Content-Length: 5313 > Content-Type: multipart/form-data; boundary=------------------------d96e85d23101a1c3 > Expect: 100-continue > < HTTP/1.1 100 Continue * We are completely uploaded and fine < HTTP/1.1 201 Created < Content-Type: text/plain; charset=UTF-8 < Content-Length: 45 < Date: Tue, 18 Jan 2022 20:30:20 GMT < * Connection #0 to host localhost left intact mulesoftlogo has been stored as a muley logo.* Closing connection 0 ``` ### XML for Sending HTTP Responses Mule App Example Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app: ```xml

``` ## See Also - [HTTP Connector Reference](https://docs.mulesoft.com/http-connector/latest/http-documentation) - [HTTP Connector Troubleshooting Guide](https://docs.mulesoft.com/http-connector/latest/http-troubleshooting) - [DataWeave Formats](https://docs.mulesoft.com/dataweave/latest/dataweave-formats) - [TLS Configuration](https://docs.mulesoft.com/mule-runtime/latest/tls-configuration) - [HTTP Request Attributes Reference](https://docs.mulesoft.com/http-connector/latest/http-documentation#HttpRequestAttributes) - [HTTP Response Attributes Reference](https://docs.mulesoft.com/http-connector/latest/http-documentation#HttpResponseAttributes) # 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](#basic-authentication) - [Digest Authentication](#digest-authentication) - [NTLM Authentication](#ntlm-authentication) - [OAuth2 Authorization Code Grant Type Authentication](#oauth2-grant-authentication) - [OAuth2 Client Credentials Grant Type Authentication](#oauth2-client-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](https://docs.mulesoft.com/mule-gateway/policies-included-oauth-access-token-enforcement) documentation.

In Anypoint Studio HTTP Request operation global configuration, do not use the Expression option for the Authentication field.

## [](#http-xml-auth-setup)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: ```xml org.mule.modules mule-oauth-module 1.1.8 mule-plugin ``` ## [](#basic-authentication)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](https://docs.github.com/en/rest) 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` - **Port**: `443` 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](https://github.com/settings/tokens). 14. Set **Preemptive** to **True (Default)**. 15. Click **OK**. ![HTTP Request basic authentication window configuration](/mulesoft/current/en-us/http-connector/1.10/_images/http-basic-authentication-1.png) 16. In the HTTP **Request** configuration window, set **Method** to **GET (Default)**. 17. Set **Path** to `/user`. 18. In the **Mule Palette**, select **Core > Transform message**. 19. Drag the **Transform message** component to the right of the HTTP **Request** operation. 20. In the **Output** properties window, change the output to the following DataWeave code: ```dataweave %dw 2.0 output application/json --- payload ``` 21. Save your Mule app. 22. Click **Run > Run as > Mule Application**. 23. To call the API, type `http://localhost:8081/` in your internet browser. The GitHub API returns your user information, for example: ```json { "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](https://github.com/settings/tokens) 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)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

``` ## [](#digest-authentication)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`. 8. Click **OK**. ![HTTP Request digest authentication window configuration](/mulesoft/current/en-us/http-connector/1.10/_images/http-digest-authentication-1.png) ### [](#xml-for-configuring-digest-authentication-example)XML for Configuring Digest Authentication Example The following code shows how to configure the digest authentication in XML: ```xml ...

... ``` ## [](#ntlm-authentication)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**. 9. Click **OK**. ![HTTP Request NTLM authentication window configuration](/mulesoft/current/en-us/http-connector/1.10/_images/http-NTLM-authentication-1.png) ### [](#xml-for-configuring-ntlm-authentication)XML for Configuring NTLM Authentication The following code shows how to configure the NTLM authentication in XML: ```xml

... ``` ## [](#oauth2-grant-authentication)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](https://docs.github.com/en/rest/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: ![Get OAuth access token diagram](/mulesoft/current/en-us/http-connector/1.10/_images/http-authentication-diagram-2.png) 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. ![Return token for data diagram](/mulesoft/current/en-us/http-connector/1.10/_images/http-authentication-diagram-3.png) 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)Set Up Authorization To set up the authorization, follow these steps: ![Set up authorization](/mulesoft/current/en-us/http-connector/1.10/_images/http-authentication-diagram-1.png) 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](https://github.com/settings/applications/new) 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/` that includes the GitHub-assigned client ID and client secret. ### [](#create-the-mule-app)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 `` section and before the `` statement, add the following statement to enable OAuth options for the **Request** operation: ```xml org.mule.modules mule-oauth-module 1.1.8 mule-plugin ``` 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. ![Configure Authorization code grant type authentication](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-authentication-1.png) 14. Click **OK**. 15. Save your Mule app. ### [](#run-the-mule-client-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](https://datatracker.ietf.org/doc/html/rfc6749). 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. ![Github Authorize application page](/mulesoft/current/en-us/http-connector/1.10/_images/http-authentication-githubpage.png) 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)XML for Configuring OAuth2 Authorization Code Example The following code shows how to configure OAuth2 Authorization Code in XML: ```xml

``` ### [](#configure-oauth2-authorization-scopes)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`. ![Configure Scopes field for OAuth Authentication](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-scopes.png) 5. Click **OK**. In the **Configuration XML** editor, the `scopes` configuration looks like this: ```xml

``` ### [](#configure-oauth2-authorization-custom-parameters)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`. ![Configure Custom Parameters field for OAuth Authentication](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-customparameter.png) 10. Click **OK**. In the **Configuration XML** editor, the `oauth:custom-parameter` configuration looks like this: ```xml

``` ### [](#configure-oauth2-authorization-redirect-uri)Configure OAuth2 Authorization Redirect URI The [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749) 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://.cloudhub.io/` 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)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](https://docs.mulesoft.com/mule-runtime/latest/dataweave) 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]` ![Configure Response access token](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-extractparameters.png) 1. Click **OK**. In the **Configuration XML** editor, the `responseAccessToken`, `responseRefreshToken` and `responseExpiresIn` configurations look like this: ```xml

``` ### [](#configure-oauth2-authorization-refresh-token-when)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](https://docs.mulesoft.com/mule-runtime/latest/dataweave). 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']` ![Configure Response Token When field for OAuth Authentication](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-refreshtoken.png) In the **Configuration XML** editor, the `refreshTokenWhen` configuration looks like this: ```xml

``` 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)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**. ![TLS Configuration field set to Global reference](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-tls-1.png) 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` ![TLS Context global configuration settings window](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-tls-2.png) 1. Click **OK**. In the **Configuration XML** editor, the `tls:context`, `tls:trust-store` and `tls:key-store` configurations look like this: ```xml

``` ## [](#oauth2-client-authentication)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: ![OAuth2 dance between CA and OAS](/mulesoft/current/en-us/http-connector/1.10/_images/http-authentication-diagram-4.png) 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. ![Client credentials grant type configuration](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauthcc-authentication-1.png) 1. Click **OK**. 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)XML for Configuring Client Credentials Grant Type Authentication The following code shows how to configure client credentials grant type authentication in XML: ```xml

``` ### [](#configure-oauth2-client-credential-extract-parameters)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]` ![Configure Response access token](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauthcc-extractparameters.png) 1. Click **OK**. In the **Configuration XML** editor, the `responseAccessToken`, `responseRefreshToken` and `responseExpiresIn` configurations look like this: ```xml

``` ### [](#configure-oauth2-client-credential-refresh-access-token-when)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']` ![Configure Response Token When field for OAuth2 Client credentials grant type](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauthcc-refreshtoken.png) 1. Click **OK**. In the **Configuration XML** editor, the `refreshTokenWhen` configuration looks like this: ```xml

``` ## [](#configure-a-token-manager)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. ![Configure Token manager](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-tokenmanager-1.png) 1. Click **OK**. In the **Configuration XML** editor, the `tokenManager-ref` attribute references a `token-manager-config` element like this: ```xml

``` ### [](#token-manager-access-authorization)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: ```xml

``` If you use an authorization code with multiple resource owners, use the following OAuth module operations: ```xml

``` #### [](#token-manager-examples)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

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.

<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)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]`. ![Configure Token manager](/mulesoft/current/en-us/http-connector/1.10/_images/http-oauth-tokenmanager-2.png) In the **Configuration XML** editor, the `invalidate-oauth-context` configuration looks like this: ```xml

``` 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. ```xml

In Anypoint Studio HTTP Request operation global configuration, do not use the Expression option for the Authentication field.

## [](#http-xml-auth-setup)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: ```xml org.mule.modules mule-oauth-module 1.1.8 mule-plugin ``` ## [](#basic-authentication)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](https://docs.github.com/en/rest) 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` - **Port**: `443` 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](https://github.com/settings/tokens). 14. Set **Preemptive** to **True (Default)**. 15. Click **OK**. ![HTTP Request basic authentication window configuration](/mulesoft/current/en-us/http-connector/1.11/_images/http-basic-authentication-1.png) 16. In the HTTP **Request** configuration window, set **Method** to **GET (Default)**. 17. Set **Path** to `/user`. 18. In the **Mule Palette**, select **Core > Transform message**. 19. Drag the **Transform message** component to the right of the HTTP **Request** operation. 20. In the **Output** properties window, change the output to the following DataWeave code: ```dataweave %dw 2.0 output application/json --- payload ``` 21. Save your Mule app. 22. Click **Run > Run as > Mule Application**. 23. To call the API, type `http://localhost:8081/` in your internet browser. The GitHub API returns your user information, for example: ```json { "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](https://github.com/settings/tokens) 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)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

``` ## [](#digest-authentication)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`. 8. Click **OK**. ![HTTP Request digest authentication window configuration](/mulesoft/current/en-us/http-connector/1.11/_images/http-digest-authentication-1.png) ### [](#xml-for-configuring-digest-authentication-example)XML for Configuring Digest Authentication Example The following code shows how to configure the digest authentication in XML: ```xml ...

... ``` ## [](#ntlm-authentication)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**. 9. Click **OK**. ![HTTP Request NTLM authentication window configuration](/mulesoft/current/en-us/http-connector/1.11/_images/http-NTLM-authentication-1.png) ### [](#xml-for-configuring-ntlm-authentication)XML for Configuring NTLM Authentication The following code shows how to configure the NTLM authentication in XML: ```xml

... ``` ## [](#oauth2-grant-authentication)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](https://docs.github.com/en/rest/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: ![Get OAuth access token diagram](/mulesoft/current/en-us/http-connector/1.11/_images/http-authentication-diagram-2.png) 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. ![Return token for data diagram](/mulesoft/current/en-us/http-connector/1.11/_images/http-authentication-diagram-3.png) 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)Set Up Authorization To set up the authorization, follow these steps: ![Set up authorization](/mulesoft/current/en-us/http-connector/1.11/_images/http-authentication-diagram-1.png) 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](https://github.com/settings/applications/new) 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/` that includes the GitHub-assigned client ID and client secret. ### [](#create-the-mule-app)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 `` section and before the `` statement, add the following statement to enable OAuth options for the **Request** operation: ```xml org.mule.modules mule-oauth-module 1.1.8 mule-plugin ``` 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. ![Configure Authorization code grant type authentication](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-authentication-1.png) 14. Click **OK**. 15. Save your Mule app. ### [](#run-the-mule-client-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](https://datatracker.ietf.org/doc/html/rfc6749). 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. ![Github Authorize application page](/mulesoft/current/en-us/http-connector/1.11/_images/http-authentication-githubpage.png) 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)XML for Configuring OAuth2 Authorization Code Example The following code shows how to configure OAuth2 Authorization Code in XML: ```xml

``` ### [](#configure-oauth2-authorization-scopes)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`. ![Configure Scopes field for OAuth Authentication](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-scopes.png) 5. Click **OK**. In the **Configuration XML** editor, the `scopes` configuration looks like this: ```xml

``` ### [](#configure-oauth2-authorization-custom-parameters)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`. ![Configure Custom Parameters field for OAuth Authentication](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-customparameter.png) 10. Click **OK**. In the **Configuration XML** editor, the `oauth:custom-parameter` configuration looks like this: ```xml

``` ### [](#configure-oauth2-authorization-redirect-uri)Configure OAuth2 Authorization Redirect URI The [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749) 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://.cloudhub.io/` 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)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](https://docs.mulesoft.com/mule-runtime/latest/dataweave) 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]` ![Configure Response access token](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-extractparameters.png) 1. Click **OK**. In the **Configuration XML** editor, the `responseAccessToken`, `responseRefreshToken` and `responseExpiresIn` configurations look like this: ```xml

``` ### [](#configure-oauth2-authorization-refresh-token-when)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](https://docs.mulesoft.com/mule-runtime/latest/dataweave). 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']` ![Configure Response Token When field for OAuth Authentication](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-refreshtoken.png) In the **Configuration XML** editor, the `refreshTokenWhen` configuration looks like this: ```xml

``` 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)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**. ![TLS Configuration field set to Global reference](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-tls-1.png) 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` ![TLS Context global configuration settings window](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-tls-2.png) 1. Click **OK**. In the **Configuration XML** editor, the `tls:context`, `tls:trust-store` and `tls:key-store` configurations look like this: ```xml

``` ## [](#oauth2-client-authentication)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: ![OAuth2 dance between CA and OAS](/mulesoft/current/en-us/http-connector/1.11/_images/http-authentication-diagram-4.png) 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. ![Client credentials grant type configuration](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauthcc-authentication-1.png)

Although the Client id and Client secret fields support using variables, the connector doesn’t support changing these values dynamically during each flow execution. The configured credentials must remain static. If you require multiple sets of client credentials, it is recommended to create a separate configuration for each client.

1. Click **OK**. 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)XML for Configuring Client Credentials Grant Type Authentication The following code shows how to configure client credentials grant type authentication in XML: ```xml

``` ### [](#configure-oauth2-client-credential-extract-parameters)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]` ![Configure Response access token](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauthcc-extractparameters.png) 1. Click **OK**. In the **Configuration XML** editor, the `responseAccessToken`, `responseRefreshToken` and `responseExpiresIn` configurations look like this: ```xml

``` ### [](#configure-oauth2-client-credential-refresh-access-token-when)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']` ![Configure Response Token When field for OAuth2 Client credentials grant type](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauthcc-refreshtoken.png) 1. Click **OK**. In the **Configuration XML** editor, the `refreshTokenWhen` configuration looks like this: ```xml

``` ## [](#configure-a-token-manager)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. ![Configure Token manager](/mulesoft/current/en-us/http-connector/1.11/_images/http-oauth-tokenmanager-1.png) 1. Click **OK**. In the **Configuration XML** editor, the `tokenManager-ref` attribute references a `token-manager-config` element like this: ```xml

``` If you use an authorization code with multiple resource owners, use the following OAuth module operations: ```xml

Function Result

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.