What OAuth tokens are and why NeoLoad needs to handle them

OAuth tokens are temporary credentials that let one process access another process on your behalf without sharing your actual password. When you load test an process that uses OAuth — like one that lets users log in through Google, GitHub, or your company's identity system — NeoLoad needs to obtain and refresh these tokens just like a real user would.

NeoLoad is a load testing tool that simulates many users hitting your process at once. If your process requires OAuth authentication, NeoLoad must handle the token exchange during the test, or the simulated users will fail to log in and your test results will be meaningless. The challenge is that tokens expire, users need new ones at different times, and you cannot hardcode a single token into your test script — it will work once and then fail.

Handling OAuth tokens correctly in NeoLoad means capturing the token when a user logs in, storing it for that user's session, and refreshing it when it expires. This mirrors what actually happens in production and gives you realistic load test results.

Key Takeaways

  • NeoLoad must capture OAuth tokens during the login step of your test script, not hardcode them, because tokens expire and are unique to each session.
  • Use NeoLoad's variable extraction feature to pull the token from the OAuth provider's response and store it for each virtual user.
  • Configure token refresh logic in your script so that when a token expires during the test, NeoLoad requests a new one automatically.
  • Test your OAuth flow with a small number of virtual users first to confirm tokens are being captured and refreshed correctly before running full load tests.

Capturing tokens during the login flow

The first step is to record or script the OAuth login sequence. In NeoLoad, create a transaction that includes the initial request to your process, the redirect to the OAuth provider (Google, GitHub, or your identity server), and the redirect back to your process with the authorization code.

After the OAuth provider returns the token, NeoLoad receives it in the response body or headers. You need to extract this token and store it as a variable so that subsequent requests can use it. In NeoLoad, use the variable extraction feature — typically a regular expression or JSON path — to pull the token from the response. For example, if the OAuth provider returns JSON like {"access_token": "abc123xyz"}, you would extract the value and assign it to a variable called oauth_token.

Each virtual user in your load test gets its own variable instance, so when user 1 logs in, they capture their own token; when user 2 logs in, they capture theirs. This is the core difference between a load test and a single-user test — every simulated user must go through the login flow and get their own valid token.

Storing and using tokens across requests

Once you have extracted the token into a variable, use that variable in the headers or parameters of every subsequent request that requires authentication. In NeoLoad, reference the variable using the syntax ${oauth_token} (or your tool's equivalent). For a Bearer token, the Authorization header would be Authorization: Bearer ${oauth_token}.

NeoLoad will substitute the actual token value for each virtual user at runtime. This means user 1's requests will carry user 1's token, user 2's requests will carry user 2's token, and so on. If you do not use variables and instead hardcode a single token, all virtual users will send the same token, which is unrealistic and will likely cause authentication failures once the token expires or the OAuth provider detects the reuse.

As you build out your test script, explore the token variable to every request that needs it — API calls, page loads, form submissions, anything that requires the user to be authenticated. Missing even one request can cause your test to fail partway through.

Handling token expiration and refresh

OAuth tokens have a lifespan, often 1 hour or less. If your load test runs longer than the token lifetime, or if you are simulating a user who stays logged in for a long time, the token will expire mid-test. NeoLoad must detect this and refresh the token automatically.

Most OAuth providers give you a refresh token along with the access token. The refresh token lives longer and can be used to get a new access token without the user logging in again. During your initial login capture, extract and store the refresh token as a separate variable, just as you did with the access token.

Then, add a conditional step in your NeoLoad script: if a request returns a 401 (Unauthorized) or 403 (Forbidden) status, or if a certain amount of time has passed, trigger a refresh request. Send the refresh token to the OAuth provider, extract the new access token from the response, and update your oauth_token variable. Subsequent requests will then use the new token.

Alternatively, some teams build in a proactive refresh — for example, refreshing the token every 50 minutes if the token lifetime is 60 minutes — rather than waiting for a failure. This avoids test failures due to expired tokens and is closer to how real applications behave.

Testing your OAuth setup before running full load

Before you run a load test with hundreds or thousands of virtual users, test your OAuth token handling with a small number — say, 5 to 10 users. Run the test and check the NeoLoad logs to confirm that each user captured a token, that tokens were used in subsequent requests, and that any refresh logic worked correctly.

Look for patterns in the logs: all users should have different token values, requests should include the Authorization header with the token, and if a token expired, you should see a refresh request followed by a new token. If all users have the same token, or if tokens are missing from requests, your variable extraction or variable reference is misconfigured.

Also verify with your OAuth provider's logs or dashboard if possible. Some providers show you which tokens were issued, when they were refreshed, and when they expired. This cross-check helps you confirm that NeoLoad is behaving like a real client.

Common mistakes and how to avoid them

One frequent mistake is recording the OAuth flow once and then hardcoding the token into the script. This works for a single test run but fails on the second run because the token has expired. Always use variable extraction and variable references, even if you are only testing with one virtual user initially.

Another mistake is forgetting to extract the refresh token. If your test runs long enough for tokens to expire and you do not have refresh logic, all your virtual users will fail authentication partway through. Check your OAuth provider's documentation to see whether it issues a refresh token and, if so, extract it.

A third mistake is not explore the token variable to all authenticated requests. If you add the Authorization header to some requests but not others, the undecorated requests will fail. Search your script for every request that should require authentication and confirm the token variable is present.

Finally, do not assume your OAuth provider's token format or refresh behavior matches the documentation exactly. Some providers return tokens in the response body, others in headers; some refresh tokens automatically, others require an explicit refresh request. Test with a small load first and inspect the actual responses to confirm your extraction and refresh logic is correct.

Frequently Asked Questions

What if the OAuth provider returns the token in a header instead of the response body?

NeoLoad can extract from headers as well as response bodies. When you set up variable extraction, specify that you are extracting from the response headers rather than the body, and use the appropriate header name. The extraction logic remains the same — you are just pulling the value from a different location.

Can I use the same token for multiple virtual users to speed up the test?

Technically yes, but it is not realistic and will likely cause failures. Real users each have their own token. If you hardcode one token for all virtual users, the OAuth provider may detect the reuse and revoke it, or the token may expire partway through your test and all users will fail at once. Always use per-user tokens to get accurate results.

How do I know if my token has expired during the test?

The OAuth provider will return a 401 or 403 status code when a request uses an expired token. In NeoLoad, you can set up an assertion or conditional logic to detect this status and trigger a refresh. You can also check the NeoLoad logs after the test to see which requests failed with 401 and when.

What if the OAuth provider does not issue a refresh token?

Some OAuth providers only issue short-lived access tokens and require the user to log in again to get a new one. In that case, your NeoLoad script should re-run the full login flow when the token expires. This is less efficient than using a refresh token but is sometimes necessary. Build a conditional step that detects a 401 response and re-executes the login transaction.

Should I test OAuth token handling with the real OAuth provider or a mock?

If possible, test with a real OAuth provider in a staging or test environment. This confirms that your script works with the actual token format, expiration behavior, and refresh logic. If the real provider is not available or is too slow for load testing, a mock OAuth server that mimics the real provider's responses can work, but always validate against the real provider before running production load tests.