OAuth2 Authorization Code Grant Flow

https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc

OAuth2 is a protocol for resource owner to grant access for a client to access resources stored on a resource server.

Authorization Code grant flow is one of the four grant flows OAuth2 supports. It is used when the resource owner has limited trust to the client (e.g. he would not be willing to give the userID and password he has with the authorization server to the client.)

What is a client? It is an application, which can be a windows application, a mobile application running in a mobile device, a web application hosted on a server, or a single-page application (SPA) provided by a server but runs soles on the user's browser. The authorization code grant flow described above is suitable only for the situation that the client's secret is not accessible to the user. A server-based web application contains pieces running at the server, and pieces running at the client.

The authorization server verifies both the resource owner and the client:

• It verifies the resource owner by asking user to login, i.e. to provide userID and password.
• It verifies the client by asking client to provide clientID and client secret.

The trust between the resource owner and the client is limited. Therefore

• The submission of userID and password from the resource owner should be done from the resource owner to the authorization server directly, outside the access of the client.
• The submission of the clientID and client secret should be done from the client to the authorization server directly, outside the access of the resource owner.

Some prerequisites need to be established before the authorization code grant flow can be established:

• the resource owner needs to register to the authorization server to get userID and password.
• the client needs to register to the authorization server to get clientID and client secret (notice this secret is for the client, so the same secret would be used for the authorization code grant flow for all resource owners.)

The authorization code grant flow normally starts after the user (a.k.a. resource owner) accesses the client. It contains 3 main sections:

• the communication between the resource owner and the client.
• the communication between the resource owner and the authorization server.
• the communication between the client and the authorization server. Once this grant flow is done, the client can communicate with the resource server to get certain resources.

The first section contains the following steps:

• the resource owner indicates to the client its intention to allow the client to access certain resources on the resource server
• the client redirects the resource owner to a page of the authorization server, and provides some additional information
  • clientID
  • redirectUrl: the url of a page of the client. After the resource owner finishes communicating with the authorization server, the authorization server should redirect the user to that url so the client can finish the rest of the flow.
  • responseType: the type of the response the client expects the authorization server to provide after the communication between the resource owner and the authorization server is done.
  • scope: what resource the client wants to access.

Question: How can a client redirect user to a page of the authorization server? If the client is a server-based web application, it can sends a http redirect response header to the browser from server, then the browser would take the user to a page hosted by the authorization server. But if the client is a native application running on the user's machine, this process would be a little different, see the explanation in https://blog.pedrofelix.org/2016/02/15/oauth-2-0-and-pkce/, which is called sending an intent.

The second section contains the following steps:

• the authorization server checks if the resource owner has logged in. If not, ask the resource owner to login.
• after login, ask the resource owner if he wants to grant the client to access certain resources (described in the scope) on the resource server.
• if the source owner indicates he grants the permission, the authorization server redirects the resource owner to a page of the client (specified in the redirectUrl), and provides an authorization code to the client. We can expect the authorization code contains the information about the resource owner and the grant scope.

Notice the communication between resource owner and the authorization server happens in browser on web pages hosted by the authorization server, regardless of the type of the client.

Question: can the OAuth2 protocol just allow the client to use the authorization code to access the resource? No, because the identity of the client has not be verified by the authorization server.

Question: how can the authorization server redirect user to a page provided by the client? If the client is a web application and the page is a web page, the authorization server can simply sends a http redirect response header to the browser, and browser can take user to a web page specified in the redirectUrl. But if the client is a native application, that url would be a custom scheme url and should be passed to the client through an inter-application messgae. For details, again see https://blog.pedrofelix.org/2016/02/15/oauth-2-0-and-pkce/.

The third section contains the following steps:

• the clients sends clientID, client secret and the authorization code to the authorization server. Once the authorization server verifies the client through the clientID and client secret, it generates an access key and returns it to the client. With the access key, the client can access certain resources on the resource server.

Such application can keep the client's secret at the server side. That secret never go to the resource owner's machine and browser. The server-side code of that web application can communicate to the authorization server directly without going through the resource owner's machine and browser. This type of clients is called confidential clients since they can keep secret and is suitable for the authorization code grant flow. The following diagram shows teh flow for credential client, and notice that the last part of the flow is between two servers only.

Other clients are called public clients since they cannot keep secret. They cannot use the last part of the authorization code grant flow as it is. Therefore they often use another OAuth2 grant flow: implicit grant flow, which is similar to the authorization code grant flow at the beginning, but the authorization server returns an access token directly instead of returning an authorization code. In this flow, there is no client authentication checking. A better approach is using the authorization code grant flow with Proof Key for Code Exchange (PKCE) extension. For details, see Pedro Félix, OAuth 2.0 and PKCE