Configure OAuth connections in Control Room

OAuth is a secure, efficient, and easy-to-use open standard authorization protocol that helps you protect user privacy. It defines how to delegate or provide authorization to applications to access resources (such as remote or third-party APIs, or user data) without the user having to provide their username and password credentials. Currently, this configuration is only required if you are completing the PixieBrix connection setup.

Note: The Salesforce mark and logo, the Microsoft SharePoint mark and logo, the Apigee mark and logo, the ServiceNow mark and logo, and the Genesys mark and logo are trademarks or registered trademarks of Salesforce, Inc., Microsoft Corp., Google LLC, ServiceNow, Inc., and Genesys, respectively, and are used for identification purposes only.

For more information, see OAuth 2.0.

OAuth supports a set of predefined methods called grant types. Each grant type has specific requirements and flow depending on the scenario. Control Room OAuth connections support the following grant types:

  • Authorization Code Flow
  • Authorization Code Flow with Proof Key for Code Exchange (PKCE)
  • Client Credentials Flow
Note: In scenarios where the user authorization and consent are not required or a token is shared across multiple bots (such as unattended bot runs) ensure that you use a shared token (the Save login credentials option) to run unattended automations. For more information, see Create OAuth connection.

OAuth architecture

With OAuth connections managed in the Control Room, you can manage connections and token lifecycle centrally through the Control Room. Additionally, you can securely store the tokens required to authenticate and authorize access to enterprise applications without having to obtain them at every automation run-time. The OAuth connections that are configured in the Control Room are outbound towards the corresponding enterprise applications for authentication purposes.

The Control Room supports the following options:
  • Create and manage connections for every SaaS application used within automations.
  • Manage token lifecycle for shared and user-specific tokens.
  • Secure token storage by using industry standard encryption levels.
  • Grant permissions and role-based access to manage and consume the OAuth connections within automations.

OAuth workflow example: The following example describes how to configure, create, and use the OAuth connection:

  1. Configure enterprise applications
  2. Create OAuth connection
  3. Use OAuth connection

Image showing OAuth connection workflow

Roles and responsibilities: Administrators perform the following tasks:
  1. Create a connection for an enterprise SaaS application.
  2. Enter the authentication details such as: client ID, client secret, authorization URL, and so on.
  3. (Optional) Save the login credentials and test the connection.
  4. Invite roles to use this connection or authenticate for unattended Bot Runners.
  5. Save and manage the connection.

See: Create OAuth connection.

Pro developers or citizen developers perform the following tasks:
Note: To build and execute an API bot successfully, pro developers or citizen developers need to authenticate to the enterprise application unless the administrator has saved the login credentials for the developers (users) to use the connection.
  1. Create an API Task or Task Bot.
  2. Add authentication action for packages.
  3. Select the authentication type (Control room OAuth connection), connection name, and enterprise application information.

See: Use OAuth connection.

OAuth tokens

OAuth provides the following token types:

Access token
A long string of characters that serves as the credential used to access protected resources.
Refresh token
A long-lived special token used to obtain a new access token when the existing access token expires. The refresh token provides a short-lived access token instead of collecting credentials from the user every time a new access token is required. The Control Room uses the refresh token to get a new access token from the authorization server (AS).

When using OAuth, the access token and refresh token are returned in the same response during the token exchange process called Access Token Response.

OAuth tokens in Control Room

The following types of tokens are used in the Control Room:
  • Shared: The shared token type is typically used to run unattended automations where user authentication or consent is not required. To configure and use this token type in the Control Room, you must configure the following options:
    1. In the Manage > OAuth connections section, a user with the Manage connections permission can create OAuth connections. Such a user must select the Save login credentials option in the Test connection and save credentials screen when creating a connection so that a shared token is generated. See Create OAuth connection.
    2. When a user is using this connection in their bots, the user must select the Shared token type in the Pick a connection option. See Use OAuth connection.
  • User-specific: The user-specific token type is typically used to run attended automations where user authentication or consent is required. To configure and use this token type in the Control Room, you must configure the following options:
    1. In the Manage > OAuth connections section, a user with the Manage connections permission can create OAuth connections. Such a user must not select the Save login credentials option in the Test connection and save credentials screen. Instead, the user must invite roles to use the connection by selecting the appropriate roles in the Invite roles screen. See Create OAuth connection.

      Users who are part of the roles get notified about the assigned connection if they have subscribed to event notifications. See Notifications.

    2. The user who is using the User-specific connection in their bots must authenticate the connection in the My settings > OAuth connections section before using the connection. See Authenticate user-specific OAuth connections.
    3. When the user is using this connection in their bots, the user must select the User-specific token type in the Pick a connection option. See Use OAuth connection.

Benefits of integrating OAuth with Control Room

When you integrate OAuth with the Control Room, you:

  • Provide a secure and standard model for automations to authenticate and authorize enterprise applications.
  • Eliminate the need to manually enter the credentials at runtime or hard code the credentials in automations.
  • Ensure that the access tokens are always valid and available for automations at runtime by obtaining them before they expire; therefore, eliminating the need for users to go through the authentication process to obtain them.
  • Avoid repetitive task of configuring the OAuth parameters for every automation using the OAuth connection. The connections are referenced in automations using the enterprise application provider type.

Token lifecycle management

All access tokens have an expiration time dictated by the authorization server (AS). Tokens are refreshed using the token refresh mechanism to extend the token validity (by issuing a new token). With a centralized approach, the Control Room manages the token lifecycle and validates each token before a bot execution.