Introducing the OAuth 2.0 Flow Simulator

I often need to explain the different steps in OAuth 2.0 and OpenID Connect flows, for example during a training or consulting session. Illustrating the numerous steps with a real-world application is always challenging, especially since many of the requests are invisible to the user. That's why I built the Flow Simulator, which allows you to walk through a flow step by step, while visualizing all the relevant details. Keep reading to learn all about the publicly available Flow Simulator.

7 July 2020 OAuth 2.0 & OpenID Connect OAuth 2.0, OIDC, Online Courses, Flow Simulator

It always bothered me that I could not easily show the details of OAuth 2.0 and OpenID Connect flows. Sure, you can use the browser developer tools, but that is not going to be easy to follow. Additionally, some flows involve backchannel requests that would require debugging the server-side application.

That’s exactly why I built the Flow Simulator. This tool allows me to quickly demonstrate features by running a flow in the browser. All relevant details are visualized with automatic encoding and decoding when applicable. In a nutshell, the Flow Simulator will be heavily used in my work the coming months and years.

Visualizing OAuth 2.0 / OIDC flows

The primary purpose of the Flow Simulator is visualizing the different steps in an OAuth 2.0 flow. The example below shows how the Flow Simulator displays each interaction between a client and a Security Token Service in an Authorization Code flow.

Each step can be folded open, which reveals all the relevant details about requests and responses. That info is essential for someone getting familiar with the flows and learning about the different steps.

The main reason I built this tool is to make it easier to discuss OAuth 2.0 and OpenID Connect with developers and architects. Before using the Flow Simulator, backchannel requests were not visible, and inspecting frontchannel communication meant digging through the browser’s developer tools, as you can see below.

With the Flow Simulator, the previous request looks as follows.

STS support

The Flow Simulator uses the general concept of a Security Token Service (STS) to refer to an OAuth 2.0 Authorization Server or OIDC OpenID Provider.

Since the Flow Simulator implements common features defined in the OAuth 2.0 and OpenID Connect specifications, it should be compatible with most STS implementations out there. So far, I have extensively used the Flow Simulator against an Auth0 STS. If you test drive the Flow Simulator against other implementations, don’t hesitate to let me know how it goes.

Features of the Flow Simulator

The Flow Simulator supports a couple of cool features to make it easier to work with OAuth 2.0 and OpenID Connect flows. Let’s take a closer look.

Initializing the flow

The client typically provides a couple of configuration parameters during the intialization of a flow. Examples include the scope, an audience, the prompt parameter, or the use of PKCE. With the Flow Simulator, you can easily configure each of these options before starting the the flow. The image below shows you how to initialize an Authorization Code flow.

Copy / pasting URLs and requests

Real applications typically execute a number of steps automatically, making it hard to inspect what exactly is going on. The Flow Simulator executes a flow step-by-step. Each URL or request in the flow can be inspected . Requests can even be copied as a cURL or HTTPie command, allowing you to modify the request before firing it off in a terminal. The image below shows the POST request to run the code exchange step in an Authorization Code flow.

Inspecting tokens

Copying JWT tokens to jwt.io for inspection gets old really quickly. The Flow Simulator automatically deconstructs the payload of a JWT access token or identity token in a nice overview table. Of course, the raw token is also available. The image below shows a deconstructed access token.

Running a refresh token flow

When the Flow Simulator receives a refresh token, it offers the option to launch a Refresh Token flow with that token. This convenient mechanism is perfect to illustrate how a Refresh Token flow works in practice. The image below shows a refresh token, along with the button to launch a Refresh Token flow. FYI, with rotating refresh tokens, you can keep doing this :)

Getting started with the Flow Simulator

The Flow Simulator should be pretty intuitive if you are familiar with OAuth 2.0 and OpenID Connect. While there is no written manual I can point you to, I do use the Flow Simulator in the free Introduction to OAuth 2.0 and OpenID Connect course. In that course, you will find both demo videos and hands-on assignments that explain how to use the Flow Simulator. If you want to learn more, I strongly recommend that you sign up for the free course..

Reaching out with feedback

If you have any feedback or encounter unexpected issues, don’t hesitate to let me know. The easiest way to reach me is via email (philippe@pragmaticwebsecurity.com).