OAuth 2.0

OAuth 2.0 is a special type of connection that is ubiquitous in integration development. OAuth 2.0 allows your customers to authorize your integration to perform certain functions on their behalf, without needing to give you their username or password. For example, customers can authorize your integration to fetch their Salesforce leads, create Slack channels, or generate Quickbooks invoices for them.

You've probably come across OAuth 2.0 at some point - any time you click "Log in with my Google Account" or "Log in with Facebook" on a website, that website leverages OAuth to fetch information about you (your email address, friend's list, etc) on your behalf. You don't enter your Google or Facebook credentials into the website. Instead, you enter your credentials on a Google, Facebook, etc. page and the OAuth provider generates a unique code that grants the website a set of your permissions.

In the integration world, it's common to use OAuth to authenticate third-party services. You set up an "OAuth 2.0 App" in a third-party service, like Salesforce, Quickbooks, Jira or Dropbox, and your customers can then click a button, enter their credentials in the OAuth provider, and your Prismatic integration is granted the necessary access to perform actions in the third-party service on the customer's behalf.

How does OAuth 2.0 work?

OAuth 2.0 is a complex protocol, but at a high level the OAuth 2.0 auth code flow works like this:

1. You register with a third-party app. You tell them your app's name, a description, and a callback URL. They give you a client ID and client secret.
2. You send a customer to the third-party app's OAuth service. You include your client ID, a redirect URL, and a list of scopes (permissions) that you want to request.
3. The customer authenticates with the third-party app. They enter their username and password, and the third-party app generates a unique code.
4. The third-party app sends the customer back to your redirect URL, along with the unique code.
5. You send the unique code to the third-party app's OAuth service, along with your client ID and client secret. The third-party app verifies that the code is valid, and if so, responds with an access token and a refresh token.
6. You periodically refresh the access token with the refresh token, and use the access token to make API calls on behalf of the customer.

Creating an OAuth 2.0 "app" in a third-party service

To use OAuth to authenticate users with a third party, you will need to work with the third-party service to create an "OAuth App". Most common SaaS platforms have documentation on how to create an OAuth app, and we link to that documentation on our component docs pages. It's usually found in an "API Access" section of a settings page, or on a page similarly named.

When you configure your OAuth app, you'll likely need to set up an authorized callback URL. That's the URL that the app is allowed to send a special code to when a user authenticates with them. The callback URL depends on the region you use:

Region	Callback URL
US Commercial (default)	https://oauth2.prismatic.io/callback
US GovCloud	https://oauth2.us-gov-west-1.prismatic.io/callback
Europe (Ireland)	https://oauth2.eu-west-1.prismatic.io/callback
Europe (London)	https://oauth2.eu-west-2.prismatic.io/callback
Canada (Central)	https://oauth2.ca-central-1.prismatic.io/callback
Australia (Sydney)	https://oauth2.ap-southeast-2.prismatic.io/callback
Custom Domain	https://oauth2.<your-custom-domain>/callback

Also take note of the OAuth app's client ID and client secret. These are sometimes called "App ID", "App Key" or something similar. You'll use those to configure your Prismatic integration's connection.

Within the OAuth app you may also need to configure permissions that can be granted. For example, you can say the an app gives integrations the ability to list files and read files, but not write files, or the ability to generate invoices on behalf of your customer. These permissions in the OAuth world are called scopes.

registering with a third-party can take time

Most third-party services allow you to create an un-verified OAuth app for testing purposes, but require you to go through a verification process before you can use the app in production. The verification process can take days or weeks, so it's best to start the process early. The third-party may require you to provide a privacy policy, terms of service, and other information about your app.

Adding an OAuth 2.0 connection to an integration

Once you have an OAuth 2.0 App configured in a third-party service, add a new connection in your Prismatic integration for the third-party you're integrating with. You can do that by either adding a step for the third-party (add a Salesforce step to automatically create a Salesforce connection, etc.), or open the Configuration Wizard Designer and create a new config variable of type Connection.

Enter the client ID and client secret that you noted in the previous step. You may need to enter an Auth URL or Token URL if those are different for different tenants. You can find those in the third-party apps' docs. There's a good chance the URLs are the same for everyone, so are hidden in the Prismatic UI. Mark fields that you don't want your customers to see "hidden" by clicking the icon. You probably want to hide your client ID and client secret.

If the app you're connecting with allows you to override scopes on a per-connection basis, you'll be prompted for scopes here, too.

Custom OAuth 2.0 redirects

Normally, a user who completes an OAuth 2.0 flow finds themselves on an "Authorization Complete" screen - https://app.prismatic.io/app/authorization-complete/.

If you would like to customize where a customer is redirected after a successful or failed OAuth 2.0 flow, toggle the Custom OAuth Redirects option on the connection and enter URLs for OAuth Success Redirect URI and OAuth Failure Redirect URI.

Your user will be redirected to those URLs, with URL search parameters representing:

• The instance's instanceId and instanceName
• The integration's integrationId and integrationName
• The required config variable's requiredConfigVariableId and requiredConfigVariableKey
• The connection's id. For instance-level connections, this will be the instance's config variable ID. For user-level connections, this will be the user-level config variable ID.

Configuring OAuth 2.0 connections

If you've created an integration with an OAuth 2.0 connection, customers will see a CONNECT button button when they enable the integration. When they click the CONNECT button they will be brought to the third-party app's OAuth service, and will be prompted to verify that they want to grant permissions to your integration. Once they are done, they'll see a "Authorization completed successfully" page, which they can close to return to the instance configuration screen.

To change an OAuth connection (for example, if you logged in as the incorrect person when you clicked CONNECT), you can click DISCONNECT and then CONNECT again to reauthenticate against the OAuth provider.

If any problems occur during the OAuth flow (incorrect Auth or Token URL, incorrect scopes, etc), you can view related connection logs by clicking the button to the right of the connection config variable. The connection will be marked with a green lens if the connection has been used successfully in an execution of the instance, yellow lens if it has been configured (but not used), and red lens if the component using the connection threw a connection-related error.

Disconnecting an OAuth 2.0 connection

When you disconnect an OAuth 2.0 connection, two things (and one optional thing) happen:

1. Prismatic stops periodically refreshing the access token
2. Prismatic deletes the access and refresh tokens from its database, so steps can't reference it
3. [Optional] It's not common, but some OAuth 2.0 providers allow you to revoke a token. Quickbooks is a prominent example of an API that supports revocation. If a revocation endpoint is present in a component's connection, Prismatic reaches out to that endpoint to revoke the token with the third-party's API.

To disconnect an active OAuth 2.0 connection, click the DISCONNECT button under the config variable name: