Google OAuth 2.0

Google OAuth 2.0 is an authorization protocol that allows a service (application) to be granted access rights to user resources on another service. The protocol can prevent the need for the application to be entrusted with login and password information and grant only a restricted set of rights rather than all of them at once.

First, we recommend you to read and understand Google OAuth 2.0 documentation available at https://developers.google.com/identity/protocols/OAuth2

The general flow for setting up Google OAuth and Corezoid is the following:

1. Create a Project on the Google Cloud Console.
2. Enable the Google OAuth API for your project.
3. Learn the requirements and flowchart for queries to Google APIs.
4. Create the OAuth 2.0 project folder in Corezoid.
5. Create Google credentials.
6. Obtain the Google code using your credentials.
7. Create the Corezoid process for generating the Google API access token.
8. Create and configure an API Call node in the token generation process.
9. Generate a Google API access token.
10. Create the Corezoid process for refreshing the Google API access token.
11. Configure the access token refresh in the token refresh process.
12. Create and configure a state diagram for access token storage.

Create a Project on the Google Cloud Console

1. Go to console.developers.google.com and create a new project:

• On the Google Cloud main page, Click the Select a project dropdown menu.

• In the Select a project window, click New project.

2. Name your project and click Create.

Enable the Google OAuth API

In the Google Cloud main dropdown menu:

1. Open the APIs & Services item and select Enabled APIs & Services.

2. Click +Enable APIs & Services.

3. From the list of APIs select the Gmail API, for example.

• After selecting the API, click Enable.

General flowchart and requirements for queries to Google APIs

All queries to Google APIs require authorization via the OAuth 2.0 protocol.

A general flowchart illustrating interactions between Google services via OAuth 2.0 is as follows:

Each request to API must contain the following parameters in the Header:

Authorization: Bearer {{ACCESS_TOKEN}}

ACCESS_TOKEN is used for authorization of queries and storage of additional information about the user (user_id, user_role, or any other; this information is also called payload). In other words, the token is required to verify your account data before requesting the Google API.

ACCESS_TOKEN storage process should be made unified so that you could use the ACCESS_TOKEN in other projects.

You will be able to obtain ACCESS_TOKEN by adding a Set Parameter node with a structure of

{{conv[process_id].ref[reference_of_request].name_of_the_parameter_the_ACCESS_TOKEN_is_located_in}}

in the process required, for example:

{{conv[4].ref[gmail].ACCESS_TOKEN}}

To do this, you must create 3 unified processes in Corezoid:

• Сreate Token: a process for calling API to generate the ACCESS_TOKEN.
• Refresh Token: a process for refreshing the ACCESS_TOKEN
• Token Storage: a state diagram to store and refresh an ACCESS_TOKEN obtained.

The processes will interact with the Google OAuth 2.0 as shown in the figure below.

At his point, you have completed the Google project creation stage. Now, you can proceed to the following steps:

• Create the folder for your OAuth 2.0 project in Corezoid.
• Create Google credentials and obtain the user code.
• Configure processes in Corezoid to obtain, refresh and store the ACCESS_TOKEN.

Create the OAuth 2.0 Project Folder in Corezoid

Create a folder named Google OAuth 2.0 to work with projects more conveniently.

Create Google Credentials

1. On the Credentials page of the Google developers console, click Create Credentials and select OAuth client ID.

2. Click Configure consent screen to proceed with credentials creation.

3. In the Select an API dropdown list select Gmail API, select User data in the type of requested data and click Next.

4. Fill out the fields in the App information and Developer contact information sections.

5. (Optional) Add scopes for your credentials

6. In the Application type dropdown list, select Web application and enter the name for your application in the Name field.

7. Enter the redirect URI, for example http://localhost:3000/auth/google/callback.

8. On the Download your credentials page, download the credentials you've created and click Done to finish.

Obtain the Google Code

1. In your web browser, enter the following URL:

https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=http://localhost:3000/auth/google/callback&response_type=code&access_type=offline&scope=https://mail.google.com&client_id=client_id

where:

• redirect_uri: the redirect URI that you've entered at step 7 when creating credentials http://localhost:3000/auth/google/callback.
• response_type: use code to obtain the code value (step 3).
• access_type: use offline.
• scope: the Google API you want to gain access to. As we use the Gmail API in this tutorial, the value is https://mail.google.com.

• client_id: the OAuth Client ID you've obtained when creating your Google credentials (step 8).

2. On the Google Account access confirmation page, click Allow.

3. The page with the unable to connect message will open. Copy and save the page URL to get the OAuth code.

Create the Process for Access Token Generation

Go to the OAuth 2.0 project folder that you've created in Corezoid and create the Create access token process for generating the ACCESS_TOKEN using Google API.

Create and Configure an API Call Node for Token Generation

1. In the Create access token process, add an API Call node, which will call Google OAuth 2.0 API for generating ACCESS_TOKEN.

2. After adding the node, click it and fill out the URL field together with the required request parameters in the Parameters section:

2.1 Enter the URL:

https://oauth2.googleapis.com/token

2.2 Set the following request parameters:

• Request format: Default
• Request method: GET
• Content-Type: Application/Json

2.3. In the Parameters section, add the following:

{
    "redirect_uri": "http://localhost:3000/auth/google/callback",
    "grant_type": "authorization_code",
    "client_id": "{{client_id}}",
    "code": "{{code}}",
    "client_secret": "{{client_secret}}"
}

2.4 In the Other section, select the Header parameters box and add the following header:

{
    "Authorization": "Bearer {{conv[@config].ref[google].access_token}}"
}

3. To ensure automatic parameter entry upon manual request for ACCESS_TOKEN generation, add the credentials parameters to the process tasks:

3.1 Click the Task parameters icon in the Process editor window.

3.2 In the Task parameters menu, click Add parameter, add the client_id, code, client_secret parameters and click Save.

The API Call you've configured is ready to request a call which will result in obtaining ACCESS_TOKEN from Google OAuth 2.0 API.

Generate the Google Access Token

In the configured Create access token process, send a new task.
If ACCESS_TOKEN is created successfully, your request will be in the Final node. Click it to look through the contents of the request that contains access_token as one of its parameters.

Create the Access Token Refresh Process

In your process folder, create a new process called Refresh Token to configure the Google access token refresh.

Configure the Token Refresh

According to the Google OAuth protocol, the token expiration time is 1 hour; therefore, a Google API call must be set up for token refresh.

1. To refresh ACCESS_TOKEN, in the Refresh Token process add two nodes - Condition and API Call.

   Condition is required to transfer a request to the API Call node for the token to be refreshed under the grant_type == refresh_token condition.

   Add refresh_token receipt verification to the grant_type parameter in the Condition node to do this.

2. The API Call node is required to call Google API for a token refresh after this condition.

To do this, enter https://oauth2.googleapis.com/token in the API URL
and set the following values in the API Call node settings:

Request format: Default  
Request method: POST
Content-Type: Application/X-Www-Form-Urlencoded

Add the following in the Parameters section:

{
    "refresh_token": "{{refresh_token}}",
    "grant_type": "refresh_token",
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}"
}

The process for ACCESS_TOKEN refresh has been created successfully!

Create and Configure the Token Storage State Diagram

1. A mechanism for storing the generated/refreshed ACCESS_TOKEN should be created to avoid calling the Create Token and Refresh Token processes each time a request is made to Google API. You can use a state diagram for this purpose.

1.1. Create a state diagram named Token Storage.

Token Storage state diagram is designed for storage of a request with active ACCESS_TOKEN.

You will call a Create/Refresh Token process for ACCESS_TOKEN refresh from this state diagram.

1.2. Add a Copy Task node in the Token Storage state diagram to call the Create/Refresh Token process.

1.3. Enter the following in the Reference field:

{{root.ref}}

1.4. Add the following in the Parameters section:

{
    "refresh_token": "{{refresh_token}}",
    "grant_type": "refresh_token",
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "code": "{{code}}"
}

You will create a request for ACCESS_TOKEN generation in the Create/Refresh Token process, and a copy of this request will be transferred to the Token storage state diagram.

When it is time to refresh ACCESS_TOKEN during the Token storage process, the request will be passed through the Copy Task node for ACCESS_TOKEN refresh and wait for modification in the next Set State node.

1.5. In the Set state node, add Condition access_token == to check the presence of the access token parameter after modification of the request. If an empty parameter is received, the request will be transferred to the final node Token is not refresh (you may assign another name to the node).

1.6. Add a wait-for-response timer in the same Set State node. To do this, click Additionally and set up a checkmark next to the Limit the time of the task in the node. Set a minimal time of 30 seconds as shown below. If a response from the Create/Refresh Token is not received in the state diagram within 30 seconds, the request will be passed to the Final node called Timeout create token.

2. According to the Google OAuth protocol, token expiration time is 1 hour, therefore it is necessary to set up a token refresh cycle in the prescribed time.

To do this, click the Limit the time of the task in the node in the Active token node and set a timer for 1 hour.

Final view of the Token Storage process with nodes involved is shown below.

3. In order to transfer the ACCESS_TOKEN generated, go to the Create/Refresh Token process in the Token Storage state diagram. Add the Copy Task node after the Create access token node.

3.1. In the Copy Task node, activate the Token Storage state diagram in the Process field.

3.2. In the Reference field, enter the following: gmail.

3.3. Add the following in the Parameters section:

    {
        "access_token": "{{access_token}}",
        "expires_in": "{{expires_in}}",
        "client_secret": "{{client_secret}}",
        "code": "{{code}}",
        "client_id": "{{client_id}}",
        "refresh_token": "{{refresh_token}}"
    }

4. To refresh the ACCESS_TOKEN in the Token Storage state diagram, add the Modify Task node next to the Refresh access token node in the Create/Refresh Token process.

   4.1. In the Modify Task node, activate the Token Storage state diagram in the Process field.

   4.2. In the Reference field, enter the following:

   {{root.ref}}
   

   4.3. Transfer the following in the Parameters section:

    {
        "refresh_token": "{{refresh_token}}",
        "access_token": "{{access_token}}",
        "expires_in": "{{expires_in}}"
    }

Where: 
- `refresh_token` - token to refresh **ACCESS_TOKEN**.
- `ACCESS_TOKEN` -  token to access Google API.
- `expires_in` - **ACCESS_TOKEN** expiration time.

After the entire project consisting of 1 process and 1 state diagram is assembled, you can work with active ACCESS_TOKEN.

To do this, repeat the point of getting CODE and create a new request for ACCESS_TOKEN generation in the Create/Refresh Token process, thereby launching a process of the token storage and refreshing in the Token Storage state diagram.

If ACCESS_TOKEN is created successfully, your request will be in the Active token state. Click it to review the request that contains access_token as one of its parameters.

Interaction of the Corezoid processes with the unified Token Storage state diagram and Google APIs is shown below.

You can use the ACCESS_TOKEN obtained in all the processes of your company to work with any Google APIs by adding it to the Header as follows:

Authorization: Bearer {{conv[DIAGRAM_ID].ref[REFERENCE].access_token}},

where:

DIAGRAM_ID - ID of the Token Storage state diagram.

To obtain the DIAGRAM_ID proceed as follows:

1. Go to the Edit mode in the Token Storage state diagram
2. Click the Start node inside the diagram
3. Copy the number in the ID process line in the Connection data section

REFERENCE - assigned by you at step 5. In our case, this will be “gmail”.

Example of Google API call via API Call node using Google OAuth 2.0:

Congratulations! You have learned how to create processes and use a state diagram to integrate Google OAuth 2.0 authorization.