Philippe De Ryck

Hi, I'm Philippe, and I help developers protect companies through better web security. As the founder of Pragmatic Web Security, I travel the world to teach practitioners the ins and outs of building secure software.

Want to learn more about OAuth 2.0 and OpenID Connect?

Save yourself days of digging through dozens of specs with this online course

More information

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

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.

The Flow Simulator visualizes the different steps in an OAuth 2.0 / OIDC flow
The Flow Simulator visualizes the different steps in an OAuth 2.0 / OIDC 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.

Inspecting the code exchange request to the token endpoint with browser tools is not that easy
Inspecting the code exchange request to the token endpoint with browser tools is not that easy

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

The Flow Simulator allows the inspection of the request before it is being sent
The Flow Simulator allows the inspection of the request before it is being sent

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.

Learn all about current best practices for OAuth 2.0 and OIDC

This online course saves you countless hours of digging through specs

More information

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.

The Flow Simulator allows the configuration of the Authorization Code initialization URL
The Flow Simulator allows the configuration of the Authorization Code initialization URL

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.

The Flow Simulator supports copy/pasting entire requests to the terminal
The Flow Simulator supports copy/pasting entire requests to the terminal

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.

The Flow Simulator decodes a JWT payload, making inspection of the claims easy
The Flow Simulator decodes a JWT payload, making inspection of the claims easy

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 :)

The Flow Simulator allows the launching of a Refresh Token flow with the click of a button
The Flow Simulator allows the launching of a Refresh Token flow with the click of a button

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).



About Dr. Philippe De Ryck

Hi, I'm Philippe, and I help developers protect companies through better web security. Learn more about my security training program, advisory services, or check out my recorded conference talks.

Want to learn more about OAuth 2.0 and OpenID Connect?

Save yourself days of digging through dozens of specs with this online course

More information
Philippe De Ryck

Dr. Philippe De Ryck

Hi, I'm Philippe, and I help developers protect companies through better web security. As the founder of Pragmatic Web Security, I travel the world to teach practitioners the ins and outs of building secure software.


Talks and workshops

You will often find me speaking and teaching at public and private events around the world. My talks always encourage developers to step up and get security right.


Articles

Security is often about small nuances. In my articles, I dive deeper into various security topics, providing concrete guidelines and advice. My articles also answer questions I often get while speaking or teaching.


Security resources

Getting security right is all about knowledge. I strongly believe in sharing that knowledge to move forward as a community. Among my resources, you can find developer cheat sheets, recorded talks, and extensive slide decks.


Mailing list

Subscribe to the Pragmatic Web Security mailing list to stay up to date on the latest activities and resources.

Subscribe