Authentication can be complex, and developers are forced to work within the framework of the APIs they’re integrating to.
If you’re building internal integrations, you’ll likely encounter easier to manage tokens, if they’re even necessary at all. But for productized integrations, you’ll have to manage your users’ credentials and tokens to third-party systems, which adds complexity and means more time and effort on your plate.
With this in mind, there are some primary auth types that you’ll likely encounter in your work, meaning having some understanding of their intricacies and in-practice use can be helpful to starting off your build quickly and effectively. Read on to learn about the primary auth mechanisms you can use to connect your app to a cloud service endpoint.
This blog post is a follow-on to our updated Definitive Guide to API Integration. Download the full guide for more in-depth content on integration best practices, from pre-build to post-build, or check out the blog series.
A widely used protocol for simple username/password authentication. This
type of mechanism provides no confidentiality protection for the transmitted credentials. With this, Basic authentication is typically used in concert with HTTPS to provide confidentiality/security. Example:
An Open Data Protocol that provides a process for end users to authorize
third-party access to their server resources without sharing their credentials using useragent redirections. Credential tokens are long lived, typically a year. Example flow:
Delegates security to the HTTPS protocol. OAuth (1) does not require this and uses alternative methods to remain secure. OAuth2 also introduced the use of refresh tokens that allow authentications to expire, unless “refreshed” on a periodic basis. Example flow:
OAuth2 Password Grant
The password grant is one of the simplest OAuth grants and involves only one step: the application presents a traditional username and password login form to collect the user's credentials and makes a POST request to the server to exchange the password for an access token.
OpenID Connect is an open standard and decentralized authentication protocol based on the OAuth 2.0 family of specifications. Promoted by the non-profit OpenID Foundation, it allows users to authenticate to websites and applications (known as relying parties, or RPs) using the third-party service UI (OpenID) so that developers do not have to manage password files.
An XML-based open standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. SAML is popular with large single sign on (SSO) organizations, corporate applications, and many older applications. Example of an SAML authentication request:
A TLS handshake is the process that kicks off a communication session that uses TLS encryption. During a TLS handshake, the two communicating sides exchange messages to acknowledge each other, verify each other, establish the encryption algorithms they will use, and agree on session keys.
JSON Web Token (JWT)
The claims in a JWT are encoded as a JSON object that is digitally signed using JSON Web Signature (JWS) and/or encrypted using JSON Web Encryption (JWE). In simple terms, it is just another way of encoding a JSON object and using that encoded object as access tokens for authentication from the server. Example flow:
Managing Refresh Tokens
If you want your users to authenticate once and then not have to reauthenticate again as they interact with the endpoint, your application will need to manage the refresh token from the endpoint (when available) in addition to the initial access token. This is a best practice, as users can become tired of constant requests for authentication. Notably, OAuth 2.0 is the only auth mechanism that currently has refresh tokens.
When looking at access tokens, it’s important to remember that some expire in an hour while others may last as long as a year or never expire. It’s especially important with token-based authentication methods to come up with a plan for managing your refresh tokens and for making sure they’re stored securely. (More info here).
At the end of the day, - it’s your responsibility to protect tokens. If your application stores tokens, it’s highly recommended that you encrypt with 256-bit encryption at rest within your data storage system with the key owned by the end user. Encrypted tokens stored with 256-bit encryptions are really tough to break, protecting your application and your customers' usernames and passwords.
Want to learn more about API authentication and use cases where you might need to call an IDP? Learn more in the Design a.k.a. Research section of our Definitive Guide to API Integration.
Even more? Read the next post in the series: discovery APIs.