Contact Free trial Login

OAuth2 Provider Module Reference

The OAuth2 Provider Module allows a Mule Application to be configured as an Authentication Manager in an OAuth2 Dance. With this role, the application will be able to authenticate previously registered clients, grant tokens, validate tokens, or register and delete clients, all during the execution of a flow.

  • The following documentation assumes a basic knowledge of the OAuth2 authorization protocol. If you are not familiar with this protocol, the RFC specification is available in RFC-6749.

  • If the app should behave as the Client in the OAuth2 Dance, then the OAuth Module should be used.

  • The API for this product is for testing purposes only with no guaranteed service level agreement.

Since the OAuth dance is done through HTTP, the OAuth2 Provider makes use of the Mule HTTP Connector.

As a consequence, apart from the definition of an OAuth2 provider configuration , the Mule application must also have an HTTP Listener configuration to be used by the provider.

Once configured, the provider works as follows:

Two HTTP endpoints are created for listening to Authentication Code and Token request as stated by the OAuth2 definition. Those work independently from the Mule application and respond via HTTP.

Apart from that, the provider defines an operation: Validate Token that can check if a token is authorized. That operation can be added anywhere in a flow to control it’s execution. If the token is indeed authorized, the flow will keep executing, setting token information in the payload, otherwise, a TOKEN_UNAUTHORIZED error will be raised. You need to add that operation in parts of the application that need token authorization.

Also, since token validation is almost always going to be used together with an HTTP Listener, in case it fails, the listener’s response mechanism can handle that error and properly respond to the requester. Additional logic can be added handling that type of error.

Lastly, additional operations are provided to add or delete clients and to revoke tokens if needed.

Configurations

General Configuration

 <oauth2-provider:config name="OAuth2Provider"
                         listenerConfig="httpListenerConfig"
                         resourceOwnerSecurityProvider="resourceOwnerSecurityProvider"
                         clientSecurityProvider="clientSecurityProvider"
                         supportedGrantTypes="AUTHORIZATION_CODE"
                         scopes="USER,ADMIN"
                         defaultScopes="USER"
                         clientStore="clientObjectStore">
         <oauth2-provider:client-validation-rate-limiter>
            <oauth2-provider:period-rate-limiter duration="600"
                                                 durationTimeUnit="SECONDS"
                                                 maximumFailureCount="5"/>
         </oauth2-provider:client-validation-rate-limiter>
         <oauth2-provider:token-config path="/token"
                                       tokenStore="tokenObjectStore"
                                       tokenTtl="86400"
                                       tokenTtlTimeUnit="SECONDS">
            <oauth2-provider:refresh-token-strategy>
                <oauth2-single-refresh-token objectStore="refreshTokenObjectStore"/>
            </oauth2-provider:refresh-token-strategy>
         </oauth2-provider:token-config>
         <oauth2-provider:authorization-config loginPage="static/auth.html"
                                               path="/authorize"
                                               objectStore="authorizationCodeObjectStore"/>
         <oauth2-provider:clients>
             <oauth2-provider:client clientId="clientId1"
                                     clientName="someClient"
                                     secret="clientSecret1"
                                     principal="clusr"
                                     description="Some test client"
                                     type="CONFIDENTIAL">
                 <oauth2-provider:client-redirect-uris>
                     <oauth2-provider:client-redirect-uri value="http://fake/redirect"/>
                 </oauth2-provider:client-redirect-uris>
                 <oauth2-provider:client-authorized-grant-types>
                     <oauth2-provider:client-authorized-grant-type value="AUTHORIZATION_CODE"/>
                 </oauth2-provider:client-authorized-grant-types>
                 <oauth2-provider:client-scopes>
                     <oauth2-provider:client-scope value="USER"/>
                 </oauth2-provider:client-scopes>
             </oauth2-provider:client>
         </oauth2-provider:clients>
     </oauth2-provider:config>

Parameters

Name Type Description Default Value Required

Name

String

The name for the OAuth2 Provider

 

x 

Provider Name

String

The name supplied to the customers of the API. This is used for some responses of the OAuth2 API.

Same as Name

 

Listener Config

String

The name of an HTTP Listener Config to reference, which handles the token and authorization endpoints.

 

x 

Resource Owner Security Provider

String

A reference to the Security Provider used to authenticate resource owners. Not needed if only CLIENT_CREDENTIALS grant type is used.

 

 

Client Security Provider

String

A reference to the Security Provider used to authenticate clients. Not needed if only public clients or private clients with secrets are used.

 

 

Token Generator Strategy

String

A reference to a Token Generator Strategy used to create the tokens that will be granted as access tokens.

Default strategy that will generate UUID encoded tokens.

 

Client Store

Object Store

A reference to a globally defined object store or a definition of a private object store. It’s used to store the registered clients information.

Object Store created by the Object Store Manager

 

Grant Types

String

A comma separated list of supported grant types. Possible values are: AUTHORIZATION_CODE,IMPLICIT,RESOURCE_OWNER_PASSWORD_CREDENTIALS or CLIENT_CREDENTIALS

AUTHORIZATION_CODE

 

Scopes

String

A comma separated list of supported scopes.

 

 

Default Scopes

String

A comma separated list of scopes to apply to clients if they don’t define their own.

 

 

Client Validation Rate Limiter

Client Validation Rate Limiter

Rate limiter to control access to validate client operations. It will control that failures calls within a certain period do not exceed a maximum count. After that number of failures is reached, further requests are rejected.

Period rate limiter with duration = 600 secs and maximum failure count = 5

 

Authorization Config

Authorization Config

Configuration related to authorization code handling.

 

 

Token Config

Token Config

Configuration related to token handling.

 

 

Security Providers

As seen in the General Configuration, two security providers should be defined in the application to be later referenced by the OAuth2 Configuration element.

One way of doing this is by using the Spring Framework, defining both security providers and then using the Spring Module to add them to the Mule Security Manager as so:

<spring:security-manager>
    <spring:delegate-security-provider name="clientSecurityProvider"
                                       delegate-ref="clientAuthenticationManager"/>
    <spring:delegate-security-provider name="resourceOwnerSecurityProvider"
                                       delegate-ref="resourceOwnerAuthenticationManager"/>
</spring:security-manager>

Client Validation Rate Limiter

Allows to configure a mechanism to prevent the continuous client validation when it’s using invalid credentials.

As for this moment, only a period-rate-limiter is implemented that handles rate limiting based on a time period.

Parameters

Name Type Description Default Value Required

Duration

Number

The time to wait before resetting the rate limiter. That means that during time intervals of duration length, every time a client validation fails, it will be added to the failure count.

600

 

Duration Time Unit

Time Unit

The time unit for the duration attribute.

SECONDS

 

Maximum Failure Count

Number

Maximum number of failures allowed within the period before preemptively rejecting requests.

5

 

Authorization Code Configuration

Configuration related to authorization code handling and the authorization endpoint.

Parameters

Name Type Description Default Value Required

Login Page

String

Relative file path to the web page for the resource owner to provide its credentials.
Keep in mind that if the default page is not used, you need to handle any external files referenced in the configured HTML. They will not be handled by the OAuth provider.
For example, if the login page HTML references an external .css style file, an endpoint that provides that file must exist. See http:load-static-resource.

www-static/auth.html

 

Path

String

The URL relative path to the authorization endpoint in the HTTP server for listening to authorization requests.

/authorize

 

Authorization Code Store

Object Store

A reference to a globally defined object store or a definition of a private object store. It’s used to store generated authorization codes.

A persistent object store created from the ObjectStoreManager with an entry TTL of 600 SECONDS.

 

Token Configuration

Configuration related to token handling and the token endpoint.

Parameters

Name Type Description Default Value Required

Path

String

The URL relative path to the token endpoint in the HTTP server for listening to token requests.

/token

 

Token Store

Object Store

A reference to a globally defined object store or a definition of a private object store for storing generated tokens.

A persistent object store with an entry TTL of 86400 SECONDS.

 

Token Ttl

Number

The time for a granted token to be considered valid after granting it. The value should be the same as the entryTtl of the token store if a custom one is configured.

86400

 

Token Ttl Time Unit

Time Unit

The Time Unit to use for the token TTL. It should be the same as the entryTtlTimeUnit of the token store if a custom one was configured.

SECONDS

 

Refresh Token Strategy

Refresh Token Strategy

Configures how refresh tokens should be handled in every refresh token request.

No Refresh Token

 

Refresh Token Strategy

The refresh token strategy configures how refresh tokens are granted and how they should be handled every time a refresh token request is executed.

No Refresh Token

There will be no refresh token granted with every access token. As a consequence, when a refresh token request comes, it will always be rejected.

Single Refresh Token

For every new access token that is granted, a single refresh token will be associated with it. That same refresh token should be used every time the access token is refreshed.

Parameters
Name Type Description Default Value Required

Object Store

Object Store

A reference to a globally defined object store or a definition of a private object store for storing generated refresh tokens.

A persistent object store created from the ObjectStoreManager with an entry TTL of 86400 SECONDS

 

Multiple Refresh Token

A new refresh token will be generated every time a refresh token request is executed. After that, the previous refresh token will be invalidated.

Parameters
Name Type Description Default Value Required

Object Store

Object Store

A reference to a globally defined object store or a definition of a private object store, which stores the generated refresh tokens.

A persistent object store created from the ObjectStoreManager with an entry TTL of 86400 seconds.

 

Clients

<oauth2-provider:clients>
    <oauth2-provider:client clientId="clientId1"
                            clientName="someClient"
                            secret="clientSecret1"
                            principal="clusr"
                            description="Some test client"
                            type="CONFIDENTIAL">
        <oauth2-provider:client-redirect-uris>
            <oauth2-provider:client-redirect-uri value="http://fake/redirect"/>
        </oauth2-provider:client-redirect-uris>
        <oauth2-provider:client-authorized-grant-types>
            <oauth2-provider:client-authorized-grant-type value="AUTHORIZATION_CODE"/>
        </oauth2-provider:client-authorized-grant-types>
        <oauth2-provider:client-scopes>
            <oauth2-provider:client-scope value="USER"/>
        </oauth2-provider:client-scopes>
    </oauth2-provider:client>
</oauth2-provider:clients>

All the registered clients that are authorized to request tokens. The list can be modified in runtime by the Create Client and Delete Client operations.

Each registered client will have an entry with the following information.

Parameters

Name Type Description Default Value Required

Config

String

The name of a globally defined OAuth Provider configuration to use for token validation.

 

x 

Client Id

String

The Id to assign to the created client

 

x 

Client Name

String

The client friendly name

 

 

Principal

String

For some security providers, the clientId can’t be used for the client username. In those cases, the client’s principal is used for authentication.

 

 

Description

String

A short description of a client.

 

 

Type

Client Type

The type of the client. Allowed values are PUBLIC (Clients incapable of maintaining the confidentiality of their credentials) or CONFIDENTIAL (Clients capable of maintaining the confidentiality of their credentials).

PUBLIC

 

Secret

String

The client’s secret (password) used for authentication.

 

Only if the client type is CONFIDENTIAL.

Client Redirect Uris

Redirect Uri

One or multiple redirect URIs to use for the client’s requests

Empty List

 

Client Authorized Grant Types

Authorized Grant Type

Authorized grant types to allow for the client. Valid values are: AUTHORIZATION_CODE,REFRESH_TOKEN, TOKEN, PASSWORD, CLIENT_CREDENTIALS.

Empty List

 

Client Scopes

Client Scope

One or multiple client scopes for which the client requests tokens. If none are provided, the default scopes of the General Configuration are used.

Empty List

 

Keep in mind that for Client Redirect Uris, Client Authorized Grant Types or Client Scopes, each new value should be given in a new XML tag as shown in the example below:

<oauth2-provider:client-redirect-uri value="http://fake/redirect"/>

<oauth2-provider:client-authorized-grant-type value="AUTHORIZATION_CODE"/>

<oauth2-provider:client-scope value="USER"/>

Operations

Validate Token

<oauth2-provider:validate-token config="OAuthProviderConfiguration"
                                token="#[vars.accessToken]"
                                scopes="#[vars.scopes]"
                                resourceOwnerRoles=#[vars.resourceOwnerRoles]/>

Validates that the given token was granted and is in a valid state. Also, if defined, checks that the token scopes or resource owner roles match the provided ones.

If the token provided is valid then the operation will set the payload as a JSON with the following information.

Key Value Always

expires_in

Time remaining for the token to be considered invalid, in seconds.

yes

scope

Space separated scopes associated with the token.

yes

client_id

ID of the client that requested this token.

only if present

username

Username of the resource owner that authorized this token to be requested.

only if present

To preserve the payload set before executing the operation, the attributes target and targetValue can be used to set this JSON information in a variable instead of overwriting the payload.

Parameters

Name Type Description Default Value Required

Config

String

The name of a globally defined OAuth Provider configuration to use for token validation.

 

x 

Token

Expression

The expression that resolves to the token to validate. The default location to look for the token is in the first value of the 'authorization' HTTP header,

#[(attributes.headers['authorization'] splitBy ' ')[1]]

 

Scopes

Expression

An expression that resolves to a list of scopes to enforce when validating the token.

Empty List

 

Resource Owner Roles

Expression

An expression that resolves to a list of resource owner roles to enforce when validating the token.

Empty List

 

Raises

OAUTH2-PROVIDER:TOKEN_UNAUTHORIZED(OAUTH_SERVER_SECURITY)

  When the token being validated is not valid.

Revoke Token

<oauth2-provider:revoke-token  config="OAuthProviderConfiguration"
                               token="#[vars.token]"/>

Revokes an existing access token and the associated refresh token. Either of them can be provided to revoke both.

Parameters

Name Type Description Default Value Required

Config

String

The name of a globally defined OAuth Provider configuration to use for token validation.

 

x 

Token

String

Token to be revoked

 

x 

Raises

OAUTH2-PROVIDER:INVALID_TOKEN(OAUTH_SERVER_SECURITY)

  When the token to be revoked is not a valid one.

Create Client

<oauth2-provider:create-client config="OAuthProviderConfiguration"
                               clientId="#[payload.clientId]"
                               clientName="#[payload.clientName]"
                               principal="#[payload.clientPrincipal]"
                               description="#[payload.clientDescription]"
                               type="#[payload.clientType]"
                               secret="#[payload.clientSecret]"
                               redirectUris="#[payload.redirectUris]"
                               authorizedGrantType="#[payload.authorizedGrantTypes]"
                               scopes="#[payload.scopes]"
                               failIfPresent="false"/>

Parameters

Name Type Description Default Value Required

Config

String

The name of a globally defined OAuth Provider configuration to use for token validation.

 

x 

Client Id

String

The Id to assign to the created client

 

x 

Client Name

String

The client friendly name

 

 

Principal

String

For some security providers, the clientId can’t be used for the client username. In those cases, the client’s principal is used for authentication.

 

 

Description

String

A short description of a client

 

 

Type

Client Type

The type of the client. Allowed values are PUBLIC (Clients incapable of maintaining the confidentiality of their credentials) or CONFIDENTIAL (Clients capable of maintaining the confidentiality of their credentials).

PUBLIC

 

Secret

String

The client’s secret (password) used for authentication.

 

Only if the client type is CONFIDENTIAL

Redirect Uris

Expression

An expression that resolves to a list of redirect uris used for when the client makes requests to the OAuth Provider.

Empty List

 

Authorized Grant Types

Expression

An expression that resolves to a list of the authorized grant types that the client can use to request a token. Valid values are: AUTHORIZATION_CODE,REFRESH_TOKEN, TOKEN, PASSWORD, CLIENT_CREDENTIALS.

Empty List

 

Scopes

Expression

An expression that resolves to a list of supported scopes by the client. If none provided, the default scopes of the General Configuration will be used.

Empty List

 

Fail if Present

Boolean

Defines what to do if the a client with the same ID is already registered. If true, an error will be raised. Otherwise, the client will be updated.

false

 

Raises

  • OAUTH2-PROVIDER:CLIENT_ALREADY_EXISTS(OAUTH_SERVER_SECURITY)

      If a client already exists with the same client ID, and the flag: failIfPresent is set to true.

  • INVALID_CONFIGURATION

      If the provided parameters are not valid, as having an authorizationGrantType of AUTHORIZATION_CODE and no redirect URI.

Delete Client

Deletes the client with the given ID. As a consequence, any new request that comes from the deleted client will be rejected and tokens granted to that client will no longer be valid.

Parameters

Name Type Description Default Value Required

Config

String

The name of a globally defined OAuth Provider configuration to use for token validation.

 

x 

Client Id

String

The ID of the client to be deleted.

 

x  

Raises

OAUTH2-PROVIDER:NO_SUCH_CLIENT(OAUTH_SERVER_SECURITY)

  If the client to be deleted does not exist.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub