An OAuth2 Grant Selection Decision Tree for Securing REST APIs

OAuth2 protocol, grants, and guidelines for selecting grants

Imesh Gunaratne
Feb 18, 2018 · 9 min read

Abstract Protocol Workflow

Figure 1: OAuth2 Abstract Protocol Workflow

1. Client Credentials Grant

Figure 2: Client Credentials Grant Workflow
POST /token HTTP/1.1
     Host: server.example.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     Content-Type: application/x-www-form-urlencoded     grant_type=client_credentials
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "example_parameter":"example_value"
}
GET /example/resource HTTP/1.1
Host: server.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

2. Authorization Code Grant

Figure 3: Authorization Code Grant Workflow
GET /authorize?response_type=code
         &client_id=s6BhdRkqt3&state=xyz
         &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
               &state=xyz
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
     &code=SplxlOBeZQQYbYS6WxSbIA
     &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
   "example_parameter":"example_value"
}
GET /example/resource HTTP/1.1
Host: server.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

3. Implicit Grant

Figure 4: Implicit Grant Workflow
GET /authorize?response_type=token
        &client_id=s6BhdRkqt3
        &state=xyz
        &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com
HTTP/1.1 302 Found
Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA
               &state=xyz
               &token_type=example
               &expires_in=3600
GET /example/resource HTTP/1.1
Host: server.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

4. Resource Owner Password Credentials Grant

Figure 4: Resource Owner Password Credentials Grant Workflow
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe&password=A3ddj3w
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
   "example_parameter":"example_value"
}
GET /example/resource HTTP/1.1
Host: server.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Refresh Token Workflow

Figure 5: Refresh Token Workflow
POST /token HTTP/1.1
Host: server.example.com grant_type=refresh_token
&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVV
&client_secret=12312342342wefsdfsf3241334
&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Grant Selection Decision Tree

Figure 6: Grant Selection Decision Tree, Reference: https://alexbilbie.com/guide-to-oauth-2-grants/

Conclusion

References

Scalable

Industry best practices for implementing scalable enterprise applications

Imesh Gunaratne

Written by

Engineer at Google

Scalable

Scalable

Industry best practices for implementing scalable enterprise applications