OAuth2 Roles in WSO2 API Manager
The OAuth2 specification(RFC 6749) defines four roles as follows.
- Resource Owner
- Resource Server
- Client
- Authorization Server
Before explaining each what each of these roles does, let’s define the following.
2-legged OAuth
Two-legged OAuth processing involves three parties: OAuth client, authorization server, and resource server. The OAuth client can be either the resource owner or the trusted entity that knows about the credentials of the resource owner. In other words, two-legged OAuth processing does not involve additional resource owner interaction.
3-legged-OAuth
Three-legged OAuth processing involves four parties: resource owner, OAuth client, authorization server, and resource server. In other words, three-legged OAuth is a traditional pattern with resource owner interaction. In this case, a resource owner wants to give a client access to a server without sharing credentials.
References [1] , [2].
From the above explanation, we can derive that if Resource Owner does not participate in the authorization flow, it becomes two-legged and otherwise 3-legged.
The OAuth2 spec states 4 main grant types. All these grant types are supported by WSO2 API Manager.
- Authorization code
- Resource owner password
- Implicit
- Client Credentials
According to the definitions of three-legged and two-legged flows, the above grant types can be categorized as follows.
Two-Legged => Client Credentials, Resource Owner Password
Three-Legged => Authorization code, Implicit
Resource owner password grant type falling under two-legged flow might sound confusing for some of you(at least for me). But the idea is that the client already knows the resource owner’s credentials and does not need separate consent from him/her to access the resources during the token request flow.
Authorization code and Implicit grants need to get the Resource Owner involved during the flow because the resource owner needs to provide consent in order to access the resources on behalf of them. Therefore these become three-legged.
If the above explanations are clear, let's dive into how these roles are played in the WSO2 API Manager context.
The quoted texts are excerpts from the RFC document.
Client
An application making protected resource requests on behalf of the resource owner and with its authorization. The term "client" does not imply any particular implementation characteristics (e.g.,whether the application executes on a server, a desktop, or other devices).If you have a client id, client secret pair, you have an oauth2 client. In API Manager, you need to create an application in the store portal and then click on generate keys in order to generate a client id and secret pair. There can be two clients associated with a store application at a particular moment.
1) production client
2) sandbox client
Any token generated by the Authorization Server(key Manager) will be associated with one of the above client types.
Resource Owner
An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.There are various ways(Grant Types) a client can use to generate an oAuth2 token in WSO2 API Manager.
When a subscriber uses the Store UI to generate a token, the client credentials grant is used internally. In such a case, the token is generated on behalf of the client itself. There is no actual end-user associated with this token. Since the resource owner is not participating in this, this flow is two-legged. However, WSO2 associates this token to the owner of the client application. Hence in analytics charts all API calls done via a token generated with client credentials grant will be associated to the application owner.
For 3-legged authorization flows the resource owner will participate in the process. This user is the person who authorizes the client to call the resource server on behalf of them.
Authorization Server
The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.In WSO2 perspective, the component which is responsible for issuing tokens is the Key Manager. It will also be responsible for revoking/refreshing tokens as well.
One thing which could deceive you is that usually when the client needs to generate a new token, WSO2 recommends calling the token endpoint hosted in the gateway. Similarly, to revoke the token WSO2 recommends calling the revoke endpoint in the gateway. Therefore one could easily assume that the Gateway is the Authorization Server. But what happens behind the scenes is that the Gateway APIs will call the relevant endpoints in the Key Manager to generate/revoke the token. Gateway alone cannot generate/revoke tokens without a Key Manager.
If KM endpoints are called by bypassing the gateway, A cached token in the gateway will still continue to work even after revoking from KM.
Hence WSO2 recommends calling the respective endpoints in the gateway instead of KM.
Resource Server
The server hosting the protected resources, capable of accepting
and responding to protected resource requests using access tokens.In WSO2 API Manager, the generated access token will be used to call APIs deployed in the Gateway. This means Gateway is the server which is hosting the resources the client needs to access. This makes the Gateway the Resource Server.
Summary
The intention of this post is to clarify the OAuth2 roles in WSO2 API Manager context. Please leave a comment if you need to clarify anything else regarding this topic.
References
[1] https://www.ibm.com/support/knowledgecenter/en/SS9H2Y_7.7.0/com.ibm.dp.doc/oauth_twoleggedflow.html
