1. The Scope Of This Page

This paper aims to introduce the authorization scenario service capability based on standard OAuth 2.0 to merchants and external ISVs. Service capabilities include web authorization, mini program authorization, checking access token, querying the list of authorized tokens according to user ID and cancel authorization, etc. The recommended reading object of this paper is PD, DEV, QA and other relevant personnel in charge of system integration.

test: chapter 6

2. Reference

《OAUTH 2.0 Standard》

3. Terminology

4.2. Authorization Introduce

The wallet OAuth 2.0 authorization system allows the wallet user to use the identitication of the wallet to securely grant certain permissions, such as authorized login, agreement payment, etc.

After the user authorizes the third-party application through the wallet OAuth 2.0 standard, the third party can obtain the temporary access token, and access the wallet specific interface through the access token to perform business operations.

At present, the authorization mode of wallet oauth2.0 only supports the authorization code mode, which is only applicable to the access the third party with the server side.

4.2.1. Authorization Flow

4.2.1.1. Flow

4.2.1.2. Object Interaction Flow

4.2.2. WEB Authorization Service

The web authorization service is used for the merchant's web-based scene access authorization system, including H5, PC web, WAP, etc which  base on browser interaction mode.

Authorization can be divided into two interactive processes:

1. normal authorization: user authorization is required, would show the authorization page to user, and user have to confirm and agree the authorization deal.
2. silence authorization: no user authorization is required, for example, the user is authorized,  the authorization scope does not need user authorization.

4.2.2.1. normal authorization flow

1. The Thrid Party guides the user to jump to the authorization page of the wallet, and the jump address needs to be generated according to the authorization url splicing rules.
2. After the user authorizes, the wallet will redirect the user's browser to the redirect url set by the Thrid Party (the redirect URL should be consistent with the authorization redirect url which set by the Third Party when onboarding), and will bring the auth code and auth state parameters to Thrid Party
3. After acquiring the auth code, the Thrid Party exchanges the auth code for the access token
4. The Thrid Party can access the open platform of wallet to obtain user information and user authorization information by holding access_token.

see Chapter 6.4. seee xxxx

4.2.2.2. silence authorization flow

1. If the user is authorized, when the Third Party requests the open auth page again, it will automatically call back the merchant's redirect URL. won't show auth page.
2. The next steps are the same as the non silent(normal) interaction flow

Please refer to the introduction of authorized sub service chapters for detailed authorized sub service capabilities：WEB  authPage.htm refer (Chapter 6.2.)  , applyToken refer (Chapter 6.4.)，refresh token refer（Chapter 6.5.），check token refer（Chapter 6.6.），cancel token  refer (Chapter 6.8.).

4.2.2.3. Sensitive data prepares ahead of the authorization process

When the merchant has data that is not to be displayed on the user's browser, or when there are business parameters other than the OAuth standard that need to be passed on to the wallet.

When the user clicks to authorize, the merchant can pre-save the data on the side of the wallet through the interface provided by the wallet, and the wallet will return an authorized link address, the merchant will guide the user to visit the authorization address, the wallet will be based on the previously saved data to render the authorization interface.

Please refer to the introduction of authorized sub service chapters for detailed authorized sub service capabilities：prepare refer (Chapter 6.1.)  , apply token refer (Chapter 6.4.)，refresh token refer（Chapter 6.5.），check token refer（Chapter 6.6.），cancel token  refer (Chapter 6.8.).

4.2.3. Mini Program Authorization Service

The mini program authorization service is used for the merchants mini program scenario access authorization system.

Authorization can be divided into silence and non silence (normal) interaction processes, which are similar to web authorization mode services

4.2.3.1. normal authorization flow

1. When the user opens the mini program page, the Third Party mini program needs to obtain user information, Third Party mini program call jsapi to obtain auth code.
2. The  jsapi provides the getAuthCode interface to help the Third Party obtain the auth code in a very convenient way
3. Within the jsapi the wallet oauth open api will be called to determine whether user authorization is required. If user authorization is required, jsapi will render the authorization interface to guide the user to authorize.
4. When the user agree and confirm authorization, jsapi will call OAuth system to apply for auth code, then callback the callback method of the third-party mini program, and the input parameter includes auth code.
5. After the Third Party mini program obtains the auth code, it can exchange the token according to the auth code to continue the business.
6. When the access token expires, the Third-Party can obtain a new access token according to the refreshtoken

Please refer to the introduction of authorized sub service chapters for detailed mini program authorized sub service capabilities：mini program obtain auth code refer  (Chapter 6.3.)，apply token refer(Chapter 6.4)，refresh token refer（Chapter 6.5.），check token refer（Chapter 6.6.），cancel token refer (Chapter 6.8.).

see Chapter 6.8

4.2.3.2. slience authorization flow

1. When the user opens the mini program page, the Third Party mini program needs to obtain user information, Third Party mini program call jsapi to obtain auth code.
2. The  jsapi provides the getAuthCode interface to help the Third Party obtain the auth code in a very convenient way
3. Within the jsapi the wallet oauth open api will be called to determine whether user authorization is required. If user authorization is not required,  jsapi will call OAuth system to apply for auth code, then callback the callback method of the third-party mini program, and the input parameter includes auth code.
4. After the Third Party mini program obtains the auth code, it can exchange the token according to the auth code to continue the business.
5. When the access token expires, the Third-Party can obtain a new access token according to the refreshtoken

Please refer to the introduction of authorized sub service chapters for detailed mini program authorized sub service capabilities：mini program obtain auth code refer  (Chapter 6.3.)，apply token refer(Chapter 6.4)，refresh token refer（Chapter 6.5.），check token refer（Chapter 6.6.），cancel token refer (Chapter 6.8.).

4.3. User Authorization Management Introduce

4.3.1. User Authorization Management Flow

1. The user queries the current valid authorization information list in the wallet, including access token, authorization expiration time, third party, authorization scope and other information.
2. The user can cancel the authorization to the third party with the access token in the wallet.

Please refer to the introduction of authorized sub service chapters for detailed user authorization management sub service capabilities：inquiry token refer（Chapter 6.7.），cancel token refer (Chapter 6.8.).

5. Sub Service List

OAuths-Standard-API-Specifications.1.1.2

6. Authorization Sub Service Introduction

6.1. Prepare

6.1.1. Sub Service Introduction

When the merchant has data that is not to be displayed on the user's browser, or when there are business parameters other than the OAuth standard that need to be passed on to the wallet.

When the user clicks to authorize, the merchant can save the authorization data in advance by the interface provided by the wallet to save the authorization data, and the wallet will return an authorized link address. The merchant directs the user to the authorized address, and the wallet renders the authorization interface based on the previously saved data.

6.1.2. User Case

6.1.3. Sub Service Constraint

1. Client must be checked in in advance on the wallet side.
2. The scope must be within the range assigned to client.
3. It is recommended that the access party pass auth state in the authorization link and verify the auth code at the time of the callback to put the cross-site attack.
4. The returned URL link is time-sensitive, the wallet should be used as soon as possible after it is obtained to the url, and the URL will be invalid after the user visits it.

6.1.4. Related APIs

6.2. Get Auth Code In WEB Interation

6.2.1. Sub Service Introduction

interface standard：/v1/oauths/authPage.htm

Third Partry generate the auth page url by wallet specification, then  guides the user to jump to the auth page. When the user completes the authorization, the wallet will redirect back to the merchant's redirect url, and bring the auth code and auth state. So, merchant can should check the auth state and obtain the auth code from input parameters.

6.2.2. Sub Service Constraint

1. the client id have to onboad wallet before calling guild user jump to auth page.
2. scope must be with in the legal scope of client.
3. The validity of auth code will not be very long. After the Third Party obtains the auth code, it needs to exchange access token as soon as possible.
4. sensitive information cannot be transmitted in the link, because the jump link is based on the user's browser (or other media),
5. It is recommended that the Third Party pass the auth state in the authorization url link, and verify the auth code during the callback to avoid CSRF attack
6. If the user is guided to access this auth page  multiple times, the different auth code will be returned multiple times
7. the redirect url have to within the legal redirect urls of third party when third party onboarding.

6.2.3. Best Practice

request to wallet authorization url address：

https:///v1/oauths/authPage.htm?

authClientId="clientId"

&scopes="scope"

&authRedirectUrl="merchant domain url/..."

&authState="random id"

call back to merchant:

merchant domain url?

authCode = "authCode"

authState = "random id"

third party have to check the auth state is the same as the auth state in current session. to avoid CSRF attack.

6.3. Get Auth Code In Mini Program Interation

6.3.1. Sub Service Introduction

The authorization code of the mini program needs to be implemented based on the jsapi of the mini program. The user will be guided to complete the authorization within the jsapi. After the authorization is completed, the access party will obtain the corresponding auth code in the callback function of the jsapi.

6.3.2. Sub Service Constraint

1. the client id have to onboad wallet before calling guild user jump to auth page.
2. The validity of auth code will not be very long. After the Third Party obtains the auth code, it needs to exchange access token as soon as possible.
3. if call jsapi getAuthCode multiple times, the different auth code will be returned multiple times

6.3.3. Best Practice

my.getAuthCode({
  scopes: 'BASE_USER_INFO',
  success: (res) => {
    my.alert({
      content: res.authCode,
    });
  },
});

6.4. Apply Access Token

6.4.1. Sub Service Introduction

The authorization token application is used to exchang the access token based on the auth code after  obtaining the auth code.

6.4.2. USER CASE

6.4.3. Sub Service Constraint

1. When get access token by auth code, grant type field must be equal to AUTHORIZATION_CODE
2. The access token in the returned result has ceratin timeliness. After the access token expiration, third party should get the Third Party needs to exchange a new access token based on the  refresh token
3. After exchanging access token by auth code, the auth code will be invalid and cannot be used again. if third party use same auth code to exchange access token again, it should get USED_AUTH_CODE result code.
4. If third party call this open api when auth code is expired, it should get EXPIRED_AUTH_CODE result code. at this time, merchant need guild user to do authorization again if third party want a new auth code.
5. When the authorization object is an application/service and the authorized object is an ISV, after exchaning the Access Token, the ISV can place the token in the 'Agent-Token' of the subsequent request body. So that ISV can send business requests on behalf of application owners.

6.4.4. Related APIs

6.5. Refresh Access Token

6.5.1. Sub Service Introduction

When the access token expires, the third party can refresh a new access token based on the refresh token.

6.5.2. USER CASE

6.5.3. Sub Service Constraint

1. When refresh a new access token by refresh token, grant type field must be equal to REFRESH_TOKEN.
2. The access token in the returned result has certain timeliness. After the access token expiration, the Third Party needs to exchange a new access token based on the  refresh token.
3. refresh token has certain timeliness, after refresh token is expired, third party can't use refresh token to exchange a new refresh token, and it should return EXPIRED_RERESH_TOKEN result code.

6.5.4. Related APIs

6.6. Check Token

6.6.1. Sub Service Introduction

Check that the Thrid Party's authorization token is legitimate.

6.6.2. User Case

6.6.3. Sub Service Constraint

1. Client must be checked in in advance on the wallet side.
2. Scope must be within the legal scope of the client.
3. Access token must be valid.

6.6.4. Related APIs

6.7. Inquiry Tokens

6.7.1. Sub Service Introduction

Query the list of authorization binding relationships between the user and the Thrid Party and return the user's current list of valid authorization relationships.

6.7.2. User Case

6.7.3. Sub Service Constraint

1. Client must be checked in in advance on the wallet side.

6.7.4. Related APIs

6.8. Inquiry Token Info

6.8.1. Sub Service Introduction

Query the authorization binding relationship between the user and the Thrid Party and return the user's current valid authorization relationship.

6.8.2. USER CASE

6.8.3. Sub Service Constraint

1. Client must be checked in in advance on the wallet side.
2. Access token must be valid.

6.8.4. Related APIs

6.9. Cancel Token

6.9.1. Sub Service Introduction

When the user is unbinding on the third party side, third party can call the cancel token interface to unbind the user's authorization. 

after this operation, all of the  tokens which under this scope of request access token will be disabled.

6.9.2. USER CASE

6.9.3. Sub Service Constraint

1. After the the token has been canceled, the third party will lose the corresponding authority and cannot do the corresponding operation until the user authorizes again next time.
2. Even if the token is invalid, it also can be cancelled, and after the cancelation all of the  tokens which under this scope of request access token will be disabled.
3. If the current token has been cancelled, success also will be returned.

6.9.4. Related APIs

6.10 Consult Auth

6.10.1. Sub Service Introduction

Consult  the Thrid Party's auth info.

6.10.2. USER CASE

6.10.3. Sub Service Constraint

1. will check client & scope & redirectUrl .etc to see if it is illegal;
2. will check if can skip user authorized and return  authRequired;
3. will fill auth info if necessary;

6.10.4. Related APIs