🔐 OAuth 2
What is?
OAuth 2 is an authorization protocol that allows third-party applications to obtain limited access to protected resources on a server without exposing user credentials. It works through the issuance of access tokens, which represent the permission granted to these applications. These tokens are obtained after an authorization process that involves user authentication and obtaining consent to access the desired resources. OAuth 2 is widely used in web environments to enable secure integration between different services, such as applications that access social network data or cloud services.
Flows
OAuth 2 offers several types of authorization flows to accommodate different usage scenarios. The main ones are:
- Authorization Code Grant: Used by web applications and servers, where the client redirects the user to the authorization server to obtain an authorization code, which is exchanged for an access token.
- Implicit Grant: Used by client-side applications (such as JavaScript applications) where the access token is obtained directly after authentication, without exchanging an authorization code. It is less secure than the Authorization Code Grant as it exposes the token in the query params.
- Resource Owner Password Credentials Grant: Used in situations of high trust between the user and the client, where the user provides their credentials directly to the client, which uses them to obtain an access token.
- Client Credentials Grant: Used by applications that need to access their own resources rather than acting on behalf of a user. The client authenticates directly and obtains an access token.
- Refresh Token Grant: Allows a client to obtain a new access token using a refresh token without requiring user interaction. This is useful for keeping the user's session active without requiring re-authentication.
Each flow is designed for specific situations, providing flexibility and security when implementing OAuth 2 authorization.
OAuth 2 functionality in the HUB
Currently, the HUB has implemented the following flows: Implicit Grant and Authorization Code Grant. Below is a description of how OAuth 2 works in the HUB for each respective flow.
First of all, the application must be properly registered in the HUB with the respective information that is validated:
Field | Description |
---|---|
client_id | Client identifier. |
client_secret | Client secret. |
redirect_uris | List of possible redirect URIs. |
default_response_type | Default response type, which can be: access_token, id_token, and code. |
Implicit Grant
This is considered the simplest and also the least secure, so we do not recommend using this flow.
To perform this flow, simply follow these steps:
![](https://files.readme.io/f9bf147-oauth2-implicit-grant.png)
In addition to the first step, which changes in the flow starting from the edtech application compared to the flow starting from the HUB, in the HUB flow, you open the edtech application on the home page of the HUB after logging in.
-
Access the OAuth 2 screen with the respective query params of the application:
Field Description client_id Client identifier. redirect_uri Redirect URI that must be present in the "redirect_uris" of the application registered in the HUB. response_type It can be "id_token" or "access_token", depending on your use. For the current "user.info" scope, both can be used. scope Scope of the requests that will be made to the HUB APIs with the generated token. state This is an optional field, transmitted from login to the redirection performed in the last step. It can be any string, following the encodeURIComponent standard. -
Fill in the HUB user credentials.
-
Select a profile if the user has more than one.
-
Redirect to the redirect_uri informed in step 1, containing the following information:
Field Description user_id Identifier (UUID) of the profile selected by the user. state String informed in step 1. access_token Provided if the response type selected in step 1 was "access_token". id_token Provided if the response type selected in step 1 was "id_token". -
Call the users info API to collect user information and validate the token's veracity.
Example:
curl 'https://apihub.educacional.com/users/v1/users/info' \ -H 'accept: application/json, text/plain, */*' \ -H 'authorization: jwt_token' \ -H 'x-relationship-id: user_id'
Code Grant
This is considered a bit more complex as it requires an additional API call, making it more secure. Therefore, we do recommend using this flow.
To perform this flow, simply follow these steps:
![](https://files.readme.io/0bdf560-oauth2-code-grant.png)
In addition to the first step, which changes in the flow starting from the edtech application compared to the flow starting from the HUB, in the HUB flow, you open the edtech application on the home page of the HUB after logging in.
-
Access the OAuth 2 screen with the respective query params of the application:
Field Description client_id Client identifier. redirect_uri Redirect URI that must be present in the "redirect_uris" of the application registered in the HUB. response_type It can only be "code". scope Scope of the requests that will be made to the HUB APIs with the generated token. state This is an optional field, transmitted from login to the redirection performed in step 4. It can be any string, following the encodeURIComponent standard. -
Fill in the HUB user credentials.
-
Select a profile if the user has more than one.
-
Redirect to the redirect_uri informed in step 1, containing the following information:
Field Description user_id Identifier (UUID) of the profile selected by the user. state String informed in step 1. code Code used to call the OAuth 2 authorize API. -
Call the OAuth 2 authorize API to generate tokens from the code.
Field Description grant_type It can only be "authorization_code". client_id Client identifier. client_secret Client secret. code Code generated in step 4. Example:
curl 'https://apihub.educacional.com/lti/v1/oauth2/authorize' \ -H 'accept: application/json, text/plain, */*' \ --data-raw '{"grant_type":"authorization_code","client_id":"application_client_id","client_secret":"application_client_secret","code":"UUID"}'
-
Call the users info API to collect user information and validate the token's veracity.
Example:
curl 'https://apihub.educacional.com/users/v1/users/info' \ -H 'accept: application/json, text/plain, */*' \ -H 'authorization: jwt_token' \ -H 'x-relationship-id: user_id'
Updated 2 months ago