Understanding TOTP and Why It Matters for Security Testing
When a user logs into an MFA-protected application, the flow typically involves entering a username and password followed by a one-time token generated by an authenticator app such as Google Authenticator or Microsoft Authenticator. For automated security testing, generating and submitting that token in real time is not practical without the right configuration.
The solution is the TOTP secret, also called a seed. This is the shared secret string that underpins the entire TOTP algorithm — the same value encoded into the QR code you scan during MFA enrollment. With this string, any system can generate the correct one-time password at any given moment, exactly as your authenticator app does. SpartanX uses this secret to authenticate on your behalf during testing.
Step 1: Create a Knowledge Entry
The first step is to create a knowledge entry that tells SpartanX how to authenticate with your specific application. Navigate to your campaign, select Knowledge, and add a new entry.
Give it a descriptive name such as "OTP use always." The body of this entry is a set of instructions that guide the SpartanX agents through the login flow for your application. These instructions should cover the following:
Login page navigation: Direct the agent to navigate to the application login URL.
Credential entry: Instruct the agent to use the username and password stored in Secrets.
Identity provider exclusion: Explicitly state not to select Google, Microsoft, SSO, or any other identity provider button.
MFA handling: Instruct the agent to generate the current TOTP code using the provided TOTP secret when prompted.
Passkey and biometric decline: Instruct the agent to decline any offer to enroll a passkey, fingerprint, facial recognition, or "trust this device" option.
This knowledge entry is specific to your application. If your organization uses Okta, OneLogin, or a custom authentication provider, describe that exact flow here. SpartanX agents follow these instructions on every engagement run.
Step 2: Add Credentials as a Secret
Next, navigate to Secrets and add your first secret using the type Credentials. Provide a name and optional description, then enter the username and password of the test account you are using for the assessment. This should be a dedicated penetration testing account, not a production user.
Optionally, associate this credential pair with a specific asset or URL so SpartanX knows exactly where these credentials are valid. If you are testing multiple systems, you can create multiple credential secrets scoped to different assets.
Step 3: Add the TOTP Seed as a Secret
Still in Secrets, add a second secret using the type Custom. Name it something descriptive such as "OTP" and add a description like "OTP seed to generate one-time passwords."
Add a custom field — for example, name it "OTP Secret" — and paste in the TOTP seed string as the value. This is the same long string you would see when scanning a QR code during MFA enrollment, sometimes visible in your authenticator app settings under "show key" or "export account." Associate this secret with the same URL or asset as your credentials.
Once saved, secrets are protected by an audit trail. Only users with the appropriate permission level can reveal secret values, and every reveal is logged within SpartanX.
How It Works During an Engagement
When SpartanX runs an engagement against an MFA-protected application, it follows the knowledge entry you created to navigate the login flow. It retrieves the username and password from the credentials secret, submits them to the login form, and when the MFA prompt appears, uses the TOTP seed to compute and enter the correct one-time code at that exact moment.
The result is a fully automated engagement against an application that would otherwise block any automated scanner at the MFA step. No manual intervention is required once the configuration is in place.
Appendix: Agent Login Flow Instructions Template
The following is the reference instruction template used when creating the Knowledge entry for TOTP-based authentication. Adapt this for your specific application, auth provider, and organization name.
Step 1: Use the interactive browser login flow. Do not reuse session cookies or attempt silent or implicit OAuth authentication.
Step 2: Navigate to the application login URL. Confirm the auth domain and provider (e.g. Auth0, Clerk, or Cognito).
Step 3: If prompted for an organization or workspace, enter and select the correct org name.
Step 4: Use the email and password form with the credentials stored in the provided engagement secret.
Step 5: Do not select Google, Microsoft, SSO, or any other identity provider button.
Step 6: If prompted for MFA, generate the current TOTP code using the provided TOTP secret.
Step 7: If the login service offers to set up faster sign-in (passkey, fingerprint, facial recognition, or "trust this device"), decline it. Do not enroll a passkey or any biometric method.
Step 8: After login completes, confirm the active organization and navigate to the target section to reach the target feature.
Conclusion
Configuring SpartanX for MFA-protected applications requires three things: a knowledge entry that describes the login flow for your application, a credentials secret containing the test account username and password, and a TOTP seed secret containing the shared secret string. Once these are in place, SpartanX handles the full authentication process end-to-end, including generating valid one-time passwords in real time. If you need help setting this up for your specific environment, the SpartanX team is always happy to assist. That is all for this video, and we will see you in the next one.