Test using OAuth Tools

Test using OAuth Tools

OAuth Tools is a great tool for testing OAuth flows. It is 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 does not allow to tweak the configuration in place in the Curity Identity Server. In this article you will learn how to configure OAuth Tools to integrate with a different instance of the Curity Identity Server like an instance under your control.

OAuth Tools App

OAuth Tools is also available as an app for macOS, Windows and Linux. 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 apply as both the web version and the app are configured in the same way.

Configuring an Environment

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. This tutorial provides instructions on how to set up an environment in OAuth Tools that instead uses a different instance of the Curity Identity Server (wherever that is installed).

The first step is to open the Settings page from the toolbar on the left. Click the New Environment button. 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.

Use Webfinger

Webfinger can be enabled in the Curity Identity Server by going to System -> Deployment -> Click the service role -> Switch to the tab Other -> Scroll down and activate Enable WebFinger for Issuer Discovery.

If Webfinger is not enabled enter the Issuer or Metadata URL. The Issuer URL looks 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 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.

Configuring a Client

With an environment configured in OAuth Tools you can add a client to use for testing. In the Clients tab of the newly configured environment, click New Client.

Enter the 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.

This tutorial uses a client with the ID www that can run the Code Flow.

Automatically Import a Client

You can automatically import the client information from the Curity Identity Server. In the admin UI, navigate to the Client you want to import into OAuth Tools. In the right upper corner, expand the OAuth.tools drop-down menu and select Open in Web (or Open in App if you run OAuth Tools as an app).

Test a Configured Flow

With an environment set up, and a client configured you can now start testing.

  1. Ensure to select the right environment.

Select environment

  1. In the left toolbar, click Start flow and choose the flow to test. Select Code Flow in this case.

Start new flow

Choose type

  1. From the drop-down, choose the www client and also choose the openid scope.

Configure flow

  1. Scroll down and click the Run button.

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 this test, chances are that no account exists. In this case, create a new account.

The username/password authenticator can handle registration.

Authentication - Create Account

Click the Create account link. Fill out the information for the new account. Username, email and password are mandatory fields. Submit the form and finish account creation by clicking the Create account button under the form.

After successful account creation you have the option to Return to login.

Now, proceed with the login:

  1. Use the newly created account to authenticate.
  2. In OAuth Tools this should now result in an Authorization code retrieved.
  3. 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 was not enabled for the first run click Redeem code to get the tokens.

Redeem code

There are now 3 tokens: an Access Token, a Refresh Token, and an ID Token. The ID Token is issued because the openid scope was requested.

Next Steps

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.