GM/T 0068-2019 PDF English
Search result: GM/T 0068-2019 English: PDF (GM/T0068-2019)
Standard ID | Contents [version] | USD | STEP2 | [PDF] delivered in | Name of Chinese Standard | Status |
GM/T 0068-2019 | English | 380 |
Add to Cart
|
0-9 seconds. Auto-delivery.
|
Open third party resource authorization protocol framework
| Valid |
BUY with any currencies (Euro, JPY, GBP, KRW etc.): GM/T 0068-2019 Related standards: GM/T 0068-2019
PDF Preview: GM/T 0068-2019
GM/T 0068-2019: PDF in English (GMT 0068-2019) GM/T 0068-2019
GM
CRYPTOGRAPHY INDUSTRY STANDARD
OF THE PEOPLE’S REPUBLIC OF CHINA
ICS 35.0404
L 80
Open Third-Party Resource Authorization Protocol
Frame
ISSUED ON: JULY 12, 2019
IMPLEMENTED ON: JULY 12, 2019
Issued by: State Cryptography Administration
Table of Contents
Foreword ... 4
Introduction ... 5
1 Scope ... 6
2 Normative References ... 6
3 Terms and Definitions ... 7
4 Abbreviations ... 8
5 Overview ... 9
5.1 Protocol process ... 9
5.2 Protocol channel requirements ... 10
5.3 Protocol endpoint ... 11
6 Third-Party Applications and Security Requirements ... 14
6.1 Types of third-party applications ... 14
6.2 Third-party application identifier ... 16
6.3 Registration requirements for the third-party applications ... 16
6.4 Identity authentication of the third-party application ... 16
7 Authorization Process ... 19
7.1 Authorization grant ... 19
7.2 Authorization code grant process ... 20
7.3 Implicit grant process ... 27
7.4 Resource owner password credential grant process ... 32
7.5 Third-party application identity credential grant process ... 34
8 Token ... 36
8.1 Token type ... 36
8.2 Issuance of access tokens ... 39
8.3 Access token refresh ... 41
9 Access to Protected Resources ... 42
9.1 Access process of protected resources... 42
9.2 Successful response ... 43
9.3 Error response ... 43
Appendix A (Informative) Description of Protocol Parameters ... 44
Bibliography ... 46
Open Third-Party Resource Authorization Protocol
Frame
1 Scope
This Standard specifies the process of third-party resource authorization protocol,
different types of authorization licenses, the functional requirements of each endpoint
of the protocol, and the format and parameter requirements of messages transmitted
between system entities.
This Standard is applicable to the development, testing, evaluation and procurement
of identity authentication and authorization services in the Internet cross-security
domain application scenario.
2 Normative References
The following documents are essential to the application of this document. For the
dated documents, only the versions with the dates indicated are applicable to this
document; for the undated documents, only the latest version (including all the
amendments) are applicable to this document.
GB/T 15843.3-2008 Information Technology - Security Techniques - Entity
Authentication - Part 3: Mechanisms Using Digital Signature Techniques
GB/T 32905-2016 Information Security Technology - SM3 Cryptographic Hash
Algorithm
GB/T 32907-2016 Information Security Technology - SM4 Block Cipher Algorithm
GB/T 32918.2-2016 Information Security Technology - Public Key Cryptographic
Algorithm SM2 Based on Elliptic Curves - Part 2: Digital Signature Algorithm
GB/T 32918.4-2016 Information Security Technology - Public Key Cryptographic
Algorithm SM2 Based on Elliptic Curves – Part 4: Public Key Encryption Algorithm
GM/T 0024-2014 SSL VPN Specification
RFC 1867 Form-Based File Upload in HTML
RFC 2616 Hypertext Transfer Protocol – HTTP/1.1
RFC 2617 HTTP Authentication: Basic and Digest Access Authentication
party application uses the authorization server as an intermediary to obtain the
authorization grant from the resource owner, as shown in Figures 2 and 3;
b) The resource owner [or the resource owner indirectly through the authorization
server, as described in step a)] issues authorization grant to the third-party
application. This authorization grant is a credential authorized by the resource
owner, and the used type is one of the four types defined in 7.1.1. The type of
authorization grant depends on the way the third-party application requests
authorization [that is, the two ways described in step a)] and the type of
authorization grant supported by the authorization server (usually provided by
the service document of the authorization server);
c) The third-party application authenticates the authorization server and submits the
authorization grant, requesting an access token from the authorization server;
d) The authorization server authenticates the identity of the third-party application
and verifies the validity of the authorization grant. If the identity of the third-party
application is successfully authenticated and the authorization grant is valid, the
authorization server issues an access token to the third-party application;
e) Third-party applications send access tokens and related parameters to the
resource server to request access to protected resources;
f) The resource server verifies the validity of the access token. If the access token
is valid, the requested resource is returned to the third-party application.
Based on the above protocol process, third-party application may interact with the
resource owner through the user agent (such as a browser) used by the resource
owner. In some specific situations (see 7.5), the third-party application may not interact
with the resource owner. Interactively, directly use the identity credentials of the third-
party application to obtain the access token issued by the authorization server. If the
third-party application's access to the protected resource exceeds the scope or validity
period of the access token, the access becomes invalid; and the third-party application
should restart the protocol process or use the refresh mechanism specified in this
Standard to update the access token.
This Standard uses the hypertext transfer protocol HTTP1.1 (see RFC 2616) for
communication. The open third-party resource authorization protocol framework based
on any other protocol does not belong to the scope of this Standard.
5.2 Protocol channel requirements
For sensitive data such as authorization codes, access tokens, refresh tokens,
resource owner password credentials, and third-party application identity credentials,
plaintext transmission shall not be used; and the secure transport layer protocol
defined by GM/T 0024-2014 shall be used for transmission. The authorization server
If the third-party application has registered multiple redirection endpoint URIs, or only
registered a part of the redirection endpoint URI, or has not registered the redirection
endpoint URI, the third-party application shall use < redirect_uri> parameter in the
request when sending authorization requests to identify the redirection endpoint URI
used in this request.
When the authorization request contains the redirection endpoint URI, if the third-party
application has registered the redirection endpoint URI, the authorization server shall
use the comparison and matching method defined in section 6 of RFC 3986 to
compare and match the received redirection endpoint URI and the previous registered
redirection endpoint URI. If the third-party application registers the complete URI, the
authorization server shall use the simple string comparison method defined in section
6.2.1 of RFC 3986 to compare the two redirection endpoint URIs.
If the authorization request fails verification because the redirection endpoint URI is
missing, invalid, or mismatched, the authorization server shall inform the resource
owner of the error, and shall not automatically redirect the user agent to the redirection
endpoint URI that fails the verification.
The redirection request sent to the redirection endpoint of the third-party application
usually gets the response of the HTML document, and the response is processed by
the user agent. The third-party applications shall not include any third-party scripts in
the response to the redirection request. The third-party applications shall parse out the
credentials from the redirected request URI and redirect the user agent to another
endpoint again to avoid exposing the credentials in the URI or elsewhere.
6 Third-Party Applications and Security Requirements
6.1 Types of third-party applications
According to whether the third-party applications have the ability to keep their identity
credentials confidential, this Standard defines two types of third-party applications:
a) Confidentiality type
The third-party application has the ability to maintain the confidentiality of its
credentials (for example, the third-party application runs on a secure server that
strictly enforces access control), so that it can prove the authenticity of its identity
by providing secure identity credentials; or the third party application has the
ability to prove the authenticity of its identity through other methods (not specified
in this Standard).
b) Non-confidentiality type
Third-party applications are unable to maintain the confidentiality of their
application, nor shall be threatened by other applications on the same device.
6.2 Third-party application identifier
The third-party application identification is an application identifier issued by the
authorization server for registering the third-party application. This identifier is a string,
and the authorization server may use this string to uniquely identify a third-party
application.
This Standard does not specify the length of third-party application identifiers. The
authorization server shall specify the length of this identifier and make detailed records
of any length of identifiers issued by it. The third-party applications shall not make
assumptions about the length of this identification.
6.3 Registration requirements for the third-party applications
Before the implementation of the protocol, the provider of the third-party application
needs to register the third-party application's information (such as redirection endpoint
URI, the third-party application type, etc.) on the authorization server to establish a
trust relationship between the third-party application and the authorization server. The
third-party application provider shall use the registration method (usually provided by
the service document of the authorization server) supported by the authorization server
to complete the registration process. The specific registration method does not belong
to the scope of this Standard.
When registering a third-party application, the third-party application provider should
provide the following information to the authorization server:
a) The type of third-party application (see 6.1);
b) Redirection endpoints pointing to third-party applications (see 5.3.4);
c) Other information required by the authorization server (such as application name,
website and description, etc.).
6.4 Identity authentication of the third-party application
6.4.1 Authentication scheme of the third-party application
6.4.1.1 Authentication scheme of the password credential of the third-party
application
When the authorization server uses the authentication-scheme-based on password
credentials to authenticate third-party applications, the authorization server can use
the HTTP digest to access authentication scheme (digest access authentication
scheme, see RFC 2617). The third-party applications use the SM3 algorithm (see GB/T
32905-2016) to hash the nonce parameter values (random string to prevent replay
An identity authentication method that meets the security requirements of the
authorization server (usually provided by the service document of the authorization
server) shall be established between the confidentiality third-party application and the
authorization server; so that the authorization server can securely authenticate the
identity of the third-party application. When the authorization server usually registers
on the confidentiality third-party application, the identity credentials (such as
passwords, digital certificates) shall be granted to the third-party applications; and
authenticates the identity of the third-party applications through authentication
schemes based on password credentials or digital certificates. The confidentiality of
the third-party applications shall ensure the confidentiality of their identity credentials.
Non-confidentiality third-party applications may negotiate the identity authentication
method with the authorization server; but because non-confidentiality third-party
applications cannot guarantee the confidentiality of credentials, the authorization
server cannot rely solely on this method to judge the authenticity of the identity of the
third-party application.
The authorization server shall not issue third-party application identity credentials to
the non-confidentiality third-party applications. However, if the local application on the
special device has the ability to keep the identity credential confidential, the
authorization server may issue the identity credential of the third-party application to
this type of third-party application.
In order to prevent counterfeit third-party applications, the authorization server shall
authenticate the identity of the third-party applications. When the identity
authentication process of a third-party application cannot be implemented, the
authorization server shall use other methods to verify the identity of the third-party
application. For example, the authorization server may require the third-party
application to register the redirection endpoint and compare the redirection endpoint
URI in the request with the registered redirection endpoint URI, or require the resource
owner to participate in confirming the identity of the third-party application (after the
authorization server authenticates the identity of the resource owner, provide the third-
party application, its requested protected resource access scope, and life cycle to the
resource owner, and the resource owner checks the current third-party application
information and decides to authorize or reject the request). The method of verifying the
validity of the redirection endpoint URI and requiring the resource owner to participate
in the authentication process is not sufficient to verify the identity of a third-party
application, but it may prevent passing the credentials to a counterfeit third-party
application.
The authorization server shall not automatically process (without active interaction with
the resource owner) the repeated authorization requests in the following two situations:
a) Fail to authenticate the third-party applications;
b) It cannot be confirmed that the repeated request is from a real third-party
d) The third-party application sends an access token request (see 7.2.4) to the token
endpoint of the authorization server, this request contains the authorization code
obtained in the previous step. When constructing this request, the third-party
application shall authenticate the identity of authorization server. At the same
time, the third-party application shall include the redirection endpoint URI of the
authorization code received in the request.
e) The authorization server authenticates the third-party application; verifies the
validity of the authorization code; and ensures that the received redirection
endpoint URI is the same as the redirection endpoint URI in step c). If the
verification is passed, the authorization server returns the access token (and may
also return the refresh token) to the third-party application.
In the authorization code process, the following security requirements shall be met:
a) The authorization code shall be transmitted by the secure communication
protocol described in GM/T 0024-2014.
b) When issuing the authorization code, if the authorization server may authenticate
the third-party application, the authorization server shall authenticate the third-
party application (see 6.4) to ensure that the authorization code is issued to the
correct third-party application.
c) The authorization code shall be one-time effective, and the authorization code
shall have a short life cycle. If the authorization server finds that a certain
authorization code has been used for multiple times, the authorization server
shall revoke all access tokens (or/and refresh tokens) issued by the authorization
code.
d) When using the authorization code grant type, the third-party application
specifies the redirection endpoint URI through the parameter < redirect_uri>. If
the attacker may tamper with the value of the redirection endpoint URI, it shall
cause the authorization server to redirect the user agent of the resource owner
to the endpoint controlled by the attacker (the redirection request contains the
authorization code). In order to avoid such attacks, the authorization server shall
ensure that the redirection endpoint URI used to obtain the authorization code is
consistent with the redirection endpoint URI provided when the authorization
code is used to obtain the access token. The authorization server shall require
the non-confidentiality third-party applications to register the redirection endpoint
URI, and should require the confidentiality third-party applications to register the
redirection endpoint URI. If the request contains the redirection endpoint URI,
the authorization server shall verify it according to the registered value.
7.2.2 Authorization request
The third-party application constructs an authorization request by adding the following
authorization code. If the authorization code is reused, the authorization server
shall reject this request and revoke all access tokens previously issued based
on the authorization code. The authorization server shall bind the authorization
code with the third-party application identifier and redirection URI.
b) < state>
If the authorization request of the third-party application contains this parameter,
the authorization response shall also include this parameter. The value of this
parameter is the same as the value of < state> in the authorization request of the
third-party application.
Third-party applications shall ignore unrecognized response parameters. This
Standard does not define the string length of the authorization code. The third-party
applications should not make assumptions about string length. The authorization
server shall specify the length of all its issued parameter values in the service
document.
7.2.3.2 Error response
If an error occurs due to missing, invalid, or mismatched redirection endpoint URIs, or
due to missing or invalid third-party application identifiers, the authorization server shall
inform the resource owner of the error and must not automatically redirect the user
agent to an invalid redirection endpoint URI.
If the authorization failure occurs because the resource owner refuses the access
request or due to reasons other than the wrong redirection endpoint URI, the
authorization server shall add the following parameters to the query component of the
redirection endpoint URI to notify the third-party application of the cause of the error:
a) < error> [required]
The error code in ASCII code format, the type of error code is as follows:
1) invalid_request means that required parameters are missing in the request, or
there are invalid parameters, or a parameter is repeatedly included, or other
forms of format errors;
2) unauthorized_client means that the third-party application is not authorized to
use the current method to request an authorization code;
3) access_denied means that the authorization server rejects the access request
(NOTE: there is no distinction between the resource owner's rejection of the
request and the authorization server's rejection of the request, and the same
error code type is used);
4) unsupported_response_type indicates that the authorization server does not
authenticates the resource owner process through the user agent of the resource
owner).
c) Assuming that the resource owner agrees to this access, the authorization server
uses the redirection endpoint URI (this redirection endpoint URI is the third-party
application Web resource endpoint URI in Figure 3) provided by the third-party
application during registration to send a redirection request to the user agent
of the resource owner, and include the access token in the fragment component
of the redirection endpoint URI.
d) According to the redirection request, the user agent uses the redirection endpoint
URI (excluding fragment components) to send a request to the web resource of
the third-party application. The user agent saves the fragment component in the
redirection endpoint URI locally.
e) The Web resource of the third-party application returns a web page (usually an
HTML document with an embedded script), which can read the complete
redirection URI reserved locally by the user agent, and can extract the access
token (and other parameters) contained in the fragment component.
f) The user agent of the resource owner executes the script returned in step e)
locally to extract the access token.
g) The script returned in step e) uses the user agent to send the extracted access
token to the third-party application.
In the implicit grant process, the following security considerations shall be taken:
a) The implicit grant process does not include the identity authentication process for
the third-party applications. In some specific cases, the authorization server may
verify the identity of the third-party applications. For example, the authorization
server verifies the identity of the third-party application by verifying whether the
redirection endpoint URI in the request is consistent with the redirection endpoint
URI provided during the registration of the third-party application.
b) Since the access token issued by the authorization server shall be encoded in
the redirection endpoint URI, the access token may be exposed to the resource
owner or other applications that can access the user agent of the resource owner.
c) Since the implicit grant process reduces the link of using authorization codes to
obtain access tokens, this process may improve the responsiveness and
efficiency of certain third-party applications (such as applications embedded in
browsers). However, if multiple types of processes, such as authorization code
grant process and implicit grant process, may be used, it shall balance between
the performance improvement brought by the implicit grant process and the
security issues it brings.
8 Token
8.1 Token type
8.1.1 Access token
An access token is a credential issued by the authorization server to a third-party
application to access protected resources. The access token is represented by a string,
indicating that the third-party application has the authorization of the resource owner.
Access tokens are usually not easy to interpret for third-party applications. The access
token gives the access scope and access validity period of the protected resource. The
access scope and access validity period are authorized by the resource owner, and
implemented by the resource server and authorization server.
The access token may be used as an identifier for extracting authorization information;
it may also contain authorization information itself, and the authorization information
contained in the access token may be verified in some way (for example, including
data and signature). This Standard requires that the authorization server shall first use
the SM3 algorithm (see GB/T 32905-2016) to hash the content of the access token,
then use the SM2 algorithm (see GB/T 32918.2-2016), and finally use the SM4
algorithm (see GB/T 32907-2016), send out the token that has been finally signed and
encrypted. The access token contains the necessary information required by the third-
party application to request the protected resource.
Generally, each type of access token shall have a corresponding specification
document. If a third-party application cannot understand the type of an access token,
the third-party application must not use this access token. In the definition of the access
token type, other parameters other than the parameters defined in 8.2.2 shall be
specified in the access token response; meanwhile, the verification method of the
access token shall be specified.
When transmitting and storing access tokens, the confidentiality of the access token
(and other confidential access token attributes) shall be ensured; and share among
the resource server, resource server where the resource specified by the access token
is located, and the third-party application corresponding to the access token. The
transmission of the access token shall use the secure transport layer protocol defined
by GM/T 0024-2014.
When the implicit grant process is used for authorization, the access token is
transmitted in the URI fragment, but this transmission method may expose the access
token to unauthorized parties. The authorization server shall ensure that unauthorized
parties cannot forge and modify the access token, and it is difficult to predicate the
access token to generate a valid access token.
Third-party applications shall request access tokens with the lowest protected resource
Figure 6 – Protocol Process of Using Refresh Token
The specific steps of the process shown in Figure 6 are as follows:
a) The third-party application authenticates the identity of the authorization server
and submits the authorization grant to request the access token and refresh
token.
b) The authorization server authenticates the identity of the third-party application
and verifies the validity of the authorization grant. If the identity authentication is
passed and the authorization is valid, the access token and refresh token shall
be issued.
c) The third-party application presents the access token to the resource server,
requesting access to the protected resource.
d) The resource server verifies the validity of the access token. If the access token
is valid, the request is accepted.
e) Repeat steps c) and d) until the access token expires. In the case that the access
token expires, perform step g), otherwise continue to request access to the
protected resources.
f) If the access token is invalid, the resource server returns an error response
indicating that the access token is invalid.
g) The third-party application authenticates the identity of the authorization server
and presents a refresh token to request a new access token. Whether the
authorization server needs to authenticate the identity of the third-party
application again depends on the type of the third-party application and the policy
of the authorization server (usually provided by the service document of the
authorization server).
h) The authorization server authenticates the identity of the third-party application
and verifies the validity of the refresh token. If the refresh token is valid, it shall
issue a new access token to the third-party application (or issue a new refresh
token at the same time (optional)]).
This Standard does not specify the sp......
...... Source: Above contents are excerpted from the PDF -- translated/reviewed by: www.chinesestandard.net / Wayne Zheng et al.
|