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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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:

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:

💡

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.

1. 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.

   Example:
   https://hub.educacional.com/oauth2?client_id=application_client_id&redirect_uri=application_redirect_uri&response_type=id_token&scope=user.info&state=%7B%22key%22%3A%22value%22%7D

2. Fill in the HUB user credentials.

3. Select a profile if the user has more than one.

4. 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".

   Example:
   https://hub.educacional.com/mock-edtech-response?state=%7B%22key%22%3A%22value%22%7D&user_id=uuid&id_token=jwt_token

5. Call the users info API to collect user information and validate the token's veracity.

   Example:

   cURL

   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:

💡

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.

1. 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.

   Example:
   https://hub.educacional.com/oauth2?client_id=application_client_id&redirect_uri=application_redirect_uri&response_type=code&scope=user.info&state=%7B%22key%22%3A%22value%22%7D

2. Fill in the HUB user credentials.

3. Select a profile if the user has more than one.

4. 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.

   Example:
   https://hub.educacional.com/mock-edtech-response?state=%7B%22key%22%3A%22value%22%7D&user_id=uuid&code=UUID

5. 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

   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"}'
   

6. Call the users info API to collect user information and validate the token's veracity.

   Example:

   cURL

   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'