Exploring OAuth.tools, The World’s First OAuth Playground

API security is complex, and the underlying systems that support it are even more so. Getting a grasp on API security requires understanding many underlying components. Accordingly, any tool that can help contextualize these systems is not only a good educational tool, but it’s also a good business tool.

OAuth.tools looks poised to be that solution. Developed by Curity, OAuth.tools breaks down complex OAuth related topics, like flows and scopes, into visually understandable components. Each flow is understood in context with other flows by taking on this approach. So, does OAuth.tools succeed in depicting such complex topics? We think so. Today we review OAuth.tools, and consider why understanding OAuth flows is so valuable for securing your APIs.

What is OAuth.tools?

OAuth.tools, created by Curity, is a safe, vendor-agnostic place to experiment with a wide variety of OAuth flows.

In beta at time of writing, OAuth.tools is principally an educational resource – a safe, vendor-agnostic place to learn about and experiment with a wide variety of OAuth flows. It’s designed to inform, not to proselytize a single vendor solution (or in fact, a single solution at all, as it offers a wide variety of different flows to test). Many flows that can be tested against a live environment which allows you to not only see what each flow design looks like, but what the expected output and the various restrictions, requirements, and functional components look like from an operational standpoint.

The site currently supports nine flows: Decode JWT, Client Credentials Flow, Code Flow, Hybrid Flow, Implicit Flow, ROPC Flow, Device Flow, Introspection Flow, and Userinfo Flow. This comprehensive coverage allows for a wide variety of implementations to be represented throughout your testing.

Upon entering OAuth.tools, a sample JWT is generated to use in an OAuth flow

When you first enter the site, you are greeted with the JWT token page. This page is a great example of how clarity and brevity are best used to communicate a ton of info at once. The page (and site in general) is well-designed and simple to understand.

The page is broken into three sections, representing a common-sense workflow. On the left, we can see the flows currently in use. From here we can create, delete, or switch between other flows we’ve configured (as well as filter the current batch of flows by a stated criteria). In the center of the page, the workspace allows you to paste a JWT and switch between a handful of token types, including Access Token, Refresh Token, ID Token, Client Assertion, User Assertion, OpenID Metadata, and the ambiguously titled “Other”.

Before one can test a flow, an environment needs to be created. The environment management system here is well-executed, both intuitive and complete.

Inclusion of the WebFinger protocol, a smart move for UX.

One of the big features here is the inclusion of the WebFinger protocol. The protocol, specified by the IETF, is a mechanism by which information and metadata can be discovered automatically through a simple URL. While WebFinger is the specified protocol for OpenID Connect, its inclusion here was a smart move in terms of user experience – it lowers the barrier of entry by reducing the amount of work that must be done when creating a test environment, something that is still a bit of a chore in other solutions.

After the proper URL has been entered, WebFinger can automatically populate the rest of the information in the environments panel, listing the endpoints, the exposed scopes, any published keys, the possible mechanisms for authentication, and the expected response types, not to mention the metadata itself.

The client management system in OAuth.tools

Within this system is a client management panel as well. A client will need to be created to act on the environment. This is easily done by simply entering the desired client ID/name, a secret phrase, and then selecting what flows to use. Included flows here are Code Flow, Implicit Flow, Hybrid Flow, Client Credentials Flow, ROPC Flow, Introspect, and Device Flow. Additionally, you can choose whether or not the client can be framed at this point, meaning it can be framed in an HTML element.

Once all of this has been set up, we can start creating flows. Flows in OAuth are methods of authorization that are often starkly different from one another, so the inclusion of a great many flows here is great – the user can familiarize themselves with some of the more esoteric or single-purpose flows while having access to general flows as well.

Users can familiarize themselves with both common and esoteric OAuth flows.

As stated previously, you can select from Decode JWT, Client Credentials Flow, Code Flow, Hybrid Flow, Implicit Flow, ROPC Flow, Device Flow, Introspection Flow, or Userinfo Flow to start testing a flow.

For a simple example for what Decode JWT looks like, let’s plug one in.

A sample of testing Decode JWT

In this case, we’ve used a test JWT as provided by jwt.io. Here, we can see the fundamental simplicity of this site and the clarity it gains. To the left, we have all of our flows, and the prompt to add more. In the center, we have our JWT, and a wide variety of options as to how we define that JWT to this system. On the left, we have a very clean, efficient way of visualizing what is happening during this decoding.

While this is by far the simplest of these options, it does expose a few things. First and foremost, it exposes how a JWT is composed, and what part of the JWT is responsible for what. This graphical representation of a data-heavy item is extremely useful, and when combined with the greater system of flows, helps to set the base moving forward for how the rest of our flows look and act.

Also read: The Answer to OAuth Integration in Single Page Applications

Education vs. Proselytization

As we discuss OAuth.tools, we should recognize the difference between education tools versus the proselytization of specific solutions. When creating test cases, example environments, and so forth, it’s very easy to fall into the trap of designing for marketing rather than designing for knowledge. While there’s nothing wrong per se with designing forward-facing materials for marketing uses (and in fact, is somewhat expected), these tools must at their core do one thing – educate.

This is something that OAuth.tools does really well. Because this system was designed first and foremost to educate, and given that it’s free to use and explore, the value of the tool for educational purposes cannot be overstated. OAuth can, at times, be quite complex – having the ability to play with it safely for free is great. Doing this without also being inundated with upsells is even better, and really suggests a user-experience mindset of teaching, not preaching.

Conclusion

OAuth.tools is a great offering and provides a wonderful environment from which a wide range of testing can be done in a safe, zero-cost environment. In terms of tools that expose complex underlying systems, this solution does so in perhaps one of the more elegant and effective manners.

This tool is great not only for exposing these flows to those trying to test code or approach against the flows themselves, but for exposing the common layperson to what these flows look like, how they work with a variety of pieces of data, and ultimately, how OAuth in general looks, feels, and functions.

What do you think? How have you liked exploring OAuth with OAuth.tools? Let us know in the comment section below!