Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

OAuth V2

This page presents a detailed discussion of DevKit’s support for OAuth V2 authentication and how to implement a connector that uses OAuth V2 to authenticate with your API.

5-package

Assumptions

This document assumes you are familiar with the Anypoint Connector Essentials and you are ready to implement authentication on your connector. It assumes you are familiar with the various authentication methods and you are using OAuth V1 to authenticate with your API.

If you are not familiar with OAuth V1 authentication, what it is or how it works, we recommend visiting http://oauth.net/2/[OAuth 2.0 documentation]. 

Required API Information

From the service provider’s API documentation, obtain the precise values for the variables listed in the table below. These variables reference URLs employed during the authorization process; for details on these steps of the process, consult the http://tools.ietf.org/html/rfc6749[OAuth 2 specification].

Variable Description

accessTokenUrl

URL from which to obtain the access token

authorizationUrl

URL from which to obtain authorization to resource access

@OAuth2 Annotation

To implement OAuth V2 authentication on your Connector you need to use the @OAuth2 annotation on the @Connector class.

During the building process, a connector annotated with @OAuth2 gets two additional auto-generated @Processor methods called  authorize and unauthorize . These message processors are in charge of initiating and ending the OAuth session.

The following table describes all parameters for the @OAuth2 annotation.

Parameter Description Required? Default Value

accessTokenUrl

URL defined by the service provider to obtain an access token.

 

authorizationUrl

Defined by the service provider, the URL where the resource owner is redirected in order to grant authorization to the consumer. You can override this value when configuring the processor by setting a different value in the config element. When creating a flow, you can override this value by entering your desired value in the authorize element.

 

authorizationParameters

Comma-delimited list of annotations, in the form:

@OAuthAuthorizationParameter(name = "xxx", type = xxx, description = "xxx")

The type cannot be a collection or a complex type. See the Salesforce connector for an example.

 

verifierRegex

A Java regular expression to extract the verifier from the service provider response, after the resource owner authorizes the consumer.

code=([^&]+)

accessTokenRegex

A Java regular expression to extract the access token from the service provider response.

"access_token":"([^&]+?)"

expirationRegex

A Java regular expression to extract the expiration time of the access token (in seconds) from the service provider response. If this regular expression is not found in the service provider response (because the regular expression is wrong or the access token never expires), the access token will be treated as if it would never expire.

"expires_in":([^&]+?),

refreshTokenRegex

A Java regular expression to extract a refresh token from the callback during the authorization flow.

"\"refresh_token\":\"([^&]+?)\""

callbackPath

If the service provider only accepts a known redirect URL. Assign this parameter to the path inside your domain (denoted by the  fullDomain  environment variable) that will be registered with the service provider as a redirect URL. If left empty (meaning the service provider accepts any URL as redirect URL), Mule uses a random path.

<random path>

Adding @OAuth2 Annotation on the @Connector Class


         
      
1
2
3
4
5
6
7
8
@Connector(name = "oauth2connector")
@OAuth2(authorizationUrl = "http://someUrl", accessTokenUrl = "http://someOtherUrl")
public class MyConnector
{
    /**
    * YOUR CODE GOES HERE
    */
}

@Connector Class Properties

Your @Connector class needs OAuth-related @Configurable instance properties to allow the user to specify their consumer key and secret when using the connector:

  • @OAuthConsumerKey to hold the OAuth consumer key

  • @OAuthConsumerSecret to hold the OAuth consumer secret

Ensure these instance variables have public getters and setters (not shown).


          
       
1
2
@Configurable @OAuthConsumerKey private String consumerKey;
@Configurable @OAuthConsumerSecret private String consumerSecret;

@Processor Method Annotations

In the methods that access the protected resources (annotated with @Processor), add one String parameter and annotate it with @OAuthAccessToken.


          
       
1
2
3
4
5
6
7
@Processor
public Object accessProtectedResource(@OAuthAccessToken String accessToken, ...)
{
    /**
    * YOUR CODE GOES HERE
    */
}

When invoked, a method that contains parameters annotated with @OAuthAccessToken  initiates the following activities:

  1. The first time a protected resource is accessed, the user is redirected to the authorization URL of the service provider to grant or deny access for the consumer to the protected resource.

  2. During subsequent access requests, Mule includes the access token (contained within the parameters annotated with @OAuthAccessToken) in the request to the service provider. Refer to Oauth 2.0 specification for more details.

Access Token Expiration

If you have specified a proper regular expression (using the expirationRegex parameter for the @OAuth2 annotation), and an API’s access token expires, Anypoint DevKit automatically detects the expiration and, in such cases, it triggers the OAuth2 authorization flow again.

Client Class Changes: Passing the Access Token

The OAuth V2 support in Anypoint DevKit provides the support for OAuth2 at the @Connector class-level. However, the client class will probably have to include logic to actually pass the access token with the request when it calls the web service. Because OAuth2 is not a formalized and strict standard, the specifics of how access tokens are passed with requests will depend upon the implementation of the API. 

The API provider will provide sample code that illustrates how to pass tokens to their service. When implementing your client class, use the API provider’s sample code as a reference. 

For example, Foursquare supports OAuth 2.0 authentication, and expects the client to pass the access token as a query parameter. The OAuth 2.0 sample Foursquare connector, which implements an operation usersGetList, illustrates how to do this.

  • In the https://github.com/mulesoft/connector-documentation-oauth2-example/blob/master/src/main/java/org/mule/examples/oauth2connectorexample/Oauth2ExampleConnector.java[@Connector class OAuth2ExampleConnector] , the connector passes the accessToken as a parameter to the client class operation client.usersGetList():

    
                 
              
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    
    @OAuthProtected
    @Processor
    public UsersListResponse usersGetList(
        @Optional @Default("self") String userId, 
        @Optional @Default("") String group, 
        @Optional @Default("") String location)
      throws Oauth2ConnectorExampleTokenExpiredException,
             Oauth2ConnectorExampleException {
            return client.usersGetList(accessToken, userId, group, location);
        }
    ...
  • In the client class FourSquareClient, the method usersGetList() adds the accessToken query parameter to the Jersey WebResource wr before making the GET request :

    
                 
              
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    public UsersListResponse usersGetList(String accessToken, String userId, String group, String location)
                throws Oauth2ConnectorExampleTokenExpiredException, Oauth2ConnectorExampleException {
     
            logger.info("Calling usersGetList - AccessToken: " + accessToken);
     
            URI uri = UriBuilder.fromPath(apiUrl).path("/{apiVersion}/users/{USER_ID}/lists").build(apiVersion, userId);
            WebResource wr = jerseyClient.resource(uri);
     
     
            // Warning!... queryParam does not modify the current WebResource. Instead it returns a new instance.
            // So, if you do not assign the result WebResource to the one that makes the call, the param will never be added
            wr = wr.queryParam("oauth_token", accessToken);
     
    ....
             
        try {
                logger.info(wr.toString());        
                String res = wr.type(MediaType.APPLICATION_JSON_TYPE).get(String.class);
                logger.info("Response: " + res);
                result = jacksonMapper.readValue(res, UsersListResponse.class);
            }

Other services require similar changes at the client level, but differ in details, such as sending the token as a header. Also, this example illustrates the use of OAuth 2 with a RESTful web service using Jersey Client; for a SOAP-based web service, the client class changes will again be analogous, but the specifics will be different.

Using your OAuth2 Authenticated Connector

Authorizing the Connector

Before a consumer can execute any operation that requires authorization, the resource owner must grant access to the connector to access the protected resource. When it receives an authorization request, Mule redirects the resource owner’s browser to the service provider authorization page. Any subsequent attempts to access a protected resource fills the parameters annotated with @OAuthAccessToken. Mule includes the access token in the request to the service provider. See example below.


          
       
1
2
3
4
5
6
<linkedin:config apiKey="${api.key}" apiSecret="${api.secret}"/>
...
    <flow name="authorize">
        <http:inbound-endpoint host="localhost" port="8080" path="/authorize"/>
        <linkedin:authorize/>
    </flow>

Configuring your Connector

Configure the connector by passing the consumer key and consumer secret for your application as supplied by the service provider. The code sample below illustrates an example of such configuration.

<oauth2module:config apiKey="$\{api.key}" apiSecret="$\{api.secret}"/> …​ <flow name="sampleFlow"> <oauth2module:access-protected-resource /> </flow>

Configure a simple flow that accesses a protected resource. If the connector has not been authorized by OAuth, the consumer operation throws a NotAuthorizedException.

Customizing the Callback

When the user grants access to the protected resource, the service provider makes an HTTP callback.

The callback passes an authorization code that Mule uses later to obtain the access token. To handle the callback, Mule dynamically creates an HTTP inbound endpoint, then passes the endpoint’s URL to the service provider. Thus, you do not need to complete any specific configuration to make an HTTP callback.

By default, Mule uses a host and port (determined by the fullDomain environment variable and the http.port) to construct a URL to send to the service provider. Where you need to use non-default values for host and port, add the configuration as per the code example below. 


          
       
1
2
3
<oauth2module:config apiKey="${api.key}" apiSecret="${api.secret}">
<oauth2module:oauth-callback-config domain="SOME_DOMAIN" remotePort="SOME_PORT" />
</oauth2module:config>

For details on how Mule handles callbacks, see HTTP Callbacks.

Adding Secure Socket Layer (SSL)

When Mule automatically launches an HTTP inbound endpoint to handle the OAuth callback, it uses the HTTP connector by default. Where the service provider requires HTTPS, you can configure Mule to pass your own HTTPS connector (see example below).


          
       
1
2
3
4
5
6
7
8
9
...
 
<https:connector name="httpsConnector">
<https:tls-key-store path="keystore.jks" keyPassword="mule2012" storePassword="mule2012"/>
</https:connector>
...
<oauth2module:config apiKey="${api.key}" apiSecret="${api.secret}">
<oauth2module:oauth-callback-config domain="localhost" localPort="${http.port}" remotePort="${http.port}" async="true" connector-ref="httpsConnector"/>
</oauth2module:config> ...
For details on configuring an HTTPS connector, consult the HTTPS Transport Reference.

See Also