Automating business processes on a cloud environment such as Nintex Workflow Cloud (a.k.a NWC) rely heavily on its “connectors” the workflow platform is offering. This could be a connection for an event trigger, reading or writing to an environment that is external to the NWC. In the event if the connector has not yet made available, one could still connect to external environment such as Google, Facebook, Microsoft, etc. via the “call a web service” workflow action. For any platform on a cloud environment to connect to other cloud services, gaining authentication and access to other cloud services becoming critical before one service could communicate to the others. This is where the OAuth becoming common open standard for authorization among the cloud services.
This post provides a step by step sample configuration on how to get the NWC access the REST API of google drive using the OAuth 2.0 authentication.
Before we get into the required setup, let us take a look at a sample endpoint of the Google Drive API, we will look at one fairly straight forward endpoint to start – drive.files. The REST API call might look like the following, though you’ll need to specify your own access token:
GET /drive/v2/files HTTP/1.1Authorization: Bearer ya29.Ci9_A_SXTtG9QpxFS2gqKqHbAhX3QI68AHhTTl4vboNz_hItW2YYzy53FrdoRfBGGQHost: googleapis.com
The Oauth “access_token” to be provided following the “Authentication: Bearer” in this call is the required to gain access to the resources. (Note: A complete OAuth 2.0 steps include Obtain OAuth 2.0 credentials, Obtain access token, sending of access token to API, and refresh access token if necessary could be referenced from Google’s Oauth 2.0 Overview)
As access token to an application has limited life time, the automated process will need to verify if an access token has expired, and will need to refresh the access token with the Refresh Token obtained. Here is how the actual request might look like to exchange or refresh for an Access Token:
HOST /oauth2/v4/token HTTP/1.1Host: www.googleapis.comContent-Type: application/x-www-form-urlencodedclient_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}&grant_type=refresh_tokenCalling Drive API from NWC
The diagram below is a sample NWC workflow I’ve created to call the Google Drive API, I will explain each of the workflow action and its configuration in the following table:
| Action Number | Action Name | Description | Sample Configuration |
|---|---|---|---|
| 10 | Set a variable value | Create and set the variable to the Access Token (please follow following sections on how to obtain Access Token and Refresh Token). This variable will be used and included in the API call later. | |
| 20 | Branch by stage | Defining two branches, one for the normal API call, the other to Refresh Token in case it expired. | |
| 30 | Call a web service | Calling the Google Drive API endpoint, in this example, I am calling the /drive/v2/files endpoint to my folderID.Request Headers to be included here is the Authorization with format shown:Authorization: Bearer <Access Token>The Response Content will have below error if the Access Token has expired: { “error”: { “errors”: [ { “domain”: “global”, “reason”: “authError”, “message”: “Invalid Credentials”, “locationType”: “header”, “location”: “Authorization” } ], “code”: 401, “message”: “Invalid Credentials” } } | |
| 40 | Query JSON | In my example, I am using Query JSON to parse or return the “message” of the suspected returned JSON content, which should be the “Invalid Credentials” value from the sample JSON content returned in the workflow action before this. | |
| 50 | Branch by condition | The “Branch by condition” action to verify if the returned Response Content has the access related error(s). I should be checking against the Error code instead of the Error Message, unfortunately there is a bug the time this workflow is being tested, if I check against the $.error.code with the “equals” operator against value 401. | |
| 80 | Call a web service | When “Refresh Token” branch is called, we will need to Refresh the Access Token using the Refresh Token obtained in previous steps.Please refer to the Using a refresh token section of the Using OAuth 2.0 for Web Server Applications guide for more details on the Refresh Token API. | |
| 90 | Query JSON | Parse the returned JSON with Query JSON action and assigned the refreshed Token to the variable to be used by the API Call. |
Obtain OAuth 2.0 credentials from the Google API Console
1. Select Create project link from the Project Menu
2. Give your project a Project Name and fill up other details as necessary
3. On the Credentials page, create an Oauth client ID credential.
4. Fill in the requested information on the Configure consent screen page, and click Save to return to the Credential screen.
5. Select an Application type (i.e. Other in my example), and provide any additional information if required.
6. Click Create
7. The result of this process will be a Credential with Client ID and Client Secret as shown.
Obtain an access token from the Google Authorization Server
- One of the options to get the Access Token is via the OAuth2 Playground at this link, where we will obtain the access token and refresh token.
- Click the gear icon in the upper right corner and check the box labelled Use your own OAuth credentials (if it isn’t already checked).
- Enter the OAuth2 client ID and OAuth2 client secret obtained in previous step.
4. In the section labelled Step 1- Select & authorize APIs, select APIs you would like to access from NWC (i.e. I have selected https://www.googlezpis.com/auth/drive in my case).
5. You will be prompted to grant access and authorization
6. In the tab labelled Step 2 – Exchange authorization code for tokens. Click Exchange authorization code for tokens.
7. This will get you the Refresh token and Access Token.
8. Copy the Refresh token and Access Token, which we## will need it in the API call in NWC workflow.