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.

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

  • If the Control Room servers are behind a proxy and external connections have to go through the proxy, then configure forward proxy settings as detailed in Configure forward proxy settings.
  • 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.
    • Although the following table lists the applications that are certified, you can configure your enterprise applications using the Manage > OAuth connections > Create connection by selecting Provider type as Custom.

Examples of key components of OAuth

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

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 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.
    Note: We recommend that you add the offline_access scope, or appropriate refresh token scope, in the Control Room and when configuring your identity provider so that the access token can be automatically refreshed. Otherwise, you will have to manually refresh the token in the Control Room. See Authenticate user-specific OAuth connections.
  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