OAuth 2.0 with WSO2 Identity Server

The OAuth2.0 authorization delegation protocol has gained wide attraction among the API communities for its ease of implementation compared to OAuth1.0a which involves signatures. It provides specific authorization flows (grant types in OAuth2.0 terms) for web applications, mobile and native applications and browser based clients.

The WSO2 Identity Server has the capability to function as an OAuth2.0 Authorization server. It also supports OAuth1.0a but in this post I will only be talking about OAuth2.0 support.

One of the popular products from WSO2 is the WSO2 API Manager. This product uses the same OAuth2.0 feature from the WSO2 Identity Server (enabled by the componentized architecture of Carbon platform powered by OSGi).

The OAuth2.0 core specification defines 4 authorization grant types for 4 different use cases.

1. Authorization Code grant type

The OAuth1.0a core specification talks about only one type of authorization flow mainly, which is the 3-legged flow. Authorization Code grant type is pretty much the evolution of OAuth1.0a which eliminates the need for signatures and relies solely on transport layer security such as SSL. This is a 3-legged flow and is the recommended and dominantly used flow for web applications. This flow involves two separate requests. First to the authorization endpoint and secondly to the token endpoint. In the authorization endpoint the resource owner authenticates himself and authorizes the client for a specific scope for a specific time period. The authorization server would respond with an authorization code to a callback URL specified by the client. In the second step the client would authenticate himself to the token endpoint and exchange the authorization code to an access token.

2. Implicit grant type

This  grant type has only one request. That is the request to the authorization endpoint. The resource owner as in the previous grant type would authenticate himself at the authorization endpoint. However the second step in the previous request does not take place here, which is the authentication of the client. Therefore the clients that use this grant type are known as public or anonymous clients because they don’t authenticate themselves. This grant type is defined in case of clients that live on the browser such as JavaScript clients. Here the clients credentials are kept in the browser, therefore can be seen by the resource owner or anyone who has got access to the browser session. Hence the the clients credentials are not confidential anymore and authentication does not make sense. However the client_id must be sent which can be used for throttling and monitoring (SLA) purposes. This grant type should be used with care, at the discretion of the Authorization server.

3. Resource Owner Password Credentials grant type

This grant type again has only one request. But this one talks to the token endpoint. Here the resource owner would need to provide his credentials to the client and the client would send those credentials and his own credentials to the token endpoint and authenticate both parties with their respective credentials and get back the access token. This type of grant is useful in scenarios where there is no browsers involved such as mobile apps or Desktop apps. Again this type of grant should be allowed at the discretion of the authorization server, suitably for reasons such as if the client is not able to take advantage of the browser and the clients are generally trusted parties and are certified to be trusted by the resource owners.

4. Client Credentials grant type

This grant is the most simplest grant type available. In this case the client directly sends an access token request to the token endpoint with his credentials. There is no resource owner credentials involved here. I.e. the resource owners do not authenticate themselves or authorize clients. This grant type is generally used in cases where the resources are public or else if the client is accessing resources owned by himself. So why do we need an authentication scheme at all if the resources are public? Or why do we need OAuth2.0 instead of HTTP Basic Auth if the client is accessing his own resources? Well, the answer for the first question is to impose SLAs and do monitoring, metering and billing. The answer for the second question is that the OAuth2.0 model has some inherent advantages not found with HTTP Basic Auth. Mainly the client credentials are exchanged for an access token which is used thereafter and the client’s credentials can be safely discarded until the access token expires. Therefore the frequency at which the client’s credential is required is reduced. Also the scope and lifetime of access given to the access token can be controlled unlike giving away the credentials which means if the credentials are compromised the masqueraders who obtain the credentials have complete authority over the user’s account until such time the legitimate user comes to know this and changes his credentials at the authorization server. But even that might be too late if the masquerader has already changed the password of that account. In such a case the consequences can be devastating.

Once an access token is obtained regardless of the grant type used resource access is the same from the client’s perspective. The client would send a resource request with the access token to the resource server. The request path would ideally be intercepted by an entity which will validate the access token with the authorization server and decide whether to let the request to continue or not. How the access token validation happens between the authorization server and resource server is implementation specific of the authorization server which OAuth2.0 does not talk about. The WSO2 Identity Server currently exposes a SOAP endpoint for this purpose. The WSO2 API Manager provides a SOAP endpoint as well as a Thrift endpoint for this purpose.

The OAuth2.0 specification has provisions for extensions at many places. The authorization grants and access tokens types are two main examples. One of the earliest grant type additions to the OAuth2.0 specification is the “SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants”. Although this is still at a draft stage we can see all the major players in the industry adopting this standard mostly with some level of customization. The WSO2 Identity Server also has support for this since its 4.1.0 release. I have talked about this support here. Another such extension grant type which is also at a draft stage is the “JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants”. There are two major access token types that have been widely adopted in the industry; the “Bearer Token” (an IETF standard) and the “OAuth 2.0 Message Authentication Code (MAC) Tokens” (an IETF draft). The WSO2 Identity Server currently supports only the Bearer Token profile. For someone who wants an alternative for accessing resources with signatures, there is a customization available here.

Another complement to the OAuth2.0 specification is the “OAuth 2.0 Token Revocation” draft. The WSO2 Identity Server supports this draft as well from its 4.1.0 release, and you can read about it here.

The OAuth Bible is a comprehensive compilation of OAuth1.0a and 2.0 terminology and all their major flows.

OAuth Token Revocation with WSO2 Identity Server

The OAuth Token Revocation functionality is available with WSO2 Identity Server 4.1.0. The OAuth Token Revocation implementation follows the specification here. There are two endpoints exposed from the token revocation feature.

1. REST endpoint at /oauth2endpoints/revoke

2. SOAP endpoint at /services/OAuthAdminService with operation revokeAuthzForAppsByResourceOwner

The REST endpoint is for OAuth2.0 clients who want to revoke any access granted to them by a resource owner. This could be at the discretion of the resource owner or otherwise. In other words this endpoint is meant for OAuth2.0 clients only, to authenticate themselves using client_id and client_secret and revoke the authorization granted to them. They may use the access token or refresh token for this purpose. Whichever token the client uses the result is the same; the client cannot access the user’s resource again until such time the user explicitly provides his grant by authorizing the client at the OAuth2.0 authorization server.

Following is an example of the request that needs to be sent to the revocation REST endpoint by OAuth2.0 client to revoke a token:

curl -X POST --basic -u "4xTplVAiQEwrBF6wYSW3cpyqYDoa:GREoG5f80kmg7uHNed2YwfJSxlQa" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "token=d23e96c9bf2818fe5b4db0f8dbe829bb&token_type_hint=access_token" https://localhost:9443/oauth2endpoints/revoke

The token parameter used here can be an access token or refresh token. The token_type_hint parameter is optional. This parameter can take values access_token or refresh_token. The Identity Server will use this parameter to speed up the process of looking up the token by searching first in the set of tokens the client specifies (access_token or refresh_token). If the token is not to be found in the set the client claims it to be in, then the server will look for the token in the other set (refresh_token or access_token).

The SOAP endpoint on the other hand is for the resource owners to directly interact with the Authorization server and revoke authorization grants for applications they previously granted access to, without the OAuth2.0 application/client being an intermediary in the process. The use of this SOAP endpoint is demonstrated by the WSO2 Identity Server’s management console at Configure’ -> My Authorized Apps‘ for resource owners to login and revoke application authorization.

Following is a screen shot of the ‘My Authorized Apps’ page at an instance when the user ‘ResourceOwner’ has granted authorization to the application ‘Playground2.0’ created by user ‘AppDev’.

Application 'Playground2.0' created by user 'AppDev' granted authorization by user 'ResourceOwner'

Application ‘Playground2.0’ created by user ‘AppDev’ granted authorization by user ‘ResourceOwner’

The token revocation end-point also supports CORS (Cross-Origin Resource Sharing) specification and also JSONP (Remote JSON – JSONP).

CORS is supported through CORS-Filter which can be found here. The CORS Filter is designed to be plugged to a webapp using its deployment descriptor (web.xml). Since the OAuth2.0 endpoints in WSO2 Identity Server have been written as JAX-RS endpoints you can add the required CORS configurations to its deployment descriptor. You can find this webapp at <WSO2_IS_HOME>/repository/deployment/server/webapps/oauth2endpoints.war. Rather than editing the web.xml directly in the deployed directory, its easier to copy the oauth2endpoints.war file into another location, edit the web.xml and copy it back into the webapps folder and it will get hot deployed.

Example of a JSONP revocation request:

curl -X POST --basic -u "4xTplVAiQEwrBF6wYSW3cpyqYDoa:GREoG5f80kmg7uHNed2YwfJSxlQa" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "token=d23e96c9bf2818fe5b4db0f8dbe829bb&token_type_hint=access_token&callback=package.myCallback" https://localhost:9443/oauth2endpoints/revoke

The callback parameter is optional.