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.

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

• It verifies the resource owner by asking user to login, i.e. providing userID and password.
• It verifies the client by asking client to provider 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 OAuth2 grant flow can be established

• the resource owner needs to register to the authorization server, and get userID and password.
• the client needs to register to the authorization server, and get clientID and client secret.

The authorization code grant flow normally starts after resource owner logs into 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.

The first section contains the following steps:

• the resource owner indicates to the client its intention to allow the client to access certain on a resource server
• the client redirects the resource owner to the authorization server's login page, 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 expect 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.

The second section contains the following steps:

1. the authorization server checks if the resource owner has logged in. If not, ask the resource owner to login.
2. ask the resource owner if he wants to grant the client to access certain resources (described in the scope) on the resource server.
3. 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.

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.

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.

Notice that client is an application, which can be a server-based web application, a mobile application or a SPA application. When the client is a server-based web application, some parts are running at server, other parts are running in the browser that the user (resource owner) interacts. The last part of the authorization code grant flow, which is trade application code for access token, can run only on the server that hosts the client application, since that client secret is a secret hold by the client application and should not be accessible to the user and cannot go through user's browser or user's machine. The following diagram shows the last part of the flow is between two servers only. Therefore the authorization code grant flow works only for clients that are server-based web applications. For clients that are mobile applications and SPA applications, client secret is not applicable. Therefore they often use another OAuth2 grant flow: implicit grant flow, where the authorization server returns access token directly instead of returning authorization code. In this flow, there is no client authentication checking. A better approach is using the authorization code grant flow with PKCE protection. For details, see Pedro Félix, OAuth 2.0 and PKCE