Apendix B - OAuth2 Grant Types

Authorization Code

The authorization code grant type is intended for web server applications using a server side programming language such as PHP or Python where the source code of the application is not available to the public – hence protecting the client secret.

The use case for this grant type is to allow a user of the web server application to grant access to all or some of their data to a 3rd party application. A real world example of this could a social network application requesting access to a user’s photos on a photo sharing web site. The photo sharing web site is able to expose their user profiles and data (photos) through an OAuth2 application on their platform whilst not exposing their client secret in the process.

The following diagram shows the transaction flow of the Authorization code grant type.

1. Redirect the user browser to Authorization Server.

• Includes response_type=code, client_id, redirect_uri, scope, state

2. User authenticates and grants authorization to the 3rd party App.

• User submits their credentials for the Authorization Server

3. Authorization Server now redirects back to the web application (redirect URI) including the authorization code

• Includes authorization code, state

4. Web application verifies the redirect and sends request to exchange the authorization code for an access token (query param & post body supported)

• Includes response_type=authorization_code, code, client_id, client_secret, redirect_uri

5. Authorization Server returns access token for use in subsequent API calls

• Includes access_token, expiry time, token_type=bearer, refresh_token

6. Web application includes access token in the HTTP Authorization header.

• Includes Bearer access_token

7. Resource Server returns authenticated API payload

Implicit

Browser-based apps run entirely in the browser after loading the source code from a web page typically based on a client side programming language such as JavaScript. Since the entire source code is available to the browser, these apps cannot maintain the confidentiality of their client secret, so the secret is not used in this case.

Like browser-based apps, mobile apps also cannot maintain the confidentiality of their client secret. Because of this, mobile apps must also use an OAuth2 flow that does not require a client secret such as the implicit flow.

The following diagram shows the transaction flow of the implicit grant type

1. Redirect the user browser to Authorization Server.

• Includes response_type=token, client_id, redirect_uri, scope, state

2. User authenticates and grants authorization to the 3rd party App.

• User submits their credentials for the Authorization Server

3. Authorization Server now redirects back to the client side application (redirect URI) including the access token

• Includes access_token, state

4. Client side application recovers the access token from the redirect request.

• Uses client side javascript or registered AppURL for mobile to parse access token

5. Client side application includes access token in the HTTP Authorization header.

• Includes Bearer access_token

6. Resource Server returns authenticated API payload.

OAuth2 Error Messages

Common error messages

{"type":"http://www.w3.org/Protocols/rfc2616/rfc2616- sec10.html","title":"invalid_client","status":400,"detail":"This client is invalid or must authenticate using a client secret"}

{"type":"http://www.w3.org/Protocols/rfc2616/rfc2616- sec10.html","title":"Forbidden","status":403,"detail":"Client does not have \u2018Allow API Access\u2019 privilege"}

{"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html","title":"Not Acceptable","status":406,"detail":"Cannot honor Accept type specified"}