OAuth.tools is a great tool for testing OAuth flows. It’s a public web application that acts as an OAuth client application and communicates with the Curity Identity Server endpoints. OAuth.tools already comes with a configured playground out of the box. This could suffice for some very simple tests but it doesn’t allow to tweak the configuration in place in the Curity Identity Server. In this article we’ll take a look at how to configure OAuth.tools to use an instance of the Curity Identity Server that we control and can configure to our own needs.
OAuth.tools is also available as an app for Mac and Windows. Curity customers with a license and organizations evaluating the Curity Identity Server can download the app from the Curity Developer Portal.
The instructions in this article still applies as both the web version and the app are configured in the same way.
When visiting OAuth.tools for the first time you will see a set of pre-defined flows on the left side. These flows are all using the pre-configured Curity Playground environment. We want to set up an environment in OAuth.tools that instead uses our own instance of the Curity Identity Server (wherever that is installed).
The first step is to go to the
Environments menu and from there click
New Environment. If Webfinger is enabled (recommended) in the Curity Identity Server, click the
Use webfinger button and enter the URL of the Curity Identity Server, ex. https://idsvr.example.com. This would correspond to the configured Base URL in Curity.
Webfinger can be enabled in the Curity Identity Server by going to
Deployment -> Click the service role, scrolling down to Advanced and then enabling
Enable WebFinger for Issuer Discovery.
If Webfinger is not enabled it’s also possible to enter the Issuer or Metadata URL. The Issuer URL would look something like this https://idsvr.example.com/oauth/v2/oauth-anonymous and the Metadata URL like this https://idsvr.example.com/oauth/v2/oauth-anonymous/.well-known/openid-configuration.
Finding the Issuer value
The issuer value can be found by going to
Token Service ->
General and clicking the
Info button in the top right corner.
Either of these options should discover the endpoints needed to test a configured client.
Local Curity installation
If the Curity Identity Server is installed locally it might not be possible for the web based version of OAuth.tools to reach the Curity instance. This can be resolved by leveraging a reverse proxy like ngrok for example. The Exposing Curity Using ngrok article outlines details on how to configure ngrok.
This is typically not an issue when using the app version of OAuth.tools.
With an environment configured in OAuth.tools we can configure a client to use for testing. In the Client tab of the newly configured
Client ID/Name and
Secret and enable the flow(s) that corresponds to the client configured in the Curity Identity Server from the previous step, Configure client.
In this tutorial we will use a client with the ID
www and use the
It is also possible to automatically import the client information from the Curity Identity Server. In the admin UI, go to the Client you want to import into OAuth.tools and click the button
Open in OAuth.tools.
With an environment set up and a client configured we can now start testing.
Start Flowand choose the flow to test,
Code Flowin our case.
- From the drop-down, choose the
wwwclient and also choose the
- Scroll down and click the
With the configuration in place this should bring you to an authentication. If an account is available, use it to log in. If this is the first time running though this test chances are that no account exists.
The username/password authenticator can handle registration.
Create Account, on the next screen, fill out the information for the new account. Username, email and password are mandatory fields. Click the
Create account button.
When the account creation is complete there is an option to
Return to login.
- Use the newly created account to authenticate.
- In OAuth.tools this should now result in an Authorization code retrieved.
- In order to streamline this for future tests you can enable
Auto-redeem code. This will automatically redeem the code for tokens on subsequent runs. Since that wasn’t enabled for the first run we now have to click
We should now have 3 tokens, an Access Token, Refresh Token and an ID Token. The ID Token is issued because the
openid scope was requested.
This concludes the basic “Getting started” track. Head over to the summary article that also covers further suggested reading on additional advanced configuration and integration options.