Almost anyone who uses Google, Facebook or other online services uses, perhaps not knowingly, also use OAUTH2. What exactly is OAUTH2, why should you care and how can you use it? We will use the WSO2 API Manager as a vehicle to explain OAUTH2.
The problem with keys
One of the problems with keys (yes, the ones you have in your purse or pocket) is that they open something. This sounds strange, but consider it from the point of view that you lose your keys. When someone knows where you live (or where your car is parked) they can have access to everything inside.
The digital equivalent is even more scarier. Consider your username / password as the keys to a digital service, for instance your Facebook profile. You would never give those credentials to anyone because it allows people to do everything within Facebook (we take any IP based location detection or other algorithms out of scope).
Yet, Login with google or Facebook to another site is quite handy. So if you do want to give access to services but not (potentially) lose all control, giving out an OAUTH2 token is the way to go.
OAUTH2 token
So what is it? An OAUTH2 token is a virtual key that gives access to something for a period of time. This period can be forever, a week, a day, an hour or even a couple of seconds.
IF this is too theoretic for you: An OAUTH2 token can be compared to the plastic hotel key with a chip or a magnetic stripe. As long as you pay for your room you have access. When you stop paying access is revoked and the plastic card that once opened your room is now worthless.
The key will offer access to the room but only as long as you are a guest (i.e. pay). It might even give access to a specific floor (the one with your room on it) but not other floors.
So an OAUTH2 token has not only a time element but often also a scope element. Depending on some external element you can access the gym (e.g. if you’re a member of the loyalty program).
OAUTH2 is an authorization framework that is standardized. The complete standard can be found here (warning: technical details).
Who is using OAUTH2
OAUTH2 tokens can grant access to a resource (an API for instance in the WSO2 API Manager). So your favorite API Manager is using it. But also Google, Facebook, PayPal and Linkedin. We could go on but you get the idea. One more thing, it is not only the big corporations that use it or potentially could use it.
How does OAUTH2 work?
It would go way to far to dive into the intricacies of OAUTH2. Let’s face it do you need to know everything about the combustion engine if you want to drive your car? It helps if you know some of the key elements like:
- It needs petrol (fuel)
- It needs oil (lubrication
- It needs sparks (ignition)
The equivalent of that in the world of OAUTH would be:
- Principles behind OAUTH
- CLIENT KEY & CLIENT SECRET
- GRANT TYPES
- SCOPES AND TIME
Principles behind OAUTH
OAUTH tokens work with a number of principles. Based on a so called client key and client secret an access token can be generated (with potential other parameters) that is used for validation and to grant or deny access to a resource.
Client Key and Client secret
OAUTH2 starts with a process that creates a so called client key and client secret. These two values are fixed and based on that subsequent access tokens are generated. As you can see from this screenshot of the WSO2 API Manager 2.0.0 the client key and client secret are long seemingly random strings of characters.
Grant types
The image below shows the grant types that are supported by OAUTH2:
- Refresh Token
- IWA-NTLM
- SAML2
- Client Credential
- Implicit
- Code
- Password
The client credential, refresh token and password grant types are most commonly used. For more information on the grant types please visit this link for a more in-depth description.
When we look further at this screen we can also see how we generate for instance an access token. In that case we hide the keys.
What we see here are two CURL commands that will generate an access token using either the password grant or the client credential grant. You can see that the consumer key and consumer secret are provided in a base64 encoding (see https://www.base64encode.org/ for more information). The key & secret are used as username/password of a Basic http authentication scheme (concatenate with “:” in between, b64 encode and pass in the Authorization: Basic” header
When we again show the keys you can see the curl command. Mind that the username and password need to be filled in when using the password grant type (an existing userid / password combination).The URL being called is the key manager of the API Manager which is responsible for the OAUTH2 tokens.
Scopes and time
The accesstoken can be generated with certain scopes. A scope defines a role or attribute that the owner needs to have in order to be granted access. It can also be used to differentiate between access given to the same service but on different devices. As you can see from this screenshot, the access token is a long string of characters (36) that is generated. The validity of the token is 3600 seconds but can be set to any value.
The curl command to try out the API (in this case) clearly shows the access token (6a31b etc). Without this token the API will not respond since it requires a valid token.
The scope is in this example not used. But, as an example, when you create a new API in the API Manager the required scope is apim:api_create. This scope is used and included when you generate an access token and will result in a correct access token.
Working with OAUTH2
In this case we use curl and the API Manager to generate tokens. This shows how it works and you can also include tokens in your
Is OAUTH2 here to stay?
For the moment the answer is yes. The mechanism of tokens is well established in the online world and as you learned has benefits like the possibility to revoke an access token and the fact that you remain control over the tokens, unlike a scenario where you give out userid and password.
Thanks to Gustavo Encarnacao for his review and comments.
If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
