Client / server development strategy

Occasionally we receive the question how to implement an OAuth 2.0 client or server with this SDK. Publishing a complete tutorial or example will be a huge job, especially on the server side, where the authors of OAuth 2.0 have decided, reasonably so, to concentrate most of the complexity, so that clients can be simple and lightweight. An OAuth 2.0 server that covers basic authentication and the minimum necessary security, with an API for registering and managing the clients and the underlying high-level code to drive the cryptography for the access token minting (if JWT encoded) can easily run into many thousands lines of Java code. What we provide here instead is a good universal strategy that has worked successfully with our own commercial products and online services:

Strategy for developing an OAuth 2.0 client, server or component

1. Choose a particular OAuth 2.0 profile or set of specifications (RFCs) to implement. If you work in a industry such as fintech there will be an existing standard profile - in the case of fintech and OpenBanking this is FAPI. If you need to implement general purpose user authentication on top the user-agent based OAuth 2.0 flows (usually the code flow) the profile for that is called OpenID Connect.

   Keep in mind the corpus of OAuth 2.0 standards is not static, but is evolving. Over time, certain extensions have become minimum required security. The chief example is PKCE, designed to prevent code attacks on public / native clients. Other notable extensions are mTLS and its alternative DPoP, both invented to give access tokens stronger security properties than the original bearer model.

   The specs also change or become deprecated in response to ongoing web standard and browser developments. One such example is the deprecation of the resource owner password credentials grant in favour of the authorisation code grant with the wide spread adoption for CORS. Another notable example is the gradual removal of 3rd party cookie support across browsers, which affected the OpenID Connect front-channel based single-logout specs. Yet another example is token binding, which died when a major browser decided not to implement RFC 8471. The OAuth 2.0 framework is a pretty dynamic place!

   The following link at the IETF has a list of current and expired OAuth 2.0 specifications:

   https://datatracker.ietf.org/group/oauth/documents/

   To stay current on the best practises monitor the OAuth 2.0 Security Best Current Practice and the OAuth 2.0 for Browser-Based Apps documents. Note that they also keep evolving.

   There is also an effort to roll those recent OAuth 2.0 developments into a single new baseline spec called OAuth 2.1. Its latest draft can be found here.

   You may also consider subscribing to the OAuth WG mailing list, to simply lurk, or to ask a question about an RFC or draft.

2. This SDK provides Java code that implements the protocol messages, verifications and cryptography dealing with OAuth 2.0, OpenID Connect and the various extensions. It also contains useful utilities, for dealing with HTTP, JWTs, etc.

   Aspects that are worded as “implementation specific” are also handled in this way by the SDK, which means you’ll need to decide upon them and implement them yourself. One such notable aspect is how the end-users get authenticated at the authorisation endpoint.

   The SDK code is deliberately agnostic and has no Java framework dependencies (okay, there is an minimal optional Java Servlet dependency ;)).

   Each protocol message is implemented by a class intended to be used by both client and server code.

   For instance, the TokenRequest class represents a token request from a client to a server. The class supports all standard OAuth 2.0 grants and client authentication methods. A client will use the class’es constructor; the server will use a static parse method that takes an abstract representation of an HTTP request.

   This approach applies to virtually all other protocol messages.

   The best place to study the SDK and its concepts is by reading its JavaDocs. They are always up-to-date and all publicly accessible code (classes, methods) are fully documented.

3. The OpenID Foundation provides an online certification test suite which is highly recommended to ensure your implementation is interoperable and secure against common attacks. If you develop an OpenID Connect or FAPI application use it, this can be done free of charge. Payment is needed only if you require a certification mark.

Happy coding!