Skip to main content

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.

Prismatic provides a credential manager for storing sensitive credentials for each instance. 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 OAuth 2.0 to grant access to resources. Prismatic currently supports two types of OAuth 2.0 flows:

OAuth 2.0 - Authorization Code Flow#

The OAuth 2.0 "Authorization Code Flow" is the most common type of OAuth flow, and 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.

Prismatic then receives an "authorization code" that is then exchanged for an access token, and usually a refresh token as well. If the access token has an expiration date, Prismatic will use the refresh token to fetch a new access token prior to expiration. Prismatic can then access the customer's system on behalf of the customer, without needing to know the customer's credentials.

Key: oauth2

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

For More Information: The OAuth 2.0 flow, Auth0's Explanation of the Authorization Code Flow

OAuth 2.0 - Client Credentials Flow#

With the OAuth 2.0 "Client Credentials Flow", a client ID and secret are passed to an authorization provider, and an access token is passed back to the requester. This differs from the "Authorization Code Flow" since customers do not enter credentials themselves.

Key: oauth2_client_credentials

Fields: client_id, client_secret, scopes, and token_uri

For More Information: Auth0's Explanation of the Client Credentials 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.

After entering your credentials, be sure to click Save to save your changes.

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](#listing-credentials), 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

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.

It's uncommon, but some OAuth 2.0 applications require custom HTTP headers. To add custom headers to the authorization and token HTTP requests, click the + Header button on the bottom of the OAuth credential configuration screen:

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.

A note about refreshing tokens

Some OAuth providers have access tokens that expire. Others don't. If your OAuth provider expires access tokens, it is important that Prismatic is also provided a refresh token. The refresh token will allow Prismatic to request a new access token automatically prior to expiration.

This refresh flow is often referred to as "offline access." Some OAuth providers grant "offline access" via a scope (usually called offline), and others provide an auth URL parameter, like ?token_access_type=offline.

Check your OAuth provider's documentation for how to either generate an access token that doesn't expire, or how to generate a refresh token.

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 open an instance for which you want to create some credentials. Click the + Credential button. Give your credential a name and choose OAuth 2.0 - Authorization Code 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://www.dropbox.com/oauth2/authorize?token_access_type=offline and https://api.dropboxapi.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: