From the earliest days of software development, authentication (also called auth) has been essential. To ensure system and data security, you must ensure that only properly identified users are permitted to log in to a system.
If you’re building native integrations to connect your SaaS product to the other apps your customers use, one of the tricky pieces is dealing with the nuances of the third-party apps, such as authentication. Sometimes you'll be the one setting up authentication for your own app, and sometimes you'll need to configure your integrations to use whatever auth pattern has been provided. In either case, knowing how user authentication methods work and what to look for can save you time and prevent integration headaches.
In working with our customers, my team has helped SaaS teams enable native integrations using basic authentication, API keys, and Open Auth 2.0 (aka OAuth 2.0), including non-spec variations of OAuth 2.0. Auth type preferences have certainly changed over time, with basic authentication being the go-to approach for a long time, though most developers have moved on to API keys and OAuth 2.0 for the reasons we'll get into shortly.
Let's look at how each of these main authentication methods works and dig into the details within the context of native integrations. We'll also touch on authorization (permission to access specific resources), but that is not the focus of this post.
Understanding the basic authentication method
Basic authentication uses the classic username and password approach. As noted, this is no longer common in modern SaaS apps, but we still see it for many legacy systems, including FTP or older HTTP-based apps.
For the simplest use case for basic auth in HTTP, take the username and the password, put a : between them, and use base64 to encode the whole. Then, place the entire base-64 encoded string as a header in your HTTP request:
curl https://example.com \
--header "Authorization: Basic bXl1c2VyOm15UEBzU3cwUmQ="
To ensure it conforms to standards, always use the Authorization prefix for the header with the Basic {base64 encoded username:password} value.
An even simpler way is to place the username and password at the beginning of the URL:
curl https://myuser:myP%40sSw0rd@example.com
However, this pattern has long been deprecated because typing credentials in the open, where anyone can read them, isn’t a good security practice.
Why SaaS teams use the basic authentication method for integrations
The draw of basic authentication for integrations is simple: basic auth is super easy to implement. All you need to do is decode the base64-encoded header and verify that the username/password combination is correct. That's it. Because of its simplicity, basic authentication makes sense when you build custom integrations in-house without using an API or integration platform.
Things to consider when using the basic authentication method for integrations
While basic auth is simple to implement, it also comes with a few negatives. Every integration gets the same credentials, and you cannot limit the scope of the credentials. That is, you can't change the authorization tied to the credentials. As a result, each integration can do everything permitted by the credentials. And, if you were to change the credentials, each integration that uses them would need to be individually updated to the new credentials. This largely manual approach to setting and updating credentials means that basic authentication does not lend itself to being used for integrations at scale.
Understanding the API key authentication method
An API key is a single string used both for identification and authentication, particularly with reference to integrations that use an API (application programming interface). Auth based on API keys is often referred to as token-based auth and is common in modern SaaS apps.
To set up auth using API keys, your app creates a key for you to use with your integration. You can often generate a key in an app under a Settings or Profile menu.
An example of an API key in an HTTP request looks something like this:
curl https://example.com \
--header "Authorization: Bearer mF_9.B5f-4.1JqM"
You may notice that the pattern is very similar to what we used for the basic auth, having the Authorization header, but this time using the Bearer {token}value.
An API key may also be passed in as a parameter for some APIs:
curl https://example.com?token=mF_9.B5f-4.1JqM
Or, you could even use a custom header for the API key:
curl https://example.com \
--header "x-acme-api-key: mF_9.B5f-4.1JqM"
Why SaaS teams use the API key authentication method for integrations
Though API authentication methods require a bit more to set up than basic authentication, they aren’t hard to implement. Usually, the generating app stores the API keys (or hashes of those keys) in a table and matches the keys up with the corresponding users.
One benefit of using API keys is that you can set the scope of the permissions (authorization), unlike with basic auth. You might set up a single token to have read-only access to specific resources while setting another token to access all resources available through the API. As a result, you can use different tokens for each integration, and it doesn't matter if a user changes a password – the API key remains mapped to that username. If an integration no longer needs access to the API, you can delete/disable the corresponding API key from the app.
API keys are ideal for integrations with your app if you are using an embedded integration platform (also known as embedded iPaaS).
Things to consider when using the API key authentication method for integrations
Users need to copy and paste API keys from one app to another. This manual step doesn't take much time, but it can cause issues when data isn't cut and pasted correctly. Another drawback is that API keys don't usually expire. As a result, someone could compromise an API key, which would continue to function until someone realizes and goes into the source app to disable/delete it.
Understanding the OAuth 2.0 method
OAuth 2.0 is everywhere. You've no doubt used it with numerous apps yourself. In general, it is set up so that you click a button in the App A, and App A sends you over to App B to ask if you wish to enable sharing of something (email, etc.) with App A. You click the button to agree to this data sharing and App A is granted permissions to App B on your behalf.
While this is surprisingly simple on the surface, the complexity is handled behind the scenes. Here’s how it works:
Why SaaS teams use the OAuth 2.0 method for integrations
One of the most powerful characteristics of OAuth 2.0 is that authorization (permissions) can be easily scoped to the specific access needed: read access to accounts, read/write access to contacts, etc. Each integration can use a different access token, and it doesn't matter if a user changes passwords; the OAuth access token will still work.
Revoking the refresh token is also straightforward, thereby disabling a user's ability to generate a new access token. Along with this, if an access token is somehow compromised, it usually expires quickly and limits the damage that could result.
The user experience with OAuth is essentially effortless since the user doesn't need to enter any data, such as credentials or an API key. Instead, the user only needs to approve the authorization request between apps.
While OAuth 2.0 is well suited for building integrations to third-party apps using an embedded integration platform (embedded iPaaS), it’s also the most powerful and secure approach to authentication — no matter what you do for integrations.
Things to consider when using the OAuth 2.0 method for integrations
There is more overhead to using OAuth 2.0 than either basic authentication or API keys. You'll need to build out the infrastructure to track the client IDs and client secrets for any of your apps that use OAuth 2.0. In addition, your app/API will need to be set up to create a callback URL that takes the Authorization Code as input and exchanges it for the access token and refresh token (when applicable).
Finally, you'll also need to build something that will periodically refresh the access token. This could be a cron job, AWS Lambda, etc.
Conclusion
If you are building custom in-house integrations between your app and third-party apps, it probably makes the most sense to use OAuth 2.0 because of the user experience and built-in protection. If you can't take that path for whatever reason, then using API keys should still provide a good user experience and decent security. Basic auth, while it has its use cases, is not optimal for most modern SaaS apps.
If, however, you use an embedded iPaaS to create, deploy, and maintain native integrations with your app, then the platform should come with built-in connectors to many applications that handle most of your authentication needs without requiring you to write additional code. You might even be able to set up your app so that an API key is created, and then that key is provided to your customer within the integration config when the customer activates the integration.
Whether your build your integrations in-house or use an embedded integration platform, a basic understanding of user authentication methods will help you execute your integration plan.
Top comments (0)