13 How Major Open Platforms Use OAuth 2 #

Hello, I am Wang Xindong.

In our course, I have mentioned “open platforms” many times. It is not difficult to understand that their role is for businesses to empower their own business capabilities mainly in the form of open APIs to external developers. As third-party developers or ISVs (independent software vendors), when we connect to these open platforms, what we should be most concerned about is their official documentation, paying attention to the integration process, the corresponding APIs, and the parameters passed for each API, and that should be enough.

At this point, you will find that “official documentation of open platforms” will be a key point. However, when you go to major open platforms to read these documents, you will find that these documents are very scattered.

The reason for this is also simple, that is, in order for developers who already have knowledge of OAuth 2.0 to quickly connect to the platform’s business, the open platforms have classified the various integration processes. For example, you will find that the WeChat open platform has documents on using authorization code to obtain authorization information and documents on obtaining tokens, but there is no overall document that can be connected. From my perspective, this indirectly increases the learning curve because if you don’t understand OAuth 2.0, it is basically impossible to understand those classifications.

So today, I will take advantage of this point to talk to you about how major open platforms, represented by JD, WeChat, Alipay, and Meituan, use OAuth 2.0. Understanding this issue will help you better understand the underlying logic when integrating with an open platform and reading an official integration document in the future.

Before formally introducing the usage details of major open platforms, let’s first take a look at the overall system structure of the open platforms of major companies. From my observation, the basic system structure and the interaction process of the authorization system in the center are similar among different open platforms. They all authorize through an authorization service and authenticate through a gateway. Therefore, next, I will take the JD Merchant Open Platform as an example to tell you what the system of open platforms looks like.

What does the open platform system look like? #

First, let’s take a look at the overall structure of the JD.com Seller Open Platform, as shown in the diagram below.

Figure 1: Diagram of the JD.com Seller Open Platform system structure

We can divide this architectural system into three parts:

Third-party software refers to application software developed by third-party developers or ISVs that is implemented through integration with the open platform, such as the Little Rabbit Printing System.

The JD.com Seller Open Platform includes the API Gateway Service, OAuth 2.0 Authorization Service, and Third-party Software Developer Center Service. The API Gateway Service and OAuth 2.0 Authorization Service are the “two legs” of the open platform, while the Third-party Software Developer Center Service provides developers with the service to manage basic information of third-party software applications, such as app_id and app_secret.

Various microservices within JD.com, such as the order service and product service. These microservices are the protected resource services we mentioned before.

From the figure, we can also see the overall call relationship of this system: third-party software makes an HTTP request to the open platform, specifically to the API Gateway Service of the open platform, and then the API Gateway Service internally makes RPC calls to various microservices.

Next, let’s take the example of user Xiaoming using the Little Rabbit Printing System to see how these system roles interact with each other.

Figure 2: Diagram of the interaction within the open platform system

From here, we can observe that the interactions between various system roles in the open platform system can be summarized as follows:

When user Xiaoming accesses the Little Rabbit Printing System, Little Rabbit first requests an access token from the OAuth 2.0 Authorization Service of the open platform, and then Little Rabbit uses the access token to make a request to the API Gateway Service.

In the API Gateway Service, two basic checks are performed: one is the legitimacy check of the access token, such as checking if the access token has expired, and the other is the legitimacy check of the Little Rabbit Printing System’s basic information, such as app_id and app_secret.

After both checks pass, the API Gateway Service initiates the final data request.

It should be noted that, as mentioned in Lesson 5, when verifying the access token or the information of third-party software applications, it is done in the protected resource services. When we have an API Gateway layer, these verification tasks are all delegated to the API Gateway, since we don’t want many protected resource services to perform the same tasks.

Now that we understand the structure of the JD.com Seller Open Platform, we can summarize. With the capabilities provided by the open platform, it can be said that the open platform, users, and developers have achieved a win-win situation: Xiaoming has improved the efficiency of printing orders by using the Little Rabbit Printing System; the developer of the Little Rabbit Printing System has gained profits from Xiaoming’s order services; and by exposing APIs for the Little Rabbit Printing System to efficiently process C-end user orders, JD.com has improved the user experience.

However, openness is a double-edged sword. In an ideal situation, the platform, developers, and users can all benefit, but as mentioned in Lessons 8 and 10, security issues should never be ignored, especially when it comes to user information security. Next, I will share with you a case on how the open platform system solves the security problem of access tokens.

We already know that when a user grants authorization to a third-party software, the authorization service generates an access token that is associated with the user. For example, when Xiaoming grants authorization to the Little Rabbit Printing System, the granularity of the access token is: Little Rabbit Printing System + Xiaoming.

We also know that the Little Rabbit Printing System can use this access token to access Xiaoming’s data on behalf of Xiaoming; if the access token expires, the Little Rabbit Printing System can continue to use the refresh token to access until the refresh token also expires.

Now the problem arises: if Xiaoming cancels their account or changes their password, the access tokens that were previously authorized for other third-party software should be invalidated immediately. Otherwise, until the refresh token expires, the third-party software can continue to use the previous access token to request data. This is obviously unreasonable.

Therefore, in this case, the authorization service receives messages about user account cancellation and password modification through a Message Queue (MQ) and then clears the access token.

Figure 3: Cleaning up access tokens

In fact, the approach to solving the security problem of access tokens in this case not only applies to the open platform, but can also serve as a reference when building your own OAuth 2.0 authorization system architecture within the enterprise.

The above is the overall structure of the open platform and the specific security issues of user access tokens that need to be paid attention to. As third-party software developers, when integrating with these open platforms or browsing their websites, we can almost always see a sentence like “All APIs require OAuth Authorization and can only be called after user confirmation”, which is the fundamental role of OAuth 2.0.

Now that we have understood the context of the open platform, let’s take a look at how the open platform uses the OAuth 2.0 authorization flow through a series of diagrams.

Authorization Process of Major Open Platforms #

We will take WeChat, Alipay, and Meituan as examples to see how they use OAuth 2.0 for open authorization. First, let’s take a look at the official authorization process diagrams:

Figure 4 WeChat Open Platform Authorization Process

Figure 5 Alipay Open Platform Authorization Process

Figure 6 Meituan Open Platform Authorization Process

In these three authorization process diagrams, we can see that there are words related to the authorization code “code.” This indicates that they all recommend developers to choose the authorization code flow as the preferred method. So now you can better understand why I have spent so much time in this course talking about authorization code grants.

At the beginning of this lesson, I also mentioned that as developers, the most important thing for us when integrating with open platforms is their official integration documents. And the most headache-inducing part of these documents is the parameters that need to be passed during the communication process. In the following section, I will guide you through the meaning and key points behind these parameters from my perspective, using the JD Merchant Open Platform as an example. This way, when you perform specific integration operations, you will find them much easier.

Parameter Description in Authorization Code Flow #

In summary, in the authorization service of the JD Seller Open Platform, there are two endpoints that provide services: the Authorization Endpoint responsible for generating the authorization code, and the Token Endpoint responsible for issuing the access token. Although there are many parameters in the entire authorization process, you can categorize them around these two endpoints.

Next, let’s continue to use the example of the Rabbit Print Software to see which parameters it uses when integrating with the JD Seller Open Platform.

When Xiaoming uses the Rabbit Print Software, he is first redirected to the authorization service of the JD Seller Open Platform by Rabbit Print Software, which is actually redirected to the Authorization Endpoint of the authorization service. The parameters used in this redirection process are as follows:

Figure 7 Parameters used in the redirection process

It should be emphasized here that for the “state” parameter, it is now “recommended” by the official. As mentioned in [Lesson 8], the official recommendation of OAuth 2.0 to prevent CSRF attacks is to use the “state” parameter. So for the sake of security, you should still use it.

Then, the Authorization Endpoint of the JD Seller Open Platform authorization service responds to the Rabbit Print Software. The basic parameters used in this response process are as follows:

Figure 8 Parameters used by the Authorization Endpoint response to the Rabbit Print Software

For the value of the authorization code “code”, the general recommendation is to have a maximum lifespan of 10 minutes. In addition, the Rabbit Print Software is only allowed to use the value of this authorization code once. If the same authorization code value is used to request again after one use, the authorization service must reject it.

For the value of “state” this time, the authorization service must return it to the Rabbit Print Software every time. Whether the Rabbit Print Software sends this value initially or not, it must be returned. In this way, when the Rabbit Print Software adds this value in future upgrades, the JD Seller Open Platform does not need to modify any code logic.

After obtaining the value of the authorization code “code”, the next step is for the Rabbit Print Software to make a request to the Token Endpoint of the JD Seller Open Platform authorization service to apply for an access token. The basic parameters that need to be passed during this process are as follows:

Figure 9 Basic parameters that need to be passed for requesting an access token

After the authorization service receives the Rabbit Print Software’s request for an access token, like the Authorization Endpoint, the Token Endpoint also needs to respond to the Rabbit Print Software. The basic parameters involved in this process are as follows:

Figure 10 Parameters involved in the Token Endpoint response to the Rabbit Print Software

I want to emphasize here that the “scope” value returned here is actually the actual permission scope allowed for the Rabbit Print Software, because Xiaoming may have only granted the permission of querying today’s orders API to the Rabbit Print Software, which is less than the permission scope it applied for when registering on the open platform, such as querying historical orders and querying today’s orders APIs.

Summary #

Alright, this lesson is about to end. We have learned about the overall structure and authorization process of the open platform system, as well as the parameters that need to be passed in the communication process of integrating with the open platform, which are of concern to third-party software developers. Now, I hope you can remember the following three points.

When there are multiple protected resource services, basic authentication work, including validating access tokens and third-party software application information, should be extracted into an API gateway layer, and these basic tasks should be placed in this API gateway layer.

Major open platforms recommend using the authorization code grant flow, whether it is a web-based web application or a mobile application.

For the parameters that third-party software developers focus on, they can be distinguished from the authorization endpoint and the token endpoint of the authorization service. The focus of the authorization endpoint is the handling of authorization code requests and responses, and the focus of the token endpoint is the handling of access token requests and responses.

Reflection Questions #

After introducing the API gateway layer, does the API gateway still pass the access_token value when requesting data from the order service? If not, what value does it pass?

Feel free to share your thoughts in the comments section, and feel free to share today’s content with other friends so that we can discuss together.