GM/T 0068-2019 English PDF (GMT0068-2019)
GM/T 0068-2019 English PDF (GMT0068-2019)
GM/T 0068-2019: Open third party resource authorization protocol framework
CRYPTOGRAPHY INDUSTRY STANDARD
OF THE PEOPLE REPUBLIC OF CHINA
Open Third-Party Resource Authorization Protocol
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
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
126.96.36.199 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.
188.8.131.52 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 ...