Connections contain the information necessary for the steps in your integration to connect to third-party apps and services. They're a special type of config variable that is made up of fields for things like usernames, passwords, API keys, OAuth 2.0 secrets, host endpoints, API versions, and more - whatever a component needs to know to connect to an outside service.
When you add a step to your integration that requires a connection, that step will be bound to a connection config variable that represents that connection. If a connection config variable for that component doesn't exist yet, a new one will be created. One connection config variable can be used for multiple steps (so, all of your Amazon S3 steps can reference a single connection config variable).
The config variable that is referenced will contain the information necessary for the step to connect to the outside app or service. You can provide default values for the connection's input fields, or you can choose to have customers enter their own values when they deploy an instance of the integration.
Each field of a connection config variable can be marked "customer visible" or not by clicking theicon. If a field is "invisible" to customers, you must set a default value for that field.
When your team member configures an instance for a customer, or the customer enables the integration for themselves, they are prompted to enter values for each connection input field.
You can click theicon to see logs related to that particular connection. The connection will be marked with a green if the connection has been used successfully in an execution of the instance, yellow if it has been configured (but not used), and red if the component using the connection threw a connection-related error.
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.
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 for Prismatic is https://oauth2.prismatic.io/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.
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 Config Variables tab 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 theicon. 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.
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 thebutton to the right of the connection config variable.
When you disconnect an OAuth 2.0 connection, two things (and one optional thing) happen:
- Prismatic stops periodically refreshing the access token
- Prismatic deletes the access and refresh tokens from its database, so steps can't reference it
- [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:
If you need to access some connection values in a code component, you can by referencing the connection config variable. See the Code Component Usage article for more information and an example.
If you're writing your own custom component, you can declare a new connection type that contains any set of fields (host URL, username, password, API key, etc). You can also create OAuth connections and override field names (an app might call a "Client ID" an "App ID" for example). See the Writing Custom Components article for more information and examples.