Introducing Simpler, More Flexible Authentication

I've spent the last few months talking with customers about integration development, and a couple of things keep coming up and ringing true with regards to authentication:

Not all third-party authentication is the same – there are plenty of unique authentication methods out there, and authentication in Prismatic needs to be flexible.
Customers deploying integrations for themselves need to have a good experience when dealing with authentication – especially with OAuth.

With those truisms in mind, I'm excited to share that we've revamped the way that components connect to the third-party apps and services you use. We're calling our new authentication model "connections", and connections give your developers more flexibility, your customers a better deployment experience, and your support team more insight into authentication and app connectivity.

I'll take a moment here to note that "credentials" still exist, and your integrations will continue to work as they always have with credentials. Over time, though, we plan to phase out credentials in favor of connections, since connections have a superset of features and are frankly much better to work with.

I'm excited about the changes that just landed. Especially because connections:

Give component developers more power and flexibility over how components authenticate and connect with third parties.
Simplify integration development by combining related credentials and config variables into single "connection" config variables.
Give your customers a better deployment experience when they enable integrations for themselves.
Improve the debugging and support experience for your support teams.

Full documentation on connections is available in our docs, but I'd like to take a moment to highlight a few changes that improve the experience for your developers, integration builders, customers, and support teams.

Developers have more control over auth

Connections let developers define their own authentication types when building custom components, so they can handle any number of fields a connection to a third-party API requires.

For example, if an API requires a username, token, and tenantId to authenticate, that doesn't slot in nicely into any of our existing "credential" formats (basic auth, api key auth, etc). A developer can now create a new connection type that includes all three of those fields.

Creating a new connection type for a custom component is simple – you just need to import the connection() helper function. The example API that requires a username, token and tenant ID could be expressed in code like this:

123456789101112131415161718192021222324252627
import { connection } from "@prismatic-io/spectral";

const acmeConnection = connection({
  key: "acmeUserTokenAuth",
  label: "Acme username, token, and tenant ID",
  inputs: {
    username: {
      label: "Username",
      type: "string",
      required: true,
    },
    token: {
      label: "Token",
      type: "string",
      required: true,
      comments: "Generate from the Acme user settings screen",
      example: "eyJhbGcEXAMPLE",
    },
    tenant: {
      label: "Tenant ID",
      type: "string",
      required: true,
      comments: "Your Acme tenant ID",
      example: "00112233-4455-6677-8899-aabbccddeeff",
    },
  },
});

Customers activating an integration that uses this component would be greeted by a friendly deployment prompt that has exactly those fields:

Connections include more than auth info

Connecting to a third-party service often takes more than a set of credentials. If you want to connect to an SFTP server, for example, you need the server's endpoint and port in addition to a username and password.

Previously, we would have packaged the username and password up as a credential and had a separate config variables for the SFTP server's endpoint and port:

Now, you can create a new connection type that includes a username, password, endpoint and port all packaged together as one config variable. That makes your integration a lot simpler to build – each SFTP step just takes an SFTP connection config variable rather than the credential and two config variables:

Customers wind up enjoying a cleaner deployment experience, too:

OAuth 2.0 should be a single button for customers

Your customers shouldn't need to worry about OAuth 2.0 implementation details, like authorization and token refresh URLs or scopes, client IDs and secrets. When enabling an integration for themselves, your customers should really only need to click a button to authenticate with a third party service.

Your developers have the flexibility to hard-code things that never change (like authorization and refresh URLs) within custom component code, and your integration builders can enter values for the other things that do change (like OAuth client ID and secret) when they build an integration.

When your customers interact with the integration, their deployment experience is simple: they just need to click a button. All of the implementation details are hidden, as they should be.

Your support team has better insight into connections

Connection logs are now streamed alongside your instance logs. So, if a customer's OAuth 2.0 connection fails to refresh, or if API calls to AWS or Salesforce fail due to expired credentials, your support team can easily identify the problem and quickly find a solution.

Additionally, you can now create alert monitors that alert you if connections throw exceptions. That's helpful for proactively addressing customer integration issues. If an OAuth 2.0 connection fails to refresh its access token, for example, you can choose to be alerted via email, text, Slack message, etc.

Going forward

We're going to be updating our built-in components to use connections in the coming weeks. You'll likely be notified in the integration designer that new component versions are available, and you can choose to update to a version that supports connections if you'd like. We encourage you to upgrade your own custom components by checking out our Spectral 5.x upgrade guide. Please reach out if you have any questions or feedback – customer feedback drove our design of connections, and I'm always interested to hear what other ideas you have that would make your integration development experience better!

Share this post

Taylor ReeceDeveloper Advocate

Taylor brings five years of experience in education and over a decade of software development experience to Prismatic. Today, Taylor works with customers and builds example content to ensure that new developers are successful on the Prismatic platform.