OAuth 2.0OBTAINING AUTHORIZATION

Grant Types

1. Authorization Code Grant2. Implicit Grant3. Resource Owner Password Credentials Grant4. Client Credentials Grant

Authorization Code Grant

Used to obtain both Access Tokens and Refresh Tokens Optimized for confidential clients Redirection-based flow

Authorization Code Grant

Authorization Code GrantFLOW

A. Resource owner’s user agent is directed to the authorization endpoint. The client includes: Client Identifier Requested Scope Local State Redirection URI

B. Authorization server authenticates the user via the user-agent. Grants or rejects the authorization.

C. User-agent is redirected back to the “Redirection URI” with an Authorization Code. D. The client requests and access token form the authorization servers’ Token Endpoint by

presenting the Authorization Code. The client is also authenticated to the server. The client sends the Redirection URI as a means of confirmation.

E. The authentication server authenticates the client, validates the authorization code, compares the Redirection URI to the one in step C, and returns an Access Token and, optionally, a Refresh Token.

Authorization Code GrantAUTHORIZATION REQUEST

The client constructs the request URI by adding the following parameter to the query component of the authorization endpoint URI:

response_type (REQUIRED) should be set to “code” client_id (REQURIED) redirection_uri (OPTIONAL) scope (OPTIONAL) the requested scope state (RECOMMENDED) A value used by the client to distinguish the states between Request

and Callback

Example: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

Authorization Code GrantAUTHORIZATION RESPONSE

If the Authorization Server grants the permission, it redirects the client by adding the following to the Redirection URI: code (REQUIRED) the Authorization Code generated, which must

expired shortly after it has been issued. (Maximum time: 10 minutes)

NOTE: This code must only be used once. In case the server detects more than one use, it must deny the request and revoke all the tokens issued previously.

state (REQUIRED) the exact value gotten from the client request

Example:HTTP/1.1 302 Found Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA &state=xyz

Authorization Code GrantAUTHORIZATION RESPONSE – Error Response

In case of error, the resource owner is informed and it is NOT redirected automatically.

The error URI contains: error (REQUIRED) ASCII, should be one of the following:

invalid_request, unauthorized_client, access_denied, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable

error_description (OPTIONAL) human-readable, ASCII error_uri (OPTIONAL) human-readable web page state (REQUIRED) same value as in the client request

Example:HTTP/1.1 302 Found Location: https://client.example.com/cb?error=access_denied&state=xyz

Authorization Code GrantACCESS TOKEN REQUEST

The client makes a request to the token endpoint with the following parameters: grant_type (REQUIRED) must be set to “authorization_code” code (REQUIRED) authorization code received from the authorization

server redirect_uri (REQUIRED) identical value to the one in authorization

request client_id (REQUIRED) if the client is not authenticating with the

authorization server

*NOTE: If the client type is confidential or the client was issued client credentials, the client must authenticate with the authorization server.

Authorization Code GrantACCESS TOKEN REQUEST - Continued

Example: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

Authorization Code GrantACCESS TOKEN REQUEST - Continued

The authentication server must: Require client authentication for confidential clients or clients that were

issued client credentials Authenticate the client if it is included Ensure the authorization code is the one that belongs to the client If the client is public, verify client_id Verify that the authorization code is valid Ensure that the redirect_uri parameter is present if redirect_uri was

included in th initial authorization, and if included, ensure they are identical.

Authorization Code GrantACCESS TOKEN RESPONSE

Example of a token: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“ }

Implicit Grant

Used to obtain Access Tokens (not Refresh Tokens) Optimized for public clients, which operate at a particular Redirection URI Clients are typically implemented on a browser using a scripting language such

as JavaScript Redirection-based flow Client interacts with the user-agent and receives incoming requests via

redirection by the server As opposed to the Authorization Code grant type, this sends a one-time

request to obtain an access token via authorization Doesn’t include client authentication and relies on resource owner’s presence. The access token is encoded into the redirection URI and exposed to every app

residing on the user’s device

Implicit Grant

Implicit GrantFLOW

A. User-agent is directed to the authorization endpoint. The client includes: client_id scope local_state redirection_uri

B. Authorization server authenticates the resource owner and requests scopeC. The user-agent is redirected to the Redirection URI. The URI contains the access token in the

URI fragmentD. The user-agent follows the redirection instructions by making requests to the web-hosted

client resourceE. The web-hosted client resources returns a web page (HTML + script) which accesses full

redirection URI including the fragmentF. The user-agent extracts the access token by using the scriptsG. The user-agent passes the access token to the client

Implicit GrantAUTHORIZATION REQUEST

The client forms the Redirection URI by adding the following parameters: response_type (REQUIRED) must be set to “token” client_id (REQUIRED) redirect_uri (OPTIONAL) scope (OPTIONAL) state (RECOMMENDED)

Example: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

Implicit GrantAUTHORIZATION REQUEST - Continued

The authorization server validates the parameters and authenticates the resource owner.

After making a decision to grant or reject the authorization, the user-agent is redirected to the Redirection URI

Implicit GrantACCESS TOKEN RESPONSE

The Access Token response contains: access_token (REQUIRED) token_type (REQUIRED) Bearer, MAC, … [case insensitive] expires_in (RECOMMENDED) lifetime in seconds scope (OPTIONAL) state (REQUIRED)

NOTE: The authorization server must not issue a refresh token!

Example:HTTP/1.1 302 Found Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA &state=xyz&token_type=example&expires_in=3600

Implicit GrantACCESS TOKEN RESPONSE – Error Response

In case of error, the resource owner is informed and it is NOT redirected automatically.

The error URI contains: error (REQUIRED) ASCII, should be one of the following:

invalid_request, unauthorized_client, access_denied, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable

error_description (OPTIONAL) human-readable, ASCII error_uri (OPTIONAL) human-readable web page state (REQUIRED) same value as in the client request

Example:HTTP/1.1 302 Found Location: https://client.example.com/cb#error=access_denied&state=xyz

Resource Owner Password Credentials Grant Suitable in cases where the resource owner has a trust relationship

with the client, such as the device operating system or a highly privileged application.

Can only be used when the client is able to retrieve the resource owner’s credentials (using a form).

Also used to migrate existing clients to OAuth using direct authentication schemes such as HTTP Basic or Digest and converting the stored credentials to an access token.

Resource Owner Password Credentials Grant

ROPC GrantFLOW

A. The Resource Owner provides the client with its username and password.

B. The client requests an access token with the Resource Owner’s credentials form the authorization server’s token endpoint. The client authenticates with the authorization server as well.

C. The authorization server authenticates the client and validates the credentials. If valid, it issues the access token.

ROPC GrantAUTHORIZATION REQUEST AND RESPONSE

The method of obtaining the resource owner credentials is left up to the implementation.

The client must discard the credentials as soon as the access token is obtained.

ROPC GrantACCESS TOKEN REQUEST

The client makes a request to the token endpoint by the following parameters: grant_type (REQUIRED) must be set to “password” username (REQUIRED) password (REQUIRED) scope (OPTIONAL)

If the client type is confidential or the client was issued credentials, the client must authenticate with the authorization server (ref. “Client Authentication”).

Example: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

ROPC GrantACCESS TOKEN REQUEST

The Authorization Server must:1. require client authentication for confidential clients or for clients that was

issued credentials2. authenticate the client 3. validate the resource owner’s password credentials using the existing

password validation algorithm The server should protect the endpoint against attacks (e.g.: using

rate-limitation, generating alerts…)

ROPC GrantACCESS TOKEN RESPONSE

If the authentication process is successful, the authorization server issues an access token and optionally a refresh token.

Example: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" }

Client Credentials Grant

The client makes a token request using only the client credentials when the resources are under its control.

Must only be used with confidential clients

Client Credentials Grant

Client Credentials GrantFLOW

A. The client authenticates with the server and requests a token from the token endpoint.

B. The server authenticates the client and, if valid, issues an access token.

Client Credentials GrantAUTHENTICATION REQUEST AND RESPONSE

Since the client authentication is used as the authorization grant, no additional authorization request is needed.

Client Credentials GrantACCESS TOKEN REQUEST

The client makes a request to the token endpoint by using the following parameters: grant_type (REQUIRED) must be set to “client_credentials” scope (OPTIONAL)

The client must authenticate with the authorization server. (ref. “Client Authentication”)

Example:POST /token HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=client_credentials

Client Credentials GrantACCESS TOKEN RESPONSE

If the authentication is successful, the access token is issued.

Example: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" }

Extension Grants

The client uses an extension grant type by specifying the grant type using an absolute URI (defined by the authorization server) as the value of the “grant_type” parameter of the token endpoint, and by adding additional parameters optionally.

Example: (using SAML – Security Assertion Markup Language)POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU [...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24-