Test a HashiCorp Vault sign-in code with KeySigner

Protect a test user’s password sign-in with a code from KeySigner. Check that Vault requires the code, issues a token for the right user, and restores the prior sign-in when the pilot rule is removed.

Before you start

KeySigner on iPhone or Mac with Sign-in codes

  • Use a disposable Vault instance with a username and password test user, a separate recovery administrator, and access to run Vault API calls.

Data and access

Shared or checked
Vault checks the password and code for the test identity before issuing a Vault token. Deleting the pilot requirement changes the next sign-in.
Check separately
The token’s policies govern secret access. Existing tokens can require a separate revocation.

Who does what

Vault administrator
Set up Login MFA for one test identity and keep a separate administrator session available to remove the test rule.
Test user
Save the QR code in KeySigner and check what Vault returns from a fresh session.
  1. Prepare a separate Vault test user

    Use a disposable Vault instance with the username and password sign-in method enabled. Sign in as the pilot user once to establish a Vault identity and note its entity ID. Keep a separate administrator session available. Revoke the token from the initial pilot sign-in before testing the new rule.

    Check. You have the pilot entity ID and can still reach the separate administrator.

  2. Generate the setup QR code and save it in KeySigner

    As the Vault administrator, create a time-based one-time password (TOTP) method with generation enabled. Use Vault’s admin-generate endpoint with that method ID and the pilot’s entity ID. Open the returned barcode as a private PNG. In KeySigner, open Accounts → Add (+) → Sign-in codes and backup, unlock Sign-in codes, and choose Add account. Scan the QR code or choose the PNG. Verify the issuer and account before you save, then remove the temporary image.

    KeySigner for Mac offers options to scan a QR code, choose an image, or enter a setup link.
    Use Add account to scan the Vault QR code or choose its PNG. View full-size screenshot

    Check. KeySigner shows the expected Vault issuer and pilot account.

  3. Require the code for the pilot identity

    Create a named Login MFA enforcement rule that lists the TOTP method ID and only the pilot’s entity ID. Start a fresh client session and sign in with the pilot’s password. Inspect the response for an MFA requirement without a client token. Leave the independent administrator session open.

    Check. The password returns an MFA challenge and no token.

  4. Use a current code to check token issuance

    For a single-request sign-in, supply the password and X-Vault-MFA header. Use your method ID followed by :passcode= and the current code from Show code in KeySigner. In the test instance, submit one incorrect code first and confirm Vault denies the request. Submit a fresh KeySigner code and use Vault’s token lookup to confirm that the new token belongs to the pilot identity.

    Check. Vault rejects the incorrect code and returns a new token for the pilot when a current code is supplied.

  5. Remove the pilot rule and check recovery

    From the separate administrator session, remove the named test enforcement, then sign in again as the pilot to check the prior behavior. Revoke the tokens from the rehearsal and remove the unused test enrollment or discard the test instance.

    Check. The pilot can sign in according to the prior rule after the test enforcement is removed.

Check your result

Record the instance, sign-in method, pilot identity, and recovery administrator. Login MFA gates token issuance for the matching sign-in. Vault policies decide what that token can access. Previously issued tokens and workload identities have their own access and revocation controls.

What we tested

Tested on . In a disposable Vault Community 2.2.2 instance, the KeySigner vault imported Vault’s QR code. The password alone returned a challenge without a token. Vault denied an incorrect code and issued a token for the pilot identity with a current KeySigner code. Removing the test rule restored the prior password sign-in.

How to verify your setup

If you get stuck

Vault skips the challenge or denies the code

Check the test instance, sign-in mount, and entity ID if Vault skips the challenge. If a code is denied, match the MFA method ID and KeySigner entry to that same user. Check the clock on the device and Vault server and wait for a fresh code before retrying. Use the separate administrator to review or remove the pilot rule if the problem persists.

Report a problem with this guide

Explore all setup guides →