Two-Step HTTP Testing (OAuth)

The ThousandEyes HTTP server test includes support for two-step HTTP testing. You can use this feature to create testing scenarios where the initial request fetches an authentication token, and the token is used by the second request to perform the actual test measurement. These requests can have different target URLs, the second of which is the URL of the server actually being tested.

By contrast, a basic HTTP server test only contains one request, for the test measurement itself.

The test configuration for two-step HTTP authentication is found in Cloud & Enterprise Agents > Test Settings under the Advanced Settings tab, for an HTTP server test. Look in the section titled HTTP Authentication, and choose the OAuth option.

Overview

The two HTTP requests can be described as follows:

1. Initial or authentication request

2. Primary or measurement request (the actual HTTP server test itself)

These two requests are executed as part of a single ThousandEyes HTTP server test and have a special relationship, in that certain values from the initial request can be dynamically inserted into the primary request. One example where you can use this testing method is for an OAuth-secured API service:

The initial request is sent to the authentication URL, and fetches the authorization token. The authorization token is passed to the API service URL in the primary request.

The following figure illustrates the scenario:

Advanced Settings

To create a new two-step HTTP server test, click the Add New Test button in Cloud & Enterprise Agents > Test Settings, and then go to the Advanced Settings tab and look for the HTTP Authentication section, as shown below.

Markers in the figure above point out the various configuration sections for OAuth-based tests:

1. OAuth authentication selector: When you set the Scheme field to OAuth, the fields at marker #2 appear.

2. Authentication request configuration: This section deals with the configuration of the initial authentication request.

3. HTTP request configuration: The section labeled HTTP Request contains the actual measurement request's configuration.

Configure Initial Authentication Request

As shown in the previous section, the initial authentication request is configured independently of the measurement request. The figure below shows the HTTP server test configuration with sample values, including the JSON portions.

Fields for HTTP Authentication:

1. Initial Authentication Scheme selector defines how the initial request will be authenticated to the authentication service. Currently Basic and NTLM methods are inherently supported. Other custom authentication schemes may be configured by manipulating raw request header and/or body content - see items #4, #5 and #6 below.

2. Username and Password fields for Basic (or NTLM) HTTP authentication.

3. Authentication URL is the target service URL to send the initial HTTP request to (typically an authentication request).

4. Authentication Request Method setting defines the HTTP request method to use for the authentication request. GET and POST methods are supported. Typically a POST method is used for OAuth authentication requests.

5. Authentication Request Body (use POST only) content field provides means for submitting custom POST content in the authentication request.

6. Authentication Headers can be filled with custom HTTP headers to add to your initial request.

Some other aspects of the authentication request configuration (such as HTTP protocol version and User Agent string) are common to both authentication and measurement requests, and are configured in the measurement request's configuration section.

The example shown in the figure above uses HTTP Basic authentication scheme to authenticate the client (Enterprise or Cloud Agent) to the authentication service. The expected response format is set to JSON, which is currently the only supported format that can be parsed and its values used in the subsequent measurement request. An example JSON (OAuth) response looks like this:

{
    "access_token": "<REAL-TOKEN-VALUE-HERE>",
    "token_type": "bearer",
    "expires_in": 3600,
    ...
}

Configure the Measurement Request

The majority of configuration directives pertaining to the primary (or “measurement”) request are already explained in the article titled Working with Test Settings. The section below describes how to use portions of the authentication request's JSON response content in the measurement request's headers or body. Adding the Authentication Token to the Measurement Request JSON is the supported format for parsing the HTTP authentication request's response, and for using those parsed values in the measurement response. Below is the JSON configuration format to achieve such test behavior:

%{json:<VARIABLE_NAME>}

If the access_token variable is received in the authentication request's response, the following request uses it as a bearer token in the measurement request's Authorization HTTP header as shown below:

The same format can be used in the measurement request's POST body when the POST request method is used.

Troubleshooting OAuth Authentication Issues

When an HTTP Server test using OAuth authentication experiences an issue in the initial authentication request, the result displays in the test view on the Map tab, indicating a problem in the Authentication phase, as shown below.

In the same test view on the Table tab, you’ll see “Authentication” under the Error Type column, as shown below:

To investigate why the authentication request is failing, create a dedicated HTTP server test targeting the authentication URL, using the same authentication scheme that is used for the initial authentication request in the OAuth-based test:

Such a test will provide an insight into the full request and response headers, and will not display sensitive authentication information. You can use this troubleshooting information to re-configure the OAuth portion of your original HTTP server test.