Deploying Instances with Credentials

At Prismatic, we're pretty big fans of The Twelve-Factor App methodology for software development. One of the key concepts of building a proper Twelve-Factor App is to enable data-driven configuration. It's important for the same app to be deployable to many distinct environments with different configurations. In the world of integration development for B2B software companies, that translates to writing an integration once and deploying it to multiple customers whose configurations differ from one another.

We've previously talked about deploying instances of integrations to customers using unique customer-specific configuration variables. Today I'd like to look at a parallel topic: deploying instances of integrations with customer-specific credentials. In this second of a two-part series on credentials, let's walk through deploying an integration that requires some customer-specific credentials to run.

If you missed it, check out the first part of the series on handling credentials in custom components.

Our "Reverse Geocode" Integration

For this post, let's suppose we've created an integration in Prismatic that pulls an image from a Dropbox account, finds the physical address at which the image was taken, and writes out that address to a file in S3. Our integration has three steps:

1. It pulls down a photo that is saved in our customer's Dropbox account. It uses the OAuth 2.0 authentication flow to authenticate against Dropbox.
2. Using a custom component that takes advantage of Google Maps APIs, it extracts GPS coordinates from the image's EXIF data and reverse geocodes the address where the image was taken. This custom component will require a Google Maps API key.
3. It writes out the physical address where the image was taken to a file that is stored in a AWS S3 bucket. This step uses an access key / secret key pair to authenticate against AWS.

This integration we've built is reusable, meaning it can easily be deployed to multiple customers using their own unique credentials.

Creating Customer Credentials

When it comes time to deploy an instance of this integration to a customer, all we need to do is specify their credentials. Our integration requires three sets of credentials: OAuth 2.0 authentication for Dropbox, a Google Maps API key, and a set of AWS keys for saving a file to S3. So first we need to enter three credentials for our customer:

The AWS keys and Google Maps API key are pretty straightforward, so we'll start with those two. OAuth deserves special attention, so we'll come back to it in a moment.

From within our customer's Credentials tab, we can click + Credential to create a new credential. Let's create our AWS key pair credential first:

After naming our credential and choosing an appropriate authorization method - in this case API Key / Secret, we're prompted to enter our AWS access key and secret key pair:

We can follow the same process to enter a Google Maps API key for our customer - this time we'll choose the authorization method API Key:

Prismatic Handles OAuth 2.0 For You

The last credential we need to create is the OAuth 2.0 credential for the Dropbox step. OAuth is more complex, and deserves some special attention. You're probably familiar with OAuth, even if you haven't developed your own OAuth login flow in an app. Have you ever logged into a website using your Google, Facebook, Twitter or GitHub account? OAuth is handling that login process. It's a process that allows you to authenticate against a service using a third party (or "OAuth provider") like Facebook, Google, etc.

Here's the TL;DR on OAuth's implementation: Within an OAuth 2.0 provider - in this case, Dropbox - we as an integration creator generate a Dropbox client ID and client secret. A user (like one of our customers) passes our Dropbox ID to Dropbox, usually by visiting a Dropbox web page with our ID in the URL. They're then prompted to log in to Dropbox using their Dropbox credentials, like this:

When the user successfully logs in, Dropbox then passes an "access code" back to Prismatic. Prismatic exchanges that access code for an access token and refresh token, which can be used by our integrations to interact with Dropbox on the customer's behalf. Prismatic periodically uses the refresh token to get a new access token. (phew!)

The big advantage of OAuth here is that Prismatic never handles customer's credentials - the customer enters their own credentials on Dropbox's website, and then Prismatic is given a revokable token to use on the customer's behalf. Prismatic handles most of the OAuth flow under the hood. We don't need to worry about exchanging codes for tokens, refreshing tokens, etc. - that's all done for us.

We just need to worry about entering the right thing in a few input fields and Prismatic takes care of the rest. Like our other customer credentials, we need to create a new credential, this time choosing type OAuth 2.0:

Next we'll enter our client ID and client secret that we generated on Dropbox's developer website. We also enter an authorization URL and token URL that we got from Dropbox's docs.

The last step is to enter some valid Dropbox credentials on Dropbox's website. Within the Prismatic web app we have the option to send an email to our customer with instructions on how to authenticate against Dropbox. That's preferable over entering credentials ourselves - that way we don't need to worry about our customers' credentials; they enter them and we never touch them. However, if we instead want to enter credentials ourselves we can follow the link on the bottom of the OAuth2 Authorization page:

Deploying Our Integration to a Customer

Now that we have set up the customer's credentials, we can deploy an instance of our integration to them. After clicking into our customer, we'll tap the + Instance button to create our instance.

Once the instance has been created, let's scroll to the bottom of the instance configuration screen. Using the dropdown menus, we can bind the customer-specific credentials we created to the instance's Dropbox, Google Maps, and AWS S3 steps:

Note in this screenshot that organization-level credentials that I used for testing are also available in these dropdown menus. If there's a set of credentials that is shared by all of our customers (for example, if we use a single Google Maps API key for our entire organization), we could save that API key at the organization level and use that credential for each of our customers' instances. Credentials are very similar to configuration variables in that way - you can set credentials at the customer or organization level depending on whether they are customer-specific, or generic to all of your customers.

That's it! All that's left to do is hit Deploy and Enable, and our instance will be ready to start processing images for our customer. We can repeat that credential process for each of our customers, and can deploy the same integration to other customers using their customer-specific credentials.

Resources on Handling Credentials

We covered a lot in this post. For additional information on credential types, using Prismatic's CLI tool to automate customer credential creation, etc., check out our docs. We also have a quickstart that goes through how to drive integration logic from config variables and connections.