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

Mule Secure Token Service Oauth 2.0 Provider

The Mule Oauth 2.0 Secure Token Service functionality on CloudHub is limited due to the known Object Store limitations.

If those limitations don’t affect your development, you can use the Mule Oauth 2.0 Secure Token Service on Cloudhub.
Otherwise, you need to create your own Object Store and configure the OAuth2 module to use your custom Object Store instead of the default.
For further guidance visit the MuleSoft Customer Portal and open a ticket.

Overview of Oauth 2.0

Oauth 2.0 (Open standard for Authorization) is a method of allowing an application to have limited access to a protected resource via a 3rd-party Web service. In other words, OAuth provides a secure way for a Web service to gain limited, temporary access to a resource, such as a user account, via another Web service.

Use Mule Secure Token Service to apply Oauth 2.0 to your Web service provider to:

  • grant consumers of your Web service limited access to secure data

  • avoid disclosing an end user’s access credentials to a Web service consumer

  • retain the authority to revoke the consumer’s access to an end user’s secure data at any time

To better understand how OAuth works, we must first define the entities involved.

Access Credentials

information one needs to access an asset, such as username and password

Resource Owner

a person or system that owns the protected resource and credentials needed to access the resource

Protected Resource

data which a Consumer wishes to use, to which only the resource owner has access via the access credentials

Service Provider

an application or system which stores the protected resource; issues tokens to the Consumer after authenticating the resource owner and confirming authorization to access data

Consumer (Client)

a 3rd-party application or system that needs to use the protected resource

Authorization Code

a code issued by the Service Provider after confirming the identification of a registered Consumer; exchanged with Service Provider during OAuth dance to acquire a Token


authorization that a Service Provider gives to a Consumer to use the protected resource; (the token does not contain the protected resource or access credentials)

Refresh Token

credentials that a Service Provider issues to a Consumer to obtain access to a protected resource again when the original Token expires or becomes invalid; (facilitates access to the protected resource without performing the whole dance again)


an identifier in the token that defines the specific data to which the consumer has access

Adding OAuth to an online interaction is like giving a parking attendant the valet key to your rental car. You don’t want the parking attendant to access the laptop you have stored in your trunk, but you do want him to park your car for you (limited use of the protected resource). As the resource owner, you could give the attendant your car key (access credentials) to park your car, but with the key, he could also open the trunk and take your laptop. Luckily, the car rental company (the service provider) provided a valet key (token) that will enable the attendant to start the car (scope), but will not allow him to access the trunk.

Access Credentials

car key

Resource Owner


Protected Resource


Service Provider

rental car company


parking attendant


valet key


ability to drive the car, but not access the trunk

In the online world, adding OAuth to an online activity gives a Web service permission to use some of the information in an online private account an end user maintains with another Web service. For example, say you have just discovered a new website that issues online invitations for events. You are anxious to use this service for your upcoming party for 100 friends, but you do not want to enter the email addresses of 100 invitees into the online invitation website. You have already entered them into your online address book on another website. Luckily, the invitation website can use OAuth to solve the problem.

Because it wants to make your life easier, the invitation website gives you the option of importing all your contacts from another website. You (resource owner) can click a button to access your account (protected resource) on the daily planner website. When you click the button, the invitation website (consumer) directs you to login page for the daily planner website (service provider). You enter your username and password (access credentials) to access your account (protected resource). After you log in, the daily planner website provides the invitation website with a token that allows the invitation website to import all of your contacts (scope), yet do nothing more (for example, it cannot change your password or access the personal calendar you have stored in the same account). The interaction between Consumer and Service provider in this context is referred to as the OAuth dance (see figure below).

+ OAuth_dance

Access Credentials

your username and password to your account on the daily planner website

Resource Owner


Protected Resource

your account on the daily planner website

Service Provider

daily planner website


invitation website




access to the address book, only

The OAuth Dance

The example above briefly describes the OAuth dance between client, provider and resource owner. The list below describes the sequential steps in an OAuth dance which employs the Authorization Code grant type. (For a graphical illustration of the dance steps, see the Mule STS Oauth 2.0 Example Application.)

  1. Client app submits a request to the service provider to become a registered client.

  2. Service provider evaluates the client request, then, if approved creates a client ID and client secret (if the client identifies itself as CONFIDENTIAL ) for the client app, which it stores in a list of registered clients, and sends to the client app.  (If the client identifies itself as PUBLIC, the service provider issues only a client ID, but no client secret.)

  3. Client app wants to use data (protected resource) housed by service provider, so initiates a request to access the data to the service provider.

  4. Client app calls the service provider’s authorization server, providing client ID to confirm that it is a registered client of the Service Provider.

  5. Client app, using a login page supplied by the service provider, asks that the resource owner use the access credentials to authenticate themselves to the service provider.

  6. After confirming that the client ID is valid (i.e. the client app has previously registered with the service provider), and authenticating the resource owner via login credentials, the service provider returns an authorization code.

  7. Client app calls the service provider’s authorization server again, providing its authorization code, client ID (again), and client secret.

  8. Service provider returns a token in which it specifies the scope.

  9. Client app calls the service provider’s resource server, providing the token, to request the protected resource (data).

  10. Service provider delivers the protected resource.

Configuring Oauth 2.0 on a Mule Web Service Provider

Whenever you wish to expose a Web service protected with Oauth 2.0 security, you must insert an OAuth Provider and a Global OAuth Provider into your Mule Application. The Creating an Oauth 2.0 Web Service Provider document describes how to build a Web service protected by Oauth 2.0.

Configuring Oauth 2.0 on a Mule Web Service Consumer

Whenever you wish to connect your Web service client to an API which uses Oauth 2.0 security, you must comply with the provider’s mandate and add Oauth 2.0 security to your Web service client. (Access the Web service provider’s documentation to determine whether it demands the use of Oauth 2.0.)

Apply Oauth 2.0 to your Web service client to access a Web service that mandates the use of OAuth. This enables you to:

  • leverage an end user’s secure asset with a Web service provider by requesting, and temporarily gaining restricted access to, the asset

  • avoid acquiring a resource owner’s protected resources

Use an Anypoint Connector (several are included in the out-of-the-box Mule ESB distribution) in your Mule flow to consume a Web service. Alternatively, use DevKit to build a customized connector that will enable you to connect with, and consume, the Web service of an external service provider.

Next Steps

  1. Examine the Mule STS Oauth 2.0 Example Application which illustrates how to add Oauth 2.0 to a Web service provider in Mule.

  2. Learn more about Authorization Grant Types.