A Control Room administrator can create OAuth connections for users to use these connections in the authentication action for packages without having to enter any authentication details.

Note: The Salesforce mark and logo, the Microsoft SharePoint mark and logo, the Apigee mark and logo, 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.

Prerequisites

  • Ensure that you are using a user role that has the Manage connections permission enabled for the OAuth Connections feature. See Feature permissions for a role.
  • If you are adding more than one scope, ensure that you separate the scopes using commas.

    Example: api,refresh_token,offline_access

  • Ensure that you have configured an enterprise application and made a note of the Client ID, Client secret, Authorization URL, Token URL, and Scope. See Configure enterprise applications
    Note:
    • Consider the above prerequisites to avoid a connection error.
    • When configuring OAuth, the Scope field is optional. Consult with the identity provider (IDP) to determine the required scopes.
    Table 1. Examples
    Enterprise applications Authorization URL Token URL Scope
    Apigee https://accounts.google.com/o/oauth2/auth?prompt=consent&access_type=offline https://accounts.google.com/o/oauth2/token https://www.googleapis.com/auth/cloud-platform
    Genesys https://login.<yourinstance>.pure.cloud/oauth/authorize https://login.<yourinstance>.pure.cloud/oauth/token Not required
    Google Workspace (Calendar, Drive, Sheets and Gmail) https://accounts.google.com/o/oauth2/auth?prompt=consent&access_type=offline https://oauth2.googleapis.com/token
    • Google Sheets: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/spreadsheets
    • Google Drive: https://www.googleapis.com/auth/drive
    • Google Calendar: https://www.googleapis.com/auth/calendar
    • Gmail : https://developers.google.com/identity/protocols/oauth2/scopes#gmail

      https://mail.google.com/,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.send
    Jira https://auth.atlassian.com/authorize https://auth.atlassian.com/oauth/token offline_access write:jira-work,read:jira-user,manage:jira-webhook,read:jira-work
    Microsoft Entra https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token offline_access,openid,https://graph.microsoft.com/.default
    Microsoft 365 Outlook https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token Authorization code Flow: offline_access,openid,https://graph.microsoft.com/.default
    Salesforce https://<yourinstance>.salesforce.com/services/oauth2/authorize https://<yourinstance>.salesforce.com/services/oauth2/token api,refresh_token,offline_access
    Note: If no scopes are given in the connect command, the connection will use the scope assigned to the user by default.
    ServiceNow https://<yourinstance>.service-now.com/oauth_auth.do https://<yourinstance>.service-now.com/oauth_token.do Not required
    SharePoint https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token https://<domain-name>/AllSites.Manage,offline_access,openid
    Note: The OpenID scope is required only when your apps require the sub claim in the ID token to identify the end-user. Otherwise, this scope is optional.
Note: We recommend that you use refresh tokens that are configured for a longer expiry duration. See Use AuthConfig App to enable OAuth2 services.

Procedure

  1. In the Control Room, navigate to Manage > OAuth connections.
  2. Click Create connection.
  3. In the Connection settings screen that opens, select a Provider type.
    Note: The Callback URL is used in your enterprise application configuration settings to connect to the Control Room.
  4. Enter a unique Connection name to identify the connection.
  5. Optional: Enter a Description for the connection.
    Image displaying the OAuth connection settings page
  6. Click Next.
    The Authentication details screen appears.
  7. Select a Grant type. See OAuth authorization code flow and OAuth client credentials flow.
    Note: If you are configuring for a Google Cloud Platform (GCP) account, select Authorization Code Flow because Control Room managed OAuth connection using Authorization code flow with PKCE is currently not supported.
  8. Enter the Client ID that is provided by the provider for your account.
  9. Enter the Client secret that is provided by the provider for your account.
    Note:
    • After testing or creating a connection, the Client secret field will not be displayed in the user interface, but the backend service will continue to use the stored value. This is an expected behavior.
    • The Client secret field is masked while you enter the value, similar to a password field. This enhances security by preventing the secret from being visible in clear text.
  10. Enter the Authorization URL used to obtain an authorization code for your account.
    Note: For Apigee or Google Cloud Platform (GCP) account, you must append &access_type=offline to the authorization URL. For example: https://accounts.google.com/o/oauth2/v2/auth?prompt=consent&access_type=offline.
  11. Enter the Token URL used to exchange an authorization code for an access token.
  12. Optional: Enter Scope.

    The token expiration time can be set by the identity provider. If the token expires, the Bot uses the Offline_access scope to get a new valid token when triggered, based on the details in the Control Room. See Configure OAuth connections in Control Room.

    Image displaying the OAuth authentication details page
    This information is used as claims (information about the user) in an access token and forwarded to the resource server to limit access.
  13. Click Next.
    The Test connection and save credentials screen appears.
  14. Optional: Select the Save login credentials.
    Note: Use this option only when you want to generate a shared token that allows users to use this connection without providing user authentication and consent. When you select this option, you must select the Shared token type option when using this connection. See OAuth tokens.
  15. Optional: Click Save changes and test connection.
    Image displaying the OAuth test connection and save credentials page
    Note: After you click the Save changes and test connection option and if the connection is successful, the Next button is disabled. Click the Back button, enter the Client secret again, and then click Next. You need not test the connection again unless you have made any changes to the previously provided authentication details.
  16. Click Next.
    The Invite roles screen appears.
  17. Select the roles that you want to invite to use this connection. Only invited roles can use the token in a bot, whether it is private or shared.Image displaying the OAuth invite roles page

    Invite roles action is mandatory if a Bot uses the OAuth connection. This action is optional if an external service will use the OAuth connection.

    Note: Only custom roles are displayed in the list of Available roles.
  18. Click Create connection. An OAuth connection is created.

The following video shows how to create an OAuth connection:

Next steps

Use OAuth connection