OAuth2.0 for dummies — Obtaining Authorization from the User
In the previous article, we discussed a very high level overview of the OAuth2.0 protocol and its basic authorization flow. But in that, we did not go into details of each step of the flow. With this article, we are going to start doing that. Buckle up!
Here, we will discuss how the very first step happens, which is called the “Authorization grant”. It is simply the step in which the client obtains the authorization from the resource owner. After this step, there is no more interaction with the resource owner. Then the authorization server will basically represent the resource owner in front of the other parties.
There are 4 main ways that the authorization grant can happen, according to the specification. We will go through each method individually, to understand. But I must note that these 4 methods are not the only methods that the authorization grant can happen. There’s the possibility for extension grant types. So if you don’t like any one of the below 4, just make yourself a new grant!
Also, please note that I will not go into detail about these grant types. I will rather give you a high level understanding on how everything works. The flow diagrams are obtained from the specification itself, to keep the originality.
Authorization code grant
This grant requires the involvement of a user-agent, which is most of the time a web browser, to mediate the interactions in between the authorization server, client and the resource owner. It is optimized for confidential clients. For this flow to happen, the client must be registered with the authorization server previously, and must have a unique client identifier (Client ID) issued by the authorization server.
A: The client initializes the code flow by interacting with the user-agent. The user-agent then sends the Client ID of the client and the redirection URI to which the authorization code must be sent to, to the authorization server.
Note: Here, the endpoint of the authorization server which is reached by the user-agent is the authorization endpoint. There are 2 main endpoints in the authorization server, the authorization endpoint and the token endpoint.
B: The authorization server requires the consent of the user whether to give the client access or not. Also it requires the fact that, if the client is given access, to which resources exactly it must be given access to. For this purpose, the user-agent prompts the resource owner to authenticate him or herself and to specify which resources must be given access to. Then the user-agent provides that permission information to the authorization server.
C: After processing the resource owner authentication result and the permissions granted, the authorization server generates an authorization code specifically for the client and sends it to the client via the user-agent. By this step, the preliminary steps of the authorization code grant are over.
D: The client can now send the received authorization code directly to the authorization server. It does so, requesting an access token which can be presented to the resource server for accessing the authorized resources.
E: The authorization server processes the request and generates an access token which suits the authorized access, and sends it back to the client. Optionally, a refresh token can also be sent, to be used in case the original access token is expired. Then the client can request for a new access token by presenting the refresh token. Authorization server then will send a new access token, with another refresh token as well. These tokens are issued from the token endpoint of the authorization server.
Now, these steps are the steps followed if the resource owner authenticates correctly and gives the permission to either all or a few of the resources requested. But there are two cases where this flow is not followed accordingly.
- If the redirection URI is missing, invalid or mismatching
- If the client ID is missing or wrong
- Even though client ID is correct, but the client secret is wrong
- If the resource owner denies the access request
In those cases the authorization server sends an error response to the client, according to the type of issue.
Implicit grant
Note: We must keep in mind that each of these grants represent certain situations. They are not mere options which we can fit into any situation. The implicit grant is optimized for public clients.
The main difference between implicit and authorization code grants is that implicit directly receives an access token as a result of the authorization request, whereas the authorization code grant gives an authorization code back to the client.
A: The client starts the flow by sending the authorization server its client ID and the redirection URI, so that the authorization server knows which client it was started from and where exactly (to which URI) it has to send the access token to. This is done via a user-agent.
B: Then in the same way as in authorization code grant, the resource owner authenticates him or herself and gives the necessary permissions.
C: From here onwards, we assume that the resource owner grants access. The authorization server directs the user-agent to the client (to the redirection URI provided earlier). The redirection URI includes the access token in the URI fragment.
D: Saving the URI fragment locally, the user-agent sends a request to the web-hosted client resource with the redirection URI without the fragment.
E: The web-hosted client then processes the request and creates a script which can extract the access token from the URI fragment. Then it embeds the script in an HTML document and sends it back to the user-agent.
F: The user-agent then runs the script obtained and extracts the access token from the URI fragment.
G: Then the access token is passed to the client. No refresh tokens are issued in this grant.
In the same way as earlier, if an error condition occurred, an error response is sent to the client accordingly.
Resource owner password credentials grant
This grant is also used in special situations where the resource owner has a direct trust relationship with the client. The client is provided with the credentials of the resource owner for the authorization server. Since the major part of risk is borne by the resource owner when enabling this grant type, the process is relatively simpler than the previously discussed grants. But this is a highly risky method, which should only be used if any previous grants are not possible to be used.
A: The resource owner simply provides the client with his/her credentials.
B: The client acts as the resource owner himself, provides the resource owner credentials and requests for an access token.
C: The client is given an access token with optionally a refresh token as well.
Client credentials grant
Here, first it should be arranged with the resource owner and the authorization server on which clients are given access through this grant. This enables the client to get an access token by using the client’s credentials. It is recommended during machine to machine interactions. It is somewhat like the client is a representative of the resource owner. There is no interaction with the resource owner at all in this flow. Resource owner’s interaction is done before the flow starts. The exact way that the previous arrangement is done is not specified in the specification.
Reminder: The client has to register itself with the authorization server prior to the flow in all of these grants. So the authorization server already has a unique client ID and a client secret (credentials), dedicated to the client.
So in some ways, the resource owner password credentials grant and the client credentials grant is quite similar. In this also, the major part of the risk is borne by the resource owner. So the flow is quite simple.
A: The client authenticates itself to the authorization server and requests for an access token.
B: The authorization server processes the request and provides the client with an access token. In this grant also, a refresh token is not issued, similar to the implicit grant.
In addition to these main grants, the authorization server supports any extension grant types as well.
References
- OAuth2.0 Specification: https://www.rfc-editor.org/rfc/pdfrfc/rfc6749.txt.pdf
- OAuth2.0 for dummies (Previous article): https://medium.com/@malshanranawella/oauth2-0-for-dummies-4292a5a0bcde
