> For the complete documentation index, see [llms.txt](https://help.aikido.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aikido.dev/pentests/configure-a-pentest/setting-up-authenticated-testing.md).
# Setting Up Test Users
Most critical vulnerabilities—IDORs, privilege escalations, logic bugs—live behind your login screen. To find them, Aikido’s Pentest agents needs access.
Unlike legacy tools that require complex Selenium scripts or proxy recordings, Aikido uses an LLM-driven approach. You simply tell the agent how to log in using natural language, just like you would explain it to a human QA tester.
Here is how to configure your authentication sets.
{% stepper %}
{% step %}
**Create a Test User**
1. Click **Add Test User**.
2. **Name:** Give this set a descriptive name (e.g., `Admin User`, `Read-Only User`, `Tenant A - Manager`).
{% hint style="info" %}
We recommend setting up multiple personas to test for Broken Access Control (BAC) between different privilege levels.
{% endhint %}
{% endstep %}
{% step %}
**Provide Login Instructions**
This is the most important step. In the **Authentication instructions** field, provide a step-by-step text description of your login flow.
The AI agent parses this to navigate your specific UI quirks. Be explicit.
**Example format:**
> Navigate to `staging.app.com/login`
>
> Click on "Log in with Username"
>
> Enter username: `pentest_admin`
>
> Enter password: `super_secure_password_123`
>
> Click the "Sign In" button
{% hint style="info" %}
The AI agent is equipped to solve standard Captchas automatically. You do not need to disable these for the scan or provide specific instructions for them.
{% endhint %}
{% endstep %}
{% step %}
**Test the Configuration**
Finally, verify that the agent can interpret your instructions:
1. Click **Save & Test**.
2. The agent will launch a browser session and attempt to log in using the credentials and inbox instructions.
3. If successful, you will see a confirmation that the agent authenticated and reached the post-login state.
{% endstep %}
{% endstepper %}
### Advanced Login Flows
If your application requires more than a simple username and password, use our specialized tools:
* [**Email Verification & Magic Links:**](/pentests/configure-a-pentest/setting-up-authenticated-testing/handling-email-verification-and-magic-links.md) If you need to click a link in an email or receive a code.
* [**Two-Factor Authentication (TOTP):**](/pentests/configure-a-pentest/setting-up-authenticated-testing/handling-two-factor-authentication-totp.md) If you need to generate 6-digit codes from an authenticator app.
* [**SMS Verification:**](/pentests/configure-a-pentest/setting-up-authenticated-testing/handling-sms-verification.md) If you need to handle SMS-based verification codes.
* [**Agent Creates New Account:**](/pentests/configure-a-pentest/setting-up-authenticated-testing/agent-creates-new-account.md) Let the agent generate disposable test users from natural-language instructions — useful for multi-role coverage.
Vendor-Specific Authentication Flows:
* [**Google Auth:**](/pentests/configure-a-pentest/setting-up-authenticated-testing/google-auth.md) Native support for Google Workspace login flows is available in beta.
* [**Microsoft Auth:**](/pentests/configure-a-pentest/setting-up-authenticated-testing/microsoft-auth.md) Support for Microsoft accounts with two-step verification.
* [**Auth0 Configuration:**](/pentests/configure-a-pentest/setting-up-authenticated-testing/oauth0-configuration.md) Oauth provider settings required to support session sharing between multiple agents.
### OAuth and JWT apps
Aikido Pentest runs many agents in parallel that share a single authenticated session per test user. The same refresh token is reused across agents to keep that session alive throughout the assessment.
For this to work reliably, your identity provider (Auth0, Cognito, Azure AD / Entra ID, Keycloak, custom OIDC, etc.) must be configured so that:
* **Refresh tokens are reusable.** Disable single-use refresh tokens and refresh token rotation that invalidates the previous token on exchange.
* **Refresh token lifetime exceeds your assessment window.** A typical pentest can run for several hours — set the lifetime accordingly (e.g. greater than 7200 seconds).
* **Short-lived access tokens (JWTs) are fine** as long as refresh works under the rules above.
{% hint style="warning" %}
**Common failure mode:** With single-use or rotating refresh tokens, the first agent's refresh consumes the token. Other agents reload the stored session with the now-dead token and fail with **403** on refresh, leaving them stuck once the access token expires.
The symptom is a successful preflight followed by mass authentication failures across agents partway through the assessment.
{% endhint %}
For Auth0, follow the step-by-step settings in [**Auth0 Configuration**](/pentests/configure-a-pentest/setting-up-authenticated-testing/oauth0-configuration.md). The same checklist applies to other OIDC providers.
### Best Practices
* **Don’t use Production Credentials:** Always run pentests on a Staging or QA environment. The scanner performs intrusive tests that can corrupt data.
* **Create Dedicated Test Accounts:** Do not use personal developer accounts. Create specific accounts for the scanner (e.g., `aikido-scanner@yourdomain.com`).
* **Cover All Tenants:** If your app is multi-tenant, add credentials for users in different tenants (e.g., `User - Tenant A`, `User - Tenant B`). This allows the AI to test for cross-tenant data leakage.
### Troubleshooting
Authentication is verified during the **preflight check** immediately after launch. You can watch the agent's screen in real-time to see if it succeeds.
If the agent fails to log in:
* **Inspect the failure:** Check the agent's screenshots in the error log to see exactly where it got stuck.
* **Sanity check steps:** Walk through your provided instructions manually in an incognito window. If you skipped a step or a button is unclear, the agent might struggle.
* **Check accessibility:** Is the URL reachable from the public internet? (Check your IP whitelisting).
* **Account status:** Ensure the test user hasn't been locked out.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.aikido.dev/pentests/configure-a-pentest/setting-up-authenticated-testing.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.