Debug ASP.NET Core OAuth authorization flows with Proxyman
/ 6 min read
Introduction
When working with ASP.NET Core OAuth 2.0 or OpenID Connect authentication providers, you may invariably run into misconfiguration issues that prevent you from completing an authorization flow. This will typically surface itself with a nasty error screen like this:
If you’re lucky, the error may be written to the application log. However, sometimes no log entry exists or the error in the log may be less that helpful. In situations like that, it is useful to inspect the network traffic to try and get a better understanding on the underlying issue.
This is where Proxyman comes in.
What is Proxyman?
Proxyman is a Web Debugging Proxy that allows you to capture, inspect, and manipulate HTTP/HTTPS traffic on your computer, as well as various mobile devices. This makes it an invaluable tool to help debug network-related issues and inspect API responses.
Installing Proxyman and the certificate
You can find the Proxyman download for your platform from their downloads page. Download and install Proxyman, then make sure to install the Proxyman Certificate. The Proxyman Certificate is necessary to intercept encrypted HTTPS traffic.
The Proxyman documentation contains detailed guides for installing the certificate:
Enable decryption of HTTPS traffic
After installing Proxyman and the certificate, you can start recording the network traffic by starting Proxyman, then running your application and opening your web browser.
Running through the authorization flow, we can see requests being recorded. In this case, I experience issues with the Webflow authentication provider, so I select one of the requests made to the Webflow domain. Even though we installed the Proxyman certificate, we can still not see the response from the Webflow server.
The reason for this is that we must explicitly enable SSL proxying for the relevant domains. As you can see in the screenshot above, Proxyman allows us to do this by clicking the Enable this domain button.
On closer inspection, you can see that the Webflow authentication spans multiple domains. Some requests are made to the webflow.com domain and others to the api.webflow.com domain.
We can select both those requests and enable the domains for SSL proxying individually, or we can specify a wildcard domain. To do that, go to the Tools > SSL Proxying List… menu item.
We can then click in the ”+” button and add the wildcard domain *webflow.com. This will enable SSL proxying for the primary Webflow domain as well as any subdomains.
Analyze the OAuth flow
Running through the authentication flow again, we can see a lot of requests since I’m intercepting all the traffic from my computer. There are a few ways fo filter things down.
First, all requests are grouped by domain in the sidebar. So, if you want you can drill down to the requests you’re interested in like that.
In this case, the Webflow requests are made across two domains (webflow.com and api.webflow.com), but I want to see them all together. The better approach would be to use Proxyman’s content filters and filter the requests to include only the ones where the URL contains webflow.com
You can immediately see that the last request has a red status indicator. Selecting that request, we can view the JSON response body and see that the issue is related to a missing scope.
With this information in hand, we can now change the configuration of our Webflow authentication provider and make sure that we include the authorized_user:read scope in our authorization request.
A few notes
Before I conclude this blog post, I’d like to address a few questions that may have popped up in your head while reading it.
What about using the browser’s network tab?
The browser’s network tab is a great to for monitoring traffic that originates from the browser. In most cases, this may be all you need.
However, in the case of debugging the OAuth 2.0 Authorization Code flow, this is not sufficient. While it allows you to see most of the requests, the code exchange occurs on the back channel - i.e. between the web server and the authorization server.
As such, this traffic will not show up in the browser’s network tab. This is also the part of the authorization flow that is most likely to result in errors.
What about alternative applications?
There are alternatives to Proxyman. For a long time, Fiddler was the standard for .NET developers. At some point, they stopped developing the “classic” Fiddler and the new one was - at that point, at least - lacking a lot of features.
I started looking at other tools and used Charles Proxy for a while. A few years back, Proxyman came across my radar. I tried it and immediately became a fan.
If you use a different web proxying tool, that’s fine. The principles discussed in this blog post are valid for any of those other tools.
Conclusion
In this blog post I demonstrated how you can use Proxyman to debug configuration issues with OAuth authorization flows. It is beyond the scope of this blog post to provide detailed analysis of every possible issue you may encounter with OAuth authorization flows. My goal was simply to demonstrate how you can use Proxyman as a tool to assist you in tracking down the problem.
Tracking down and solving the problem will be up to you.
If you do any sort of development involving API integrations or want to debug tricky issues such as OAuth 2.0 or OpenID Connection authentication flows, I consider Proxyman as a must have application. I am happy to pay the annual license fee and support a small developer tools shop in the process.
You can find more information on their website and review the Proxyman documentation to get a better idea of the full power of Proxyman.