I Tried Resetting TOTP Settings by Directly Calling Amazon Cognito's AdminDeleteSoftwareToken

I Tried Resetting TOTP Settings by Directly Calling Amazon Cognito's AdminDeleteSoftwareToken

Amazon Cognito added AdminDeleteSoftwareToken, letting admins reset a user's TOTP MFA settings. The AWS CLI and boto3 lacked support, but calling it directly as a SigV4-signed HTTP request worked as expected.
2026.08.27

This page has been translated by machine translation. View original

Introduction

On August 26, 2026, Amazon Cognito added AdminDeleteSoftwareToken, which allows administrators to delete a user's software token for TOTP. It is an API for deleting the token of a user who has lost their TOTP device so that MFA can be set up again.

https://aws.amazon.com/about-aws/whats-new/2026/08/amazon-cognito-totp-reset/

Item Before AdminDeleteSoftwareToken was added After it was added
Administrator resetting TOTP for a target user There is no dedicated administrator API to delete an existing TOTP token Can be deleted with AdminDeleteSoftwareToken
Recovery while keeping MFA required You had to consider changing the MFA settings of the entire user pool, or deleting and recreating the user Delete the target user's token, then start the setup flow again from MFA_SETUP, which is returned at the next authentication
Scope of impact The entire user pool, or the target user's ID and related data The target user's software token

Preparation

I performed the verification in ap-northeast-1. After creating a user pool, I enabled software token MFA and made MFA required, then prepared an app client for password authentication and a dummy user. Because I will not publish actual IDs or passwords, variables are used below.

User pool with required MFA

First, I created a user pool for password authentication.

USER_POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name totp-reset-test-pool \
  --policies '{"PasswordPolicy":{"MinimumLength":8,"RequireUppercase":true,"RequireLowercase":true,"RequireNumbers":true,"RequireSymbols":false}}' \
  --query 'UserPool.Id' --output text)

I enabled software token MFA and made MFA required for the pool.

aws cognito-idp set-user-pool-mfa-config \
  --user-pool-id "$USER_POOL_ID" \
  --mfa-configuration ON \
  --software-token-mfa-configuration Enabled=true

App client and dummy user

I created an app client that performs password authentication.

CLIENT_ID=$(aws cognito-idp create-user-pool-client \
  --user-pool-id "$USER_POOL_ID" \
  --client-name totp-test-client \
  --no-generate-secret \
  --explicit-auth-flows \
    ALLOW_ADMIN_USER_PASSWORD_AUTH \
    ALLOW_REFRESH_TOKEN_AUTH \
    ALLOW_USER_PASSWORD_AUTH \
  --query 'UserPoolClient.ClientId' --output text)

I created a dummy user that sends no notifications and set a permanent password.

USERNAME=testuser
PASSWORD='<TestUserPassword>'

aws cognito-idp admin-create-user \
  --user-pool-id "$USER_POOL_ID" \
  --username "$USERNAME" \
  --temporary-password "$PASSWORD" \
  --message-action SUPPRESS

aws cognito-idp admin-set-user-password \
  --user-pool-id "$USER_POOL_ID" \
  --username "$USERNAME" \
  --password "$PASSWORD" \
  --permanent

After the password was set, the dummy user became CONFIRMED. When I authenticated, an MFA_SETUP challenge was returned.

TOTP registration

For the dummy user with the permanent password set, I obtained an MFA_SETUP session and registered TOTP.

MFA_SETUP_SESSION="$(aws cognito-idp admin-initiate-auth \
  --user-pool-id "$USER_POOL_ID" \
  --client-id "$CLIENT_ID" \
  --auth-flow ADMIN_USER_PASSWORD_AUTH \
  --auth-parameters "USERNAME=$USERNAME,PASSWORD=$PASSWORD" \
  --query Session --output text)"

ASSOCIATE_JSON="$(aws cognito-idp associate-software-token \
  --session "$MFA_SETUP_SESSION" \
  --output json)"
TOTP_SECRET="$(printf '%s' "$ASSOCIATE_JSON" | \
  python3 -c 'import json,sys; print(json.load(sys.stdin)["SecretCode"])')"
ASSOCIATE_SESSION="$(printf '%s' "$ASSOCIATE_JSON" | \
  python3 -c 'import json,sys; print(json.load(sys.stdin)["Session"])')"

So that I would not need to install oathtool locally, I generated the code with oathtool inside a Docker container. TOTP_SECRET and the generated code are not printed to standard output.

TOTP_CODE="$(docker run --rm -e "TOTP_SECRET=$TOTP_SECRET" alpine sh -c \
  'apk add --no-cache oath-toolkit-oathtool >/dev/null && \
   oathtool --totp --base32 "$TOTP_SECRET"')"

aws cognito-idp verify-software-token \
  --session "$ASSOCIATE_SESSION" \
  --user-code "$TOTP_CODE" \
  --query Status --output text

After SUCCESS was returned, I confirmed that a SOFTWARE_TOKEN_MFA challenge was returned during authentication.

API verification

For the user whose TOTP was registered in the preparation, I checked the same items before and after deletion.

Check before deletion

Authentication factors

aws cognito-idp admin-get-user-auth-factors \
  --user-pool-id "$USER_POOL_ID" \
  --username "$USERNAME" \
  --query ConfiguredUserAuthFactors --output json
[
    "PASSWORD",
    "SOFTWARE_TOKEN"
]

Challenge during authentication

aws cognito-idp admin-initiate-auth \
  --user-pool-id "$USER_POOL_ID" \
  --client-id "$CLIENT_ID" \
  --auth-flow ADMIN_USER_PASSWORD_AUTH \
  --auth-parameters "USERNAME=$USERNAME,PASSWORD=$PASSWORD" \
  --query ChallengeName --output text
SOFTWARE_TOKEN_MFA

The password and software token are set as authentication factors, and a TOTP challenge is returned during authentication.

API execution

As of this writing, the latest AWS CLI 2.36.32 and boto3 1.43.81 did not support AdminDeleteSoftwareToken.

Instead of the AWS CLI and boto3, I called it directly with a SigV4 signature added using botocore.

import json
from urllib.request import Request, urlopen

from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
from botocore.session import get_session

region = 'ap-northeast-1'
payload = {
    'UserPoolId': 'ap-northeast-1_XXXXXXXXX',
    'Username': 'testuser',
}
request = AWSRequest(
    method='POST',
    url=f'https://cognito-idp.{region}.amazonaws.com/',
    data=json.dumps(payload, separators=(',', ':')).encode(),
    headers={
        'Content-Type': 'application/x-amz-json-1.0',
        'X-Amz-Target': 'AWSCognitoIdentityProviderService.AdminDeleteSoftwareToken',
    },
)

credentials = get_session().get_credentials().get_frozen_credentials()
SigV4Auth(credentials, 'cognito-idp', region).add_auth(request)
prepared = request.prepare()
with urlopen(
    Request(prepared.url, data=prepared.body, headers=dict(prepared.headers.items()), method='POST')
) as response:
    print(f'HTTP {response.status}')
    print(response.read().decode() or '{}')

Check after deletion

After running AdminDeleteSoftwareToken, I checked the authentication factors and the challenge during password authentication using the same commands as before deletion.

Authentication factors

[
    "PASSWORD"
]

The software token was deleted, and the only authentication factor became the password.

Challenge during authentication

MFA_SETUP

At the next authentication, an MFA_SETUP challenge was returned, allowing a new software token to be set up.

Summary

For users who have no alternative factor such as SMS MFA and use only TOTP as their MFA factor, recovery after losing a device was a challenge. With AdminDeleteSoftwareToken, you can implement a recovery flow that resets only the target user's TOTP, returns them to MFA_SETUP at the next authentication, and prompts them to register again.

If you had put off making MFA required in Cognito because of recovery when a TOTP device is lost, please try this flow.

Going forward, I hope official SDK support will arrive, and that APIs will be provided that let administrators reset authentication factors other than TOTP, including passkeys, on a per-user basis.

References

Share this article

AWSのお困り事はクラスメソッドへ