Authorization Credentials

Overview

Many services that Prismatic components connect to require credentials. SFTP servers might require basic auth username/password or an SSH key, services like Dropbox require OAuth2 tokens, and HTTP endpoints often require an API key. Credentials and keys are not something you want to store in plain text, and you may not want your customers to be able to see organization-wide credentials at all.

Prismatic provides a credential manager for storing sensitive credentials at the organization or customer level. They are stored encrypted at rest with a unique encryption key per tenant, and are encrypted in transit when transferred over a network.

For a quickstart on using credentials in an integration, click here.

Authorization Methods

Prismatic components can use a variety of authorization methods (credential types) to interact with external services.

API Key / Secret

API Key / Secret is used by components to access services that require a key/secret pair. For example, AWS Authorization requires an access_key_id and secret_access_key, which can be placed in the api_key and api_secret fields respectively.

Key: api_key_secret

Fields: api_key and api_secret.

Basic Auth

Basic Auth is generally used for HTTP or FTP(S) transactions. A username and password are presented in the form of an HTTP header, which an endpoint accepts or rejects.

Key: basic

Fields: username and password.

Private Key Authorization

Some components, like SFTP, may use public/private key pairs to perform authorization. A username and the private key portion of the key pair can be stored in Prismatic's credential store.

Key: private_key

Fields: username and private_key.

API Key Authorization

An API key is a single token (often a JWT token or similar) that contains signed user information and can be exchanged for authorization to a resource.

Key: api_key

Fields: api_key

OAuth 2.0 Authorization

Many outside software providers use the OAuth 2.0 to grant access to resources. OAuth is appealing because you don't need to handle customers' credentials, so customers won't be motivated to send their credentials to you in an insecure manner. Instead, you configure client ID, client secret, authorization scopes, and authorization and access token URLs, and your customers then enter their credentials separately.

Key: oauth2

Fields: client_id, client_secret, scopes, auth_uri, and token_uri

For More Information: The OAuth 2.0 flow

Should I Create Organization or Customer Credentials?

You should create credentials at the organization level if multiple customers will need access to those credentials. For example, if there is a shared API key that all of your customers will use to access a resource, you will want to create a credential at the organization level.

If credentials are customer-specific, you will want to create the credential at the customer level. For example, you might have AWS accounts for each of your customers. You would create an AWS credential for each customer at the customer level to handle AWS-related actions.

Creating New Credentials

Credentials can be organization-wide or customer-specific. To create new credentials you will need to know whether you want the credentials to be stored at the organization or customer level, what type of credentials you wish to store (reference the authorization method key above), as well as the credentials themselves.

To create credentials at the organization level, click the Settings link on the left-hand sidebar, and then select the Credentials tab.

To create credentials at the customer level, click Customers on the left-hand sidebar, choose a customer, and select the Credentials tab.

Click the + Credential button on the top-right side of either screen.

After entering a name for your credentials and selecting an authorization method, you will be prompted to enter your credentials. Input fields on this page will change based on what authorization method you chose.

Listing Credentials

To view credentials for the organization, click the Settings link on the left-hand sidebar, and then select the Credentials tab.

To view credentials for a specific customer, click Customers on the left-hand sidebar, choose a customer, and select the Credentials tab.

To view all credentials for all customers, click the Credentials link on the left-hand sidebar.

From any of these credentials pages, you can filter credentials by label using the search bar on the top of the page.

Credentials with incomplete setup (missing fields; incomplete OAuth 2.0 flow, etc) will be marked with a red bar on the left-hand side.

Updating Credentials

From one of the two credential listing pages, select a credential. Within this page you can set new values for Username, API Key, etc., depending on the credential's authorization type. For security reasons, stored credential values are not shown on this page after saving a credential.

Deleting Credentials

From any credential list page, click a credential. Select the credential's Summary tab and click Delete Credential. Type the name of the credential and click REMOVE CREDENTIAL to confirm deletion.

Testing Credentials

Credentials can be tested using the integration designer.

For More Information: Testing Credentials in Integrations

Using Credentials in an Instance

When deploying an instance of an integration, you will be prompted to bind stored credentials to various steps of your integration. For each step that requires authorization, select a set of credentials to pass into that step's component.

Not all steps need credentials

It is not necessary to fill in all drop-downs. Some actions, like AWS S3 or Dropbox actions, require credentials, but for other actions credentials are optional or not applicable.

The OAuth 2.0 Flow

OAuth 2.0 is complex. Writing an OAuth client outside of Prismatic involves managing a callback URL that you host, exchanging authentication codes for authentication tokens that expire, juggling token renewals, etc. Prismatic takes care of these complexities for you. This section describes generally how to set up OAuth 2.0 credentials for a customer, and the next section gives a specific example using Dropbox's OAuth 2.0 flow.

First, you will need to create an "app" with your desired OAuth provider (Facebook, Twitter, Google, Dropbox, etc., are all similar in this respect). Your OAuth provider will generate a client ID and client secret, though some providers call these different things (like "app key" and "app secret"). You will need to make note of this client ID and secret.

Next, you will need to add https://oauth2.prismatic.io/callback to the list of of allowed redirect URIs for your OAuth app. This will permit the OAuth provider to send authorization codes to Prismatic's callback URL when users authenticate.

Then, after your OAuth "app" is configured you will need to create new OAuth 2.0 credentials in the Prismatic web app for each of your customers who need credentials using the client ID and secret you noted above. Your OAuth provider will provide you with authorization and token URLs and permission scopes - enter these into the Prismatic web app, as well. These URLs and permission scopes can likely be found in the OAuth provider's developer documentation, probably under a section having to do with authentication and authorization.

After configuring a credential in the Prismatic web app, either you or your customer will need to authenticate against the OAuth provider. You can authenticate yourself by following a link that the Prismatic web app generates, or you can have your customer enter their credentials by emailing a link to your customer through the Prismatic web app. Since the purpose of OAuth is to avoid unsafe sharing of credentials, we recommend that you have your customers authenticate by emailing them a link.

After you or your customer authenticates against the OAuth provider, the provider will send an authorization code to Prismatic's callback URL, and Prismatic will take care of the rest - exchanging the authorization code for an access token, refreshing the access token periodically before it expires, and passing the access token into components that need it.

Dropbox OAuth 2.0 Flow Example

Let's look at how to set up an OAuth 2.0 credential with Dropbox.

First, log on to https://www.dropbox.com/developers/apps and select Create app. Select a Scoped access API and choose App folder for the type of access you need. Name your app whatever you'd like.

Click Create App. Under the next Settings tab, take note of your App key and App secret, and add https://oauth2.prismatic.io/callback to the list of Redirect URIs.

Finally, under the Permissions tab check the files.content.write and files.content.read scopes so your integration can read and write files within Dropbox on behalf of your customer.

Switch to the Prismatic web app and create a new credential for a customer by clicking the + Credential button under Customers -> [Customer] -> Credentials. You can similarly create test credentials at the organization level under Settings -> Credentials. Give your credential a name and choose OAuth 2.0 for the authorization method.

Within the Credentials tab, enter the Dropbox App key and App secret you noted before as your Client ID and Client Secret. Leave Scopes blank, and under Authorization URL and Access Token URL enter https://api.dropbox.com/oauth2/authorize and https://api.dropbox.com/oauth2/token respectively. These URLs were found in Dropbox's developer documentation.

At this point, our OAuth 2.0 flow is set up. We now need to have someone, either a customer or organization team member, enter their OAuth credentials to authorize Prismatic to interact with Dropbox on their behalf. We recommend emailing customers a URL and having them authenticate, so they're not tempted to email credentials to you. Do this by clicking the OAuth2 Authorization tab, enter a customer's email address, and then click Send email to send an authorization URL to your customer.

Once a user authenticates against Dropbox and and Dropbox sends Prismatic an authorization code, you will see Customer authorization complete on the top of this screen.

After the authentication process is complete, the credential can be used in an integration. In this screenshot you can see our credential being used to successfully list files contained in a Dropbox folder: