How does an API consumer authenticate? For many of us it seems obvious at first glance: "OAuth"; which is as useful an answer as "42". Indeed, the details are littered with devils.
This article will attempt to break down some of the common Authentication patterns we come across on a regular basis.
Some general concepts first. When "OAuth" is mentioned, the author probably refers to the OIDC bit of Open Authentication 2.0. When others refer to "SSO", it's usually also about OIDC. OIDC itself however, is just OpenID Connect.
With that out of the way, we at Cloudoki usual refer to "OAuth2" as shorthand for the API Authentication and Authorization flows.
Within API authentication, the two lead persona are the User and the Client Application. The User grants access to his resources (resource owner) and the Client identifies the service subscription (the third party).
The owner of the Client Application is either an internal development team (eg. building a mobile app) or a Third Party. Thus, by implementing proper API authentication you catch two birds with one stone; an API consumed by an internal app can just as easily be consumed by outside parties.
The most common API authentication flows today center around User granted Client access, even for applications and APIs from the same owner. It is the most efficient flow in an API Economy (cheap to re-use), and fits SaaS perfectly. We'll break down this flow in two flavours called "Grant types".
If only life was this simple.
We'll dedicate our next article on the concepts of consent ownership, SaaP (integrations marketplace), bare-metal access grants, IoT resources and end with the "God-mode" full model access.
- Server-side redirect flow (preferred)
- Client-side redirect flow
- JSON web token
- OpenID connect flow
- Bare-metal access flow
- IoT or hardware flow
- Full model access flow
Preferred authentication patterns
Twitter was one of the first popular service providers to promote the now industry standard OAuth 2.0 authentication patterns. For good reasons, the
Authorisation code flow and
Implicit flow grants are the preferred designs to implement in your API Ecosystem. Not only will the consumer be accustomed to the flow, it safe by design and readily allows security upgrades such as 2FA (multi-factor authentication) to be implemented.
Rule of thumb, only discard the preferred authentication patterns if you have no other option.
Preparation step: register client
If you plan to facilitate more than a few client applications, a "self-service client registration" platform - a.k.a. Developer Portal - might be in order. Whichever way you facilitate the registration progress, you'll need to offer a client ID, client secret and reset function to the application author.
With a client created, the application author will want to provide you with some basics, such as a
redirect URI. Capture that, and all is in place for some good old request authorization.
Grant: Authorization code flow
Popular for back-end applications in a SaaS stack.
The "Authorization code flow" utilizes the full extend of security steps. First, the user connects through an interface controlled by the authorization party to provide consent. Second, the client confirms its identity with a secret.
API requests signed with a server-side redirect can be considered trustworthy for communicating sensitive data.
Grant: Implicit flow (deprecated)
Popular for front-end web or mobile applications in a SaaS stack.
The "Implicit flow" utilizes only a part of the security capabilities. Since no application secret can be privatly presented, the application can not be considered trusted further than an end-user validation (who can be tricked).
API requests signed with a server-side rederict are only suiteable for communicating personal data with limited sensitivity.
JSON web token
While not part of the authentication process, most services inside the API environment like to know who's executing the call and who has given consent. A common and cheap solution for this is the JWT (JSON Web token).
The JWT payload variably contains the client identificator, the user identificator, consent scope and or a timestamp. While provided as a hashed string at also doubles as a valid access token. An edge gateway is a good place to decrypt the JWT as useful meta data object in your ingress calls. No storage services required.
Software as a Platform patterns
A.k.a Integrations Marketplace related patterns. The most commonly known reverse API-to-API integration providers are IFTTT and Zapier, but the general concept of an integrations marketplace is on the rise throughout the global API Ecosystem.
Bare-metal access flow
You have most likely come across the concept of static access tokens that unlock easy access to a specific API of a service provider. They don't involve an end-user consent step, since the owner of the consent is the access token owner as well.
Hardware based authentication use-cases are probably the most fun for an architect. They tend to be very specific, and clearly sandbox the scope of capabilities. We'll use the UK Openbanking guidelines for a deeper look.
Administrative applications can transcend the borders of end-user consent. These cases require a full access to the DDD models. However, with great power comes great responsibility...
OAuth 2.0 Password grant
Don't use this authentication flow. We mention the grant type only to explicitly discourage it's implementation.