Add OAuth2 authentication

In this example, you will create an Xtension A set of instructions for Nintex Automation Cloud to use third-party API functionality with Nintex workflows. An Xtension may include workflow actions, start events, forms or file control. that uses OAuth2 A two-step authorization protocol that both identifies the requestor, and allows a user to grant access to a third-party account without revealing their credentials to the requesting software. to create a task list in Google Tasks. When designing the workflow, you will be prompted to select which Google account to use.

OAuth2 authentication requires Nintex Automation Cloud to provide a client ID and a shared secret with the API A programming interface that defines how software can be interacted with by other software.. The API can then prompt the user to permit a defined scope of access to the user's account without having to give Nintex Automation Cloud any authentication credentials. The client ID and shared secret must be registered with the API in advance

When using Xtensions with OAuth2 authentication, you configure the client ID and secret on the security template when you import the Xtension, so that Nintex Automation Cloud can identify itself securely to the API. When you create the connection The stored authorization credentials for a connector. in the Workflow designer, you will select which account to connect to.

The complete OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. and icon for this example are available here.

Tip: Want the short version? Check out our OpenAPI Specification quick reference for quick definitions of parameter types, authentication, file handling and Specification Extensions.

OAuth2 authentication

To add OAuth2 authentication to an OpenAPI Specification, you:

Register a client ID and secret with the API you want to use
Retrieve the redirect URLs from the client
Define the OAuth2 authentication object inside the security definitions object
Reference to this OAuth2 authentication object inside the HTTP method objects that require authentication

Tip: You can request additional connection information, such as a database name, using x-ntx-connection-properties, and validate your connection when it is created using x-ntx-connection-validation.

Register a client ID and secret

To import the completed Xtension, you must create the client ID and shared secret in a Google Developer account:

If you do not already have a Google Developer Account, create a free account here.
Click the following link to open the Google API console.
Click Enable API and type Task API in the search box.
Click Enable if this API is not already enabled.
Click Credentials in the left hand navigation pane.
Click Create credentials, and select OAuth client ID.
Select Web application.
Type Nintex Automation Cloud connector for Tasks in the Name field.
Click Create.
Record the Client ID and Client Secret somewhere secure. You will need these to import the Xtension into Nintex Automation Cloud.

Define OAuth2 authentication

Step 1: Create the basic OpenAPI Specification

Create an OpenAPI Specification that:

uses the host The domain name of the third-party API's URL.www.googleapis.com
accepts HTTPS and produces application/json
has a post operation A single request to a third-party API. Operations often become actions in the workflow designer. to /users/@me/lists that passes the name of the task list in the body The part of an HTTP request or response that can contain an arbitrary amount of data, such as the content of a form or web page. with a schema that lists the property of title as a string.
responds The return from a third-party API after a request has been made by the client.200 with a schema that returns the title, id and link to the new task list, and the time it was updated.

Copy

 
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Google Tasks"
    },
    "host": "www.googleapis.com",
    "basePath": "/tasks/v1",
    "schemes": [
        "https"
    ],
    "produces": [
        "application/json"
    ],
    "paths": {
        "/users/@me/lists": {
            "post": {
                "tags": [
                    "Task"
                ],
                "summary": "Create a Task List",
                "description": "Create a Task List",
                "operationId": "createTaskList",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "task",
                        "description": "Name of task list",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "properties": {
                                "title": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/list"
                        }
                    },
                    "default": {
                        "description": "Operation Failed"
                    }
                }
            }
        }
    },
    "definitions": {
        "list": {
            "type": "object",
            "properties": {
                "kind": {
                    "type": "string"
                },
                "updated": {
                    "type": "string",
                    "format": "datetime"
                },
                "id": {
                    "type": "string"
                },
                "selfLink": {
                    "type": "string"
                },
                "title": {
                    "type": "string"
                }
            }
        }
    }
}

Step 2: Create the security definitions object.

Create the securityDefinitions object at the end of the OpenAPI Specification, after the definitions object but before the final closing brace. Make sure you add a comma to the end of the definitions object.

Copy

 
"definitions": {
    "list": {
    "type": "object",
        "properties": {
            "kind": {
                "type": "string"
            },
            "updated": {
                "type": "string",
                "format": "datetime"
            },
            "id": {
                "type": "string"
            },
            "selfLink": {
                "type": "string"
            },
            "title": {
                "type": "string"
            }
        }
    }
},
"securityDefinitions": {
    
}

Step 3: Create the OAuth2 authentication definition

Inside the securityDefinitions object, create an object to define the OAuth2 authentication. You can name the security object any name that is unique within the OpenAPI Specification. In this example, we have named it oauth2.

Add a type with a value of oauth2 to define it as OAuth2 authentication, and add a property with the key of flow and a value of accessCode to use the access code method to authenticate.

Note: For security reasons, Nintex Xtensions only supports the accessCode flow.

Copy

 
"securityDefinitions": {
    "oauth2": {
        "type": "oauth2",
        "flow": "accessCode"
    }
}

Step 4: Add the URLs and scopes

Inside the oauth2 object, add the properties for the URLs for the authentication stages and scopes provided by the API. For this example, add:

authorizationUrl with a value of https://accounts.google.com/o/oauth2/v2/auth
tokenUrl with a value of https://www.googleapis.com/oauth2/v4/token
a scopes object, with a property for each resource you want to access, where:
- the key is the resource you want to access: https://www.googleapis.com/auth/tasks
- the value is a description of the resource: access to tasks

The properties below are unique to this example. When creating OAuth2 authenticated Xtensions for other APIs, you will need to use the values provided by the API.

Allow offline access

Ensure your OAuth 2.0 configuration allows Nintex Automation Cloud to retrieve a valid access token at all times. For example:

The authorization server always returns an access token (e.g. via the `implicit` flow or grant type).
Nintex Automation Cloud exchanges a refresh token for an access token.

Note: Using a refresh token may require a specific scope, such as `offline_access`. You will need to define this scope in your security definition to use the refresh token. Refer to the documentation for your API for more details.

Copy

 
"securityDefinitions": {
    "oauth2": {
        "type": "oauth2",
        "flow": "accessCode",
        "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
        "tokenUrl": "https://www.googleapis.com/oauth2/v4/token",
        "scopes": {
            "https://www.googleapis.com/auth/tasks": "access to tasks"
        }
    }
}

Step 5: Add a security array to the HTTP method object

Inside the HTTP method object, create a security array.

Copy

 
"paths": {
    "/users/@me/lists": {
        "post": {
            "tags": [
                "Task"
            ],
            "summary": "Create a Task List",
            "description": "Create a Task List",
            "operationId": "createTaskList",
            "produces": [
                "application/json"
            ],
            "security": [
                
            ]
        }
    }
}

Step 6: Add the security object reference to the array

Inside the array, reference the security object you defined earlier by using its name as the key, and adding an array of the resource paths you defined as keys in the scopes object.

Copy

 
"paths": {
    "/users/@me/lists": {
        "post": {
            "tags": [
                "Task"
            ],
            "summary": "Create a Task List",
            "description": "Create a Task List",
            "operationId": "createTaskList",
            "produces": [
                "application/json"
            ],
            "security": [
                {
                    "oauth2": [
                        "https://www.googleapis.com/auth/tasks"
                    ]
                }
            ]
        }
    }
}

The OpenAPI Specification

This is the complete OpenAPI Specification that OAuth2 to create a new task list in Google Tasks.

Copy

 
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Google Tasks"
    },
    "host": "www.googleapis.com",
    "basePath": "/tasks/v1",
    "schemes": [
        "https"
    ],
    "produces": [
        "application/json"
    ],
    "paths": {
        "/users/@me/lists": {
            "post": {
                "tags": [
                    "Task"
                ],
                "summary": "Create a Task List",
                "description": "Create a Task List",
                "operationId": "createTaskList",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "task",
                        "description": "Name of task list",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "properties": {
                                "title": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/list"
                        }
                    },
                    "default": {
                        "description": "Operation Failed"
                    }
                },
                "security": [
                    {
                        "oauth2": [
                            "https://www.googleapis.com/auth/tasks"
                        ]
                    }
                ]
            }
        }
    },
    "definitions": {
        "list": {
            "type": "object",
            "properties": {
                "kind": {
                    "type": "string"
                },
                "updated": {
                    "type": "string",
                    "format": "datetime"
                },
                "id": {
                    "type": "string"
                },
                "selfLink": {
                    "type": "string"
                },
                "title": {
                    "type": "string"
                }
            }
        }
    },
    "securityDefinitions": {
        "oauth2": {
            "type": "oauth2",
            "flow": "accessCode",
            "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
            "tokenUrl": "https://www.googleapis.com/oauth2/v4/token",
            "scopes": {
                "https://www.googleapis.com/auth/tasks": "access to tasks"
            }
        }
    }
}

Create the workflow

Step 1: Add your Xtension

Import the OpenAPI Specification you created into Nintex Automation Cloud:

Open your Nintex Automation Cloud tenancy.
Click Xtensions in the dashboard to open the Xtensions page.
Click in the Private connector list.
Click Choose a file. Navigate to the OpenAPI Specification on your computer.
Wait for Nintex Automation Cloud to validate the file.
Click Next.

Nintex Automation Cloud detects the OAuth 2.0 security template.
Type the Client ID in the Client ID field.
Type the shared secret in the Client Secret field.
Copy the Redirect URL: you will need to add this to your OAuth credentials:
- US tenants: https://us.nintex.io/connection/api/Token.
- EU tenants: https://eu.nintex.io/connection/api/Token.

Click Next.

Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
Click Publish.

Security presets

The Security section offers presets you can use to connect with specific third-party platforms more easily, by pre-filling some required fields and configurations. Third-party services you can use presets for include:

Azure Active Directory version 1
Azure Active Directory version 2
Google
Microsoft Graph (leverages Azure Active Directory v1)

Note: It is strongly recommended to use Generic OAuth 2 for Microsoft Graph APIs such as Microsoft Outlook.

Salesforce
SharePoint Online

If you are not connecting to one of these third-party services, you should select the Generic OAuth 2 option.

Step 2: Authorize the redirect URL

The API will only accept requests that redirect to URLs that have already been authorised for the OAuth2 credentials. To authorise the redirect URL:

Open the Credentials section of the Google Developer Console.
Edit the OAuth2 credentials you created earlier.
Paste the Redirect URL you copied into the Authorized redirect URIs field.
Click Save.

Step 3: Create the workflow

Create a workflow that prompts the user for the name of the new task list, and creates it in Google Tasks.

For more information on creating workflows, see the Workflow Designer.

To create the workflow:

Click Create workflow in your Nintex Automation Cloud tenancy.
Configure the Start event to be a Public web form with one text variable for the name of the new task list.
For more information on designing forms in Nintex Automation Cloud, see Design a form.
Drag the Create a Task List action after the Start event.
Create the connection.
Select the Google account to connect to.
Click Allow.
Configure the Create a Task List action to use the new task list name from the web form as the Task Title.
Click Test to test the workflow.
Save or publish the workflow.

Tip: If you want to troubleshoot an Xtension, select Development as the Assigned Use when you publish the workflow. Development workflows display more detailed error messages in their instance details. Republish your workflow as Production when you're ready to use it.