9.4. OAuth¶

9.4.1. Introduction¶

OAuth is an open network standard for authorization and is widely used around the world. The current version is version 2.0.

OAuth sets up an authorization layer between the client and the server. The client cannot directly log in to the server, but can only log in to the authorization layer to distinguish the user from the client. The token used by the client to log in to the authorization layer is different from the user’s password. The user can specify the permission scope and validity period of the authorization layer token when logging in.

After the client logs in to the authorization layer, the server opens the data stored by the user to the client according to the permission scope and validity period of the token.

OAuth 2.0 defines four authorization methods: authorization code mode (authorization code), simplified mode (implicit), password mode (resource owner password credentials) and client mode (client credentials).

9.4.2. Process¶

After the user opens the client, the client asks the user for authorization
User agrees to authorize client
The client uses the authorization obtained in the previous step to apply for a token from the authentication server
After the authentication server authenticates the client, it confirms that it is correct and agrees to issue a token
The client uses the token to apply to the resource server for resources
The resource server confirms that the token is correct and agrees to open the resource to the client

9.4.3. Authorization Code Mode¶

The authorization code mode (authorization code) is the authorization mode with the most complete functions and the strictest process. Its characteristic is to interact with the authentication server of the server through the background server of the client.

Its process is：

The user accesses the client, which directs the former to the authentication server
The user chooses whether to authorize the client
Assuming the user grants authorization, the authentication server directs the user to the “redirection URI” (redirection URI) specified by the client in advance, along with an authorization code.
The client receives the authorization code, attaches the earlier “redirect URI”, and requests a token from the authentication server
The authentication server checks the authorization code and redirection URI, and after confirmation, sends an access token and a refresh token to the client

In step A, the URI for the client to apply for authentication includes the following parameters:

response_type: indicates the authorization type, required, the value here is fixed ascode
client_id: indicates the ID of the client, required
redirect_uri: Indicates redirect URI, optional
Scope: Indicates the scope of permission to apply, optional
state: Indicates the current state of the client, which needs to be dynamically specified to prevent CSRF

For 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

In step C, the server responds to the client’s URI with the following parameters:

code: Indicates the authorization code, which is required. The validity period of the code should be short and the client can only use the code once, otherwise it will be rejected by the authorization server. There is a one-to-one correspondence between this code and the client ID and redirection URI.
state: If the client’s request contains this parameter, the authentication server responds with the same parameters as the request

For example：

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

In step D, the client makes an HTTP request for a token from the authentication server, including the following parameters:

grant_type: indicates the authorization mode used, a required option, the value here is fixed asauthorization_code
code: indicates the authorization code obtained in the previous step, required
redirect_uri: indicates the redirection URI, required and must be consistent with the value of this parameter in step A
client_id: indicates the client ID, required

For example：

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MXXXWSGmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS5WDSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

In step E, the HTTP reply sent by the authentication server contains the following parameters:

access_token: Indicates the access token, required
token_type: Indicates the token type, the value is case-insensitive, required, can be bearertype or mactype
expires_in: Indicates the expiration time, in seconds. If this parameter is omitted, the expiration time must be set in other ways
refresh_token: Represents the update token, used to obtain the next access token, optional
scope: indicates the scope of authority, if it is consistent with the scope applied by the client, this item can be omitted

For example：

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEad1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XX5Qx2TlKWIA",
  "example_parameter":"example_value"
}

9.4.4. Simplified mode¶

The simplified mode (implicit grant type) does not go through the server of the third-party application, but directly applies for a token from the authentication server in the browser, skipping the step of the authorization code, hence the name. All steps are done in the browser, the token is visible to the visitor, and the client does not require authentication.

The steps are:

The client directs the user to the authentication server
The user decides whether to authorize the client
Assuming the user grants authorization, the authentication server directs the user to the redirection URI specified by the client and includes the access token in the Hash portion of the URI
The browser makes a request to the resource server, which does not include the hash value received in the previous step
The resource server returns a web page with code to get the token in the hash value
The browser executes the script obtained in the previous step and extracts the token
The browser sends the token to the client

In step A, the HTTP request sent by the client contains the following parameters:

response_type: indicates the authorization type, the value here is fixed as token, required
client_id: indicates the ID of the client, required
redirect_uri: indicates the URI of the redirect, optional
scope: indicates the scope of authority, optional
state: Indicates the current state of the client, which needs to be dynamically specified to prevent CSRF

For 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

In step C, the authentication server responds to the client’s URI with the following parameters:

access_token: Indicates the access token, required
token_type: Indicates the token type, the value is not case sensitive, required
expires_in: Indicates the expiration time, in seconds. If this parameter is omitted, the expiration time must be set in other ways
scope: indicates the scope of authority, if it is consistent with the scope applied by the client, this item can be omitted
state: If the client’s request contains this parameter, the authentication server responds with the same parameters as the request

For example:

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

In the above example, the authentication server uses the Location field of the HTTP header to specify the URL to which the browser is redirected. Note that the token is included in the Hash portion of this URL.

According to Step D above, the browser will visit the URL specified by Location in the next step, but the Hash part will not be sent. In the next step E, the code sent by the resource server of the service provider will extract the token in the Hash.

9.4.5. Password Mode¶

In password mode (Resource Owner Password Credentials Grant), the user provides the client with his username and password. The client uses this information to request authorization from the “service provider”.

In this mode, the user must give his password to the client, but the client must not store the password.

The steps are as follows:

User provides username and password to client
The client sends the username and password to the authentication server, and requests the token from the latter
After the authentication server confirms that it is correct, it provides the access token to the client

In step B, the HTTP request sent by the client contains the following parameters:

grant_type: indicates the authorization type, the value here is fixed as password, required
username: indicates the username, required
password: Indicates the user’s password, required
scope: indicates the scope of authority, optional

For 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

In step C, the authentication server sends an access token to the client, for 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"
}

9.4.6. Client Mode¶

The client mode (Client Credentials Grant) means that the client authenticates to the server in its own name, not in the name of the user.

The steps are as follows:

The client authenticates to the authentication server and asks for an access token
After the authentication server confirms that it is correct, it provides the access token to the client

In step A, the HTTP request sent by the client contains the following parameters:

granttype: indicates the authorization type, the value here is fixed as clientcredentials, required
scope: indicates the scope of authority, optional

For example:

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

grant_type=client_credentials

In step B, the authentication server sends an access token to the client, for 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"
}

9.4. OAuth¶

9.4.1. Introduction¶

9.4.2. Process¶

9.4.3. Authorization Code Mode¶

9.4.4. Simplified mode¶

9.4.5. Password Mode¶

9.4.6. Client Mode¶

9.4.7. Reference Links¶