OAuth 2.0 authentication

Use OAuth 2.0 authentication to connect to an API using an OAuth 2.0 flow.

Nintex Automation Cloud supports accessCode (authorization code) and application (client credentials) flows with OAuth 2.0 authentication.

Note: To use OAuth 2.0 authentication, you must register a client in the application you're connecting to. When you register your client, use the following redirect URL: https://us.nintex.io/connection/api/Token.

The following examples use OAuth 2.0 authentication:

How to use OAuth 2.0 authentication

Using access code or authorization code flow

Note: This flow is called "authorization code" in the OpenAPI 3.0 Specification. With Nintex Automation Cloud, you must use the OpenAPI 2.0 Specification value accessCode.

To add OAuth 2.0 authentication to your OpenAPI Specification:

  1. Add a securityDefinitions object before the final closing brace of your OpenAPI Specification.
  2. Create an object inside the securityDefinitions object to define your basic authentication security.
  3. Inside the object:
    1. Add aproperty of type with a value of oauth2.
    2. Add a property of flow with the value of accessCode.
    3. Add a property of authorizationUrl with a value of the endpoint to use to initiate the authentication flow.
    4. Add a property of tokenUrl with the value of the endpoint to use to retrieve the OAuth token at the end of the authentication flow.
  4. Most APIs require you to specify scopes of access for your authentication. To define scopes:
    1. Add the property of scopes to your definition object.
    2. For each scope, add a property with the key of the resource you want to access, and the value of a description of the resource.

      3. Important: You may need to define additional scopes if your API uses refresh tokens. See Ensuring offline access.

  5. Inside the HTTP method of each operation that requires basic authentication, add a security array.
  6. Inside the security array, add an object containing a property with:
    1. The key of the security definition object you created earlier.
    2. A value of any scopes required for this operation (as an array).
Copy 
{
  "swagger": "2.0",
  "host": "api.example.com",
  "schemes": [ "https" ],
  "produces": [ "application/json" ],
  "consumes": [ "application/json" ],
  "paths": {
    "/example": {
      "post": {
        "summary": "Example operation",
        "security": [
          {
            "myOauth": []
          }
        ],
        "parameters": [...],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "securityDefinitions": {
      "myOauth": {
        "type": "oauth2",
        "flow": "accessCode",
        "authorizationUrl": "https://www.example.com/oauth2/auth",
        "tokenUrl": "https://www.example.com/oauth2/token",
        "scopes": {
            "https://www.www/example.com/auth/users": "access to user profiles"
        }
      }
    }
  }
}

Using client credentials or application flow

Note: This flow is called "client credentials" in the OpenAPI 3.0 Specification. With Nintex Automation Cloud, you must use the OpenAPI 2.0 Specification value application.

To add OAuth 2.0 authentication to your OpenAPI Specification:

  1. Add a securityDefinitions object before the final closing brace of your OpenAPI Specification.
  2. Create an object inside the securityDefinitions object to define your basic authentication security.
  3. Inside the object:
    1. Add a property of type with a value of oauth2.
    2. Add a property of flow with the value of application.
    3. Add a property of tokenUrl with the value of the endpoint to use to retrieve the OAuth token at the end of the authentication flow.
  4. Most APIs require you to specify scopes of access for your authentication. To define scopes:
    1. Add the property of scopes to your definition object.
    2. For each scope, add a property with the key of the resource you want to access, and the value of a description of the resource.

      3. Important: You may need to define additional scopes if your API uses refresh tokens. See Ensuring offline access.

  5. Inside the HTTP method of each operation that requires basic authentication, add a security array.
  6. Inside the security array, add an object containing a property with:
    1. The key of the security definition object you created earlier.
    2. A value of any scopes required for this operation (as an array).
Copy 
{
  "swagger": "2.0",
  "host": "api.example.com",
  "schemes": [ "https" ],
  "produces": [ "application/json" ],
  "consumes": [ "application/json" ],
  "paths": {
    "/example": {
      "post": {
        "summary": "Example operation",
        "security": [
          {
            "myOauth": []
          }
        ],
        "parameters": [...],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "securityDefinitions": {
      "myOauth": {
        "type": "oauth2",
        "flow": "application",
        "tokenUrl": "https://www.example.com/oauth2/token",
        "scopes": {
            "https://www.www/example.com/auth/users": "access to user profiles"
        }
      }
    }
  }
}

Where to use OAuth 2.0 authentication

Use OAuth 2.0 authentication in:

  • The securityDefinitions object.
  • The security array of each HTTP method that requires OAuth 2.0 authentication.

Ensuring 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 (for example, via the `implicit` flow or grant type).
  • Nintex Automation Cloud exchanges a refresh token for an access token.

Important:  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.

Security presets

When you add your Xtension to Nintex Automation Cloud, you can specify a security preset. This allows you 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.