Authentication in HTTP Requests

First, you register the client application on the authentication server. The authentication server assigns a client ID and client secret to the Mule client app. The app uses these credentials later to identify itself to the authentication server. During the registration, you also provide the URL to the Mule app home page and the application callback URL.

To set up the example Mule client application:

In this section, you create the Mule client app that uses the Github assigned client ID and client secret to access the user data on the Github OAuth2 authentication server. The sample consists of an HTTP listen connector, an HTTP request connector, and a DataWeave (Transform) component for transforming plain text to JSON. In the HTTP requester, you configure access to the authentication server.

In the following procedure, you configure a number of options, including these:

To configure the Mule client app for accessing the Github authentication server:

Next, set up an HTTP request connector:

Within the global configuration of the connector, add an oauth2:authorization-code-grant-type child element, include the following values in it:

If you were required to provide a redirect URL when registering your application with Github, this value must match what you provided there.

Inside this element, add a oauth2:authorization-request child element with the following attributes:

Also, at the same level, add a oauth2:token-request child element with the following attribute:

After deploying the Mule client app, you follow the procedure in this section to run the app. The procedure covers the following actions:

To run the Mule client app to get Github user data:

Perform these steps before the access token expires:

Configuring the scopes attribute in the Mule client app is optional, and not needed for the Github example. To configure scopes, define a comma separated list of OAuth scopes available in the authentication server. Scopes in OAuth are like security roles.

There are OAuth implementations that require or allow extra query parameters to be sent when calling the Authentication URL of the OAS.

This example includes two Oauth2:custom-parameter child elements that define parameters that are specific to this API.

The OAuth 2.0 specification describes checking the redirect URI from the destination site of the redirect. The OAuth authentication server uses the URL to provide the authentication code to the Mule server for retrieving the access token. If you provide this URL, Mule creates an endpoint at the URL for storing the authentication code unless there’s already an endpoint registered to manually extract the authorization code.

You configure the external redirect URI by setting the system property mule.oauth2.externalRedirectUrl.

Using mule.oauth2.externalRedirectUrl is particularly useful for deploying applications to CloudHub, for example. In the configuration of authentication, you need to specify the redirectionURL in the following format:

For example, the redirectionURLis http://localhost:8082/callback in the previous example:

To create the endpoint for CloudHub, Mule has to create an endpoint for CloudHub in a different format. For example:

https://<app>.cloudhub.io/<redirect Uri>

To instruct Mule to create the endpoint for CloudHub in the correct format, include the mule.oauth2.externalRedirectUrl system property in your Mule properties file. For example:

After you have obtained an authorization code from the authentication server, you make a request to the Token URL of the server to receive an access token.

The format of the response to the request to the token URL is not defined in the OAuth spec. Each implementation may therefore return different response formats. By default, Mule expects the response to be in JSON format. When this is the case, the HTTP Response Connector knows how to extract the required information, as long as its elements are named as below:

When the response is in JSON format, the parameters are automatically extracted and you can use MEL expressions to reference these values in the Mule Message that was generated from the response to the request to the token URL, as shown in the previous Github example.

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, the 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 MEL expressions, such as #[payload.'access_token'].

On the Authentication tab, configure the options as follows for the OAuth2 - Authorization Code:

This example includes two Oauth2:custom-parameter child elements that define parameters specific to this API.

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 handles this use case automatically. So by default, when an HTTP Request Connector is executed, if the response has a status code of 403, mule call the token URL and gets a new access token.

You can customize when Mule performs one of these requests to obtain a new access token using a MEL Expression. The expression is evaluated against the Mule Message that is generated from the response of the HTTP Request Connector call.

On the Authentication tab, configure the Request Token When field with the following MEL expression: #[xpath3('/response/status/text()', payload, 'STRING') == ‘unauthorized’]

To set when to perform a call to obtain a new access token, set a MEL expression for the attribute refreshTokenwhen in the oauth2:token-request element.

When a request authorization fails, the response contains an XML node named status with value ‘unauthorized’. In the previous example, the MEL expression evaluates that condition. When it evaluates to true, Mule sends a request to the Token URL to retrieve a new access token.

In the preceding examples, you authenticated a single user. You can handle access tokens for multiple users in a single application by defining a way to identify each user during the authorization period. During this period, you send a request to the Token URL to retrieve an access token and execute operations against the API with the acquired access token.

To identify which user is granting access to the Mule client app, define a MEL expression to retrieve a Resource Owner ID against the call to the local authorization URL.

On the Authentication tab, configure the options as follows for the OAuth2 - Authorization Code: In the Advanced section of the Authentication tab, set:

The field Resource Owner ID must be set with a MEL expression that allows each execution of the HTTP Request Connector to retrieve the RO identifier from the Mule Message. So on this example, whenever the HTTP Request Connector is executed, there must be a flow variable named ‘userId’ with the RO identifier to use. To create this variable, you can add a Variable transformer to your flow, positioned before the HTTP Request Connector, and configure the transformer to create the userId variable in the Mule Message.

The Local Authorization URI field (the one in the Advanced section), defines that in order to get the RO identifier, the userId query parameter must be parsed from the call done to the local authorization URL.

So if you hit http://localhost:8082/authorization?userId=john, then the RO john can grant access to the CA on his behalf. If you hit http://localhost:8082/authorization?userId=peter then the RO peter can grant access to the CA on his behalf.

Set resourceOwnerId to [flowVars.'userId'] and localAuthorizationUrlResourceOwnerId to [message.inboundProperties.'http.query.params'.userId]

The attribute resourceOwnerId must be set with a MEL expression that allows each http:request execution to retrieve the RO identifier from the Mule Message. So on this example, whenever the http:request is executed, there must be a flow variable named ‘userId’ with the RO identifier to use.

The attribute localAuthorizationUrlResourceOwnerId defines that, in order to get the RO identifier, the userId query parameter must be parsed from the call done to the local authorization URL.

So if you hit http://localhost:8082/authorization?userId=john, then the RO john can grant access to the CA on his behalf. If you hit http://localhost:8082/authorization?userId=peter then the RO peter can grant access to the CA on his behalf.

When you need to use HTTPS for the communication with the authentication server, typical in a production environment, apply HTTPS encoding to the OAuth credentials in all requests, including those done to:

By specifying a TLS context in your HTTP Request Connector authentication settings, this is handled in all of these requests.

On the Authentication tab, configure the options as follows for the OAuth2 - Authorization Code:

The TLS settings in the Authentication tab encode your OAuth credentials. The TLS/SSL tab of the HTTP Request Configuration encode the request body.

Set tlsContext-ref to reference a TLS context element, provide your trust store and key store credentials in this element.

The tlsContext-ref attribute of the oauth2:authorization-code-grant-type element is for encoding your OAuth credentials. The tls:context child element of the http:request-config is for encoding your request’s body.

Client credentials grant type is meant to be used by a CA to grant access to an application on behalf of itself, rather than on behalf of a RO (resource owner) in the OAS. To get an access token all you need is the application credentials.

You must include the following information:

When the mule application is deployed, it will try to retrieve an access token. If the app is not able to retrieve an access token, it will fail in the deployment.

The same behavior that applies to authorization code can be applied for client credentials grant type.

The same behavior that applies to authorization code can be applied for client credentials grant type.

Once you have a token manager associated with the authorization grant type (in the example below, with authorization code) we can use the oauthContext function in a MEL expression anywhere in your flow to access information from an OAuth authorization.

If you’re using client credentials or authorization code with a single RO, use the following function:

This function provides access to the OAuth authorization information from a token manager.

If you’re using authorization code with multiple RO , use the following function:

This function provides access to OAuth authorization information from a token manager.

When using a Token Manager, you can block a particular RO.

The Invalidate OAuth Context element cleans up all of the OAuth information stored in the token manager.

When using multiple RO with a single Token Manager, if you want to only clear the OAuth information of one RO, then you must specify the resource owner id in the Invalidate OAuth Context element.

By default, the token manager uses an in-memory object store to store the credentials. You can customize the token manager object store by using the objectStore-ref attribute. See how to configure a custom object store.