OAuth2 Introduction

OAuth2 Introduction

OAuth2 is an authorization framework which enables a third-party application to aquire limited access to an protected resource, on behalf of a resource owner.The main advantage of Auth2 is resource owner do not need to divulge his login credentials to the third-party in order to access resources.

Notice that OAuth2 is all about authorization(what you can do) but not authentication(who you are). Most of the Authorization servers expose API's to get identity information of the user after followed authorization process.
i.e facebook Authorization server expose graph API to get identity information of user who has the access token, retrived by following authorization process(OAuth2).

Problem

Imagine you found a app that connects to email server and lets you to schedule emails. You have email account on the email server and emails have protected by user name and password. Now in order to access email server on behalf of you app needs your credentials. Before you share your credentials with app,

1.Do you trust the app to share your credentials ?
2.What if this app is hacked?
3.what if this app misuse your credentials to send some spam emails?

This is where OAuth2 to comes into play

OAuth2 Roles

• Resource owner : The resource owner is the user who authorize client to access his protected resources. (In this example "you")
• Resource server : Server that hosting protected data. This server needs some kind of authorization before it serve up protected resources (i.e email server)
• Client : Also called "the app". Client is the application that wants to access the user's protected resource. (i.e email schedule app)
• Authorization Server :The resource server has the resource owner user accounts, verify the identity of user and then issue access tokens to client. 

OAuth2  Endpoints

1. Authorization Endpoint 

Oauth2 defines following set of endpointsEndpoint on a Authorization server where resource owner logs in and grant authorization to client app.

GET /authorize

Input query parameters

• state
• scope
• response_type
• clientId
• redirect_uri
  

Output

• Authorization code (for authorization code grant) 
• Access Token (for implicit grant)

2. Token Endpoint

Endpoint on a Authorization server where client can exchange the authorization code, client ID and client secret, for an access token and refresh token.(client ID and client secret will generated by authorization server in the process of client registration)

POST /token
Authorization: Basic {client_id}:{client_secret}

Input query parameters

• grant_type
• code
• client_id
• redirect_uri  

 Output

• Access token
• Refresh token
  

3. Redirection Endpoint

 Endpoint on a client application where the resource owner is redirected after interact with Authorization Endpoint.
 
GET /redirect_uri


Input query parameters

• state 
• scope
• code

4. Resource Endpoint

Endpoint on a resource server which allows to access protected resources.

/api
Authorization: Bearer {access_token}

5.Verify (Non standardized)

 Endpoint on a Authorization server where resource server can validate tokens. Only internally accessible by resource server.

OAuth2 flows

Now with the knowledge of auth roles and endpoints let look at the general flow of the oauth and how these roles interact with others.

 

 1. Client send the authorization request to the authorization server asking for permission to access protected resources. Usually this is done by accessing authorization endpoint by setting scope parameter to the type of resources that client needs to be accessed.

2. User(resource owner) is redirected to authorization server's login page .

3. Now user needs to rely on the authorization server and needs to send credentials in order to authenticate himself.

4. After the user authentication process successful, authorization server send back access token to the client. access token is nothing more set of characters only meaningful in authorization server.

5. Now client can send requests to resource server asking protected resources by providing access token along with all requests.

6. But resource server does not know whether this access token is valid or not. Only authorization server knows. So resource server send this token to authorization server in order to validate.

7. Authorization server checks the validity and the permissions associate with this token and returns the status to resource server.

8. If everything ok then resource server returns protected resource to the client.

What are OAuth2 grant types?

The auth2 spec describes number of different paths or interactions (calls grants) that client can aquire an access token. Each grant type has advantages/disadvangtages an you will need to choose on based on your requirement.

1. Authorization code grant

Considered most secured grant type because client never see user's username or password for access the resource server. Since three roles works together in order to access resource server this grant also called as "three-legged" oauth. Typically used by clients who CAN securely store client id, client secret and tokens.

1. Use /authorization endpoint to send auth request with relavant parameters.
(scope= what type of information requesting, client_id=xxx, etc ...)

2. Resource owner will be redirect to the authorization server's login page.

3. Resource owner send his credentials to authorization server in order to authentication.

4. On successfully login resource owner will be redirected to consent page which shows all the information( that client requested in scope parameter of authorization request) that client is going to access.

\

5. Resource owner accept to share these information with client.

6. Returns authorization code to client. 

7. Client call /token endpoint along with authorization code

8. /token endpoint returns tokens and expiration time(access token, refresh token)

9. Client request resource from  /api (resource endpoint) along with the access token.

10. Resource server validate access token with authorization server.

11. Returns access token validation results back.

12. Returns requested resources if access token valid.

 Implicit Grant

Implicit grant is a simplication of Authorization code grant. As you can see in below diagram it does not use token endpoint and not return refresh tokens. Typically used by client who does NOT have secure storage for store  client secret and tokens.

 

Note that in this grant in step 6 /auth endpoint returns access token (not refresh token). But the rest of the steps same as in authorization code grant.

Client credential grant

Use where resource owner and client are same. So only client is authenticate by using client id and client secret at step 7.

At step 8 auth server returns access token and refresh token. The rest steps are same as in authorization code grant. But client needs to provide secure storage for tokens and client secret.

Resource owner password credentials grant

If the resource owner willing/trust to share his credentials with client this grant type can be used. So client should NOT store his credentials. They should be only use to access token endpoint and get the access/refresh tokens (step 7). Only these tokens should be stored by client.