OIDC/OAuth2 Flows  API Security

Principles 
AUTHCODE OIDC Oauth2 IMPLICIT OIDC Oauth2
Security issues arise as soon as work begins on an API, but not necessarily in the way
you might think. Commonly held beliefs often turn out to be unfounded when it comes
to API security.
Poorly designed API security leads to misuse or, worse still, to nonuse by the intended
It’s me, it’s ok It’s me, it’s ok
clients — application developers.
To facilitate and accelerate the design and development of your APIs, we’re sharing our vision and
Ok! Here’s a code Ok! Here’s a token beliefs with you here, in this Reference Card. Our insights were gained from our direct experience
on API projects.

Securi+y
A sound API security strategy rests upon 3 main pillars:

 ou must authenticate the people and programs accessing your API, thus establishing trust in
Y
the identity of that person or program.
 ou should explicitly authorize users and programs to perform certain tasks on your API. API
Y

Principles
authorization lists which programs are allowed to do what for which user.
You should trace calls made to your API in order to ensure the accountability of all parties involved.
This is a topic in and of itself and is not the matter of this document.

It’s me with proof

The Right Balance

I know this code

Here’s a token
Here’s a code

and this code

Here’s a token
Your API Security strategy must also strike the right balance between safety and usability. In
setting up obstacles to deter malicious users, you’re impeding legitimate users as well. Using
open standards often helps in finding balance because the obstacles that are known to work well
to keep out malicious users are also easily overcome by legitimate users, provided they have the
right documentation.
Strengthening security is increasingly difficult and decreasingly efficient, so remember to measure
your efforts against the actual risks.
WWW.OCTO.COM

Scan page Scan page

CLIENT CREDENTIALS Oauth2 RESOURCE OWNER Oauth2

Why an API Scan page

We believe that API Here’s a password.

He said it’s ok
strategy? 
IS THE ENGINE OF It’s me, with proof

What’s your password?

DIGI+AL STRATEGY Ok!
Here’s
“Anytime, Anywhere, Any device” is the plight of
digitalization. API is the answer to “Business Agility”

Very secret
WE KNOW that the Web infiltrates a token
as it allows to quickly build new GUIs for upcoming

transforms COMPANIES devices.

© OCTO Technology 2017 - All rights reserved

AND

WE WORK +OGETHER, An API layer enables

Cross device
Embrace WOA
“Web Oriented Architecture”
with passion, TO CONNECT Omnichannel
360° customer view
 uild a fast, scalable & secure
B
REST API

BUSINESS & IT Open API allows

 ased on: REST, HATEOAS,
B
Stateless decoupled
µ-services, Asynchronous

We help you CREATE Ok! Here’s a token

To outsource innovation
 o create new business
T
models
patterns, OpenID Connect &
OAuth2 protocols

OPPORTUNITIES AND EMBRACE

L everage the power of your
existing Web infrastructure

THE WEB Inside & Out DISCLAMER

This Reference Card isn’t intended to be comprehensive but rather to
highlight the security concepts that were exposed in the course of

Implementation
our work on APIs. Please check out our blog http://blog.octo.com,
Download OCTO's AR app. Scan pages illustrated with
and feel free to comment/challenge this API Security cookbook.
the smartphone icon to get our content with an added
We’re really looking forward to sharing with you.
augmented reality experience.

While many API Management solutions offer embedded OIDC/OAuth2 options, we advise  uth0: Cloud - Support all the OIDC/OAuth2 flows
A
against them as most of the time they usually only support the “Client Credentials” flow. We Anvil: On premise - Support “Implicit” and “AuthCode” flows
prefer dedicated solutions, such as... AUTHORS
tribu-woapi@octo.com
Powered with by Florent Jaby, Antoine Chantalou, Simon Renoult, WOAPI
Tribe & Sophie Delronge.
WWW.OCTO.COM
Which security Recommended OAuth2  Scope 
protocol ? protocols  With OAuth2, you should recognize 3 different types of clients: In OAuth2 and OpenID Connect, an access token is bound to a set of scopes.
A scope describes the limits of the privileges that a user has delegated to an application.
Confidential: For applications consuming your API. Usually server- or web-based applications
It usually looks like: “profile”, “email”, “articles”, “publish”, etc.
OPEN ID
Do not use.
External: Typical third-party web-based clients. Can keep their secrets safe A user can only delegate privileges he or she has.
API KEY
CONNECT Public: Mobile and Single Page applications. Their credentials cannot be safely stored

It offers 4 different flows:

You can use only a key for server-to-server OpenID Connect is a standardization of OAuth2.
SSL CLIENT communication and it only provides authentication. It describes user identity and third-party THREE-LEGGED FLOWS TWO-LEGGED FLOWS
SAML
It is the easiest to put in place but also the least authentication more specifically. You SHOULD
CERTIFICATES
Consensus between client, Two-party agreement,
secure of the 3 protocols recommended here. use this if you want to buy a product and handle
authorization server, and user more likely to be broken
users in a standard way. Many Web Giants now
support it too.
Authorization Code Client Credentials Application
No dynamic registration (2-legs only). Browser is Only authenticates the application and is notoriously User
mandatory. No standard identity data structure. complex to implement for consumers. Main flow. It allows external or confidential No end-user. Uses scopes, thereby following Service
No notion of privilege delegation to a third party. OAUTH2 clients to ask users to delegate some of their
privileges without sharing their password.
the principle of least privilege. Suited for
external and confidential clients.
You should only manage a handful of scopes. If the number of scopes increases with each new
feature, your strategy may be inadequate. Scopes are for programs, not people.
R.I.P OAuth2 (RFC6749) is a widely used authorization Implicit Resource Owner Credentials
WS-SECURITY OAUTH 1-A framework, relying on Bearer tokens (RFC6750) Best for public clients. Uses HTTPS to have Intended to ease migrations of legacy Naming strategies
for authentication. It allows you to delegate a the user agent verify the domain name of codebases. It allows the application to store
subset of privileges to applications in order to the application. user passwords. Best avoided. User privileges can be sliced into many scopes, which in turn can be:
protect users’ passwords.
SOAP-only, XML-only and SAML-only. OAuth2 brought two major improvements: You SHOULD use this as your default choice for Role-based: mapping between system roles and scope: “writers”, “translators”, “proofreaders”, etc.
 igital request signatures were replaced by TLS
D your API as it handles most use cases. Most Web Domain-based: named after business domains (think DDD): “translations” or “articles”.

What OAuth2 flow

 Auth2 supports many kinds of devices (native,
O Giants use this.
 ction-based: best avoided. They’re like Access Control Lists (ACL). Action-based scopes end up
A
web browser, servers…) with templates such as <resource>_<role>_<action> which leads to an ever-growing list.

BASIC AUTH
Protocol decision tree
should I use? A SCOPE MUST NOT REPLACE HOW USER PRIVILEGES ARE DESCRIBED
Is an end-user

Basic auth sends your secret to the network with HTTPS connected?

Does API DATA

YES NO Consent
each request and is primarily intended for end- You MUST rely on HTTPS (TLS) for:
users. Should I use belong to Which Client
Confidentiality, thanks to short-lived OAuth2 or OIDC an end-user? OAuth2 flow I want to Credential Choosing when to ask for scopes is a design choice. Three approaches can be considered:
symmetric cryptography or an API Key? use a common grant
should I use?
Integrity, thanks to Message login form Never: the scope is never asked and is granted implicitly (trusted applications only)
YES NO YES NO
CUSTOM
Authentication Codes (MAC) Once: the scope is asked at the first connection of each client (most common)
preventing data loss
PROTOCOLS
Do I want to My app Is my app Always: every request triggers user consent (when security concerns are high).
Authenticity, thanks to signed public My app
handle several is public? trusted?
is public
key certificates for the server IDPs?
Cf. RFC 5246 (TLS 1.2), RFC 6101 (SSL 3.0) YES NO YES NO YES NO YES NO
A custom security protocol ultimately ensures
that nobody will ever make the effort to learn to Always keep your SSL version and
use your API. API KEY Never Once Always
cipher suites up to date. Implicit Authorization Resource owner Use an
OpenID OAuth2 API KEY OAuth2 grant code grant password SSO!
Connect Client Credential credential grant

OpenID Connect  JWT  API Key  Common Pitfalls 

Objectives JSON Web Tokens (JWT) and more specifically JSON Web Signatures (JWS) are heavily used by An API key is a randomized string serving as a shared secret between the client and the server.
OpenID Connect (OIDC) lets app and site developers authenticate users without the additional
OpenID Connect. Composed of 3 Base64 encoded strings separated by dots, they’re both URL-safe. You MUST use a secure channel to exchange the key (email is not a secure channel). CLIENT SECRET
ON MOBILE
JWTs allow for symmetric and asymmetric cryptography. A compromised API key must be revoked right away.
burden of having to store and manage passwords in the face of an Internet that is well-populated
SCOPE ≠ ACL
with people trying to compromise users’ accounts for their own gain.
SUCKS
OpenID Connect protocol can be used to authenticate both clients (applications) and users on
private API resources. <headers>.<content>.<signature> Query params
Do not confuse scopes with ACLs. ACLs involve Mobile and Single Page Applications (SPA) are
You may retrieve the API key from the query params: only two actors (end-users and data providers). not secured since they can be decompiled. Any
Once in place, OpenID Connect allows you to: While scopes describe macro-size authorizations secret embedded in application distribution is to
for applications, ACLs can grant fine-grained be considered public.
Manage your own OAuth2 instance to authorize access to API resources Headers explain how to read and check this JWT as a Base64 encoded JSON literal GET /services&api_key={API_KEY} authorization for users.
Use your own OpenID Connect provider to authenticate users
Content is a Base64 encoded JSON literal
Use any external OpenID Connect provider to authenticate users: Google, Facebook and so on…
Signature is a hash (MAC) of the headers and content, allowing to check for integrity and authenticity. OAUTH RESOURCE
Header X-API-KEY
Web Giants probably handle authentication better than you ever could: two-factor authentication
with SMS... SCOPE ≠ CLAIMS OWNER AIN’T TOP
NOTCH
You may also retrieve the API key in a custom header:
Don’t hide secrets in JWTs. OpenID Connect uses a JWT to send the signed identity of the user, but
they can also be used as self-explanatory Access Tokens.
Mobile? X-API-Key: {API_KEY} Claims are information stored in ID tokens. A OAuth2 flow “Resource Owner” is a perfectly valid
scope can grant access to a set of claims or limit first step when migrating from legacy systems to
There is no way to ensure the identity of a mobile application. Any secret stored in a mobile application what an application can access. The “profile” a state of the art authentication server. However it
(like a client id) must be considered public, and therefore untrustworthy. To mitigate this issue, ALWAYS Headers are less likely to get logged and you should prefer this method. scope, for example, grants access to a handful MUST NOT be considered the end line as it solves
use an Authorization Code flow with PKCE (RFC7636). of claims. In OIDC, claims apply to identity and none of the issues addressed by the OpenID
scopes to privileges. Connect specification.
CONS:
 No fine-grain authorization

Claims .
 No expiration control
 Shared secret unsuitable for web pages and mobile apps
 No standard for secure secret exchange

Claims are information about the requested

end-user and/or the authentication event.
You can think of them as “slices” of a user’s
identity or flags about the validity of the
profile address
Bearer Token 
embedded data. Bearer Tokens (RFC 6750) are the same as API Keys but are standardized.
You may retrieve them from the Authorization header:
email team

Authorization: Bearer {TOKEN}

Bearer tokens are best used in a OAuth2 context, attached to an authorization scope, a user, and
when made easily renewable.