使用adminSetUserMFAPreference开启Cognito用户SOFTWARE_TOKEN_MFA报错

错误原因 #

报错User does not have delivery config set to turn on SOFTWARE_TOKEN_MFA的核心原因是：目标用户尚未完成软件令牌MFA的设备关联流程——即没有生成并验证TOTP（基于时间的一次性密码）设备，直接调用adminSetUserMFAPreference启用OTP MFA会触发此错误。

解决步骤 #

必须先完成用户的TOTP设备关联，再启用MFA偏好，具体步骤如下：

1. 生成TOTP设备密钥
   调用adminAssociateSoftwareToken接口，为用户生成用于绑定OTP认证APP（如Google Authenticator）的密钥：

   const associateInput = {
     Username: response.User.Username,
     UserPoolId: environment.awsUserPoolConfig.userPoolId
   };
   const associateResp = await COGNITO_CLIENT.adminAssociateSoftwareToken(associateInput).promise();
   // associateResp.SecretCode 即为TOTP密钥，可生成二维码供用户扫码绑定
   

2. 验证TOTP设备
   让用户在OTP APP中输入生成的6位验证码，调用adminVerifySoftwareToken完成设备验证：

   const verifyInput = {
     Username: response.User.Username,
     UserPoolId: environment.awsUserPoolConfig.userPoolId,
     UserCode: '用户输入的6位验证码',
     FriendlyDeviceName: '自定义设备名称（可选）'
   };
   await COGNITO_CLIENT.adminVerifySoftwareToken(verifyInput).promise();
   

3. 启用并设置首选MFA
   完成设备关联后，再执行你原有的adminSetUserMFAPreference代码即可成功：

   let input = {
     Username: response.User.Username,
     UserPoolId: environment.awsUserPoolConfig.userPoolId,
     SoftwareTokenMfaSettings: {
       Enabled: true,
       PreferredMfa: true,
     },
   };
   await COGNITO_CLIENT.adminSetUserMFAPreference(input).promise();
   

补充说明 #

• 如果是用户自助设置MFA，可引导用户通过Cognito托管UI或自定义前端流程完成TOTP设备绑定，再启用MFA；
• 管理员批量操作时，需确保每个用户都先完成TOTP设备的生成与验证步骤，再设置MFA偏好。

内容的提问来源于stack exchange，提问作者Mohamed Anser Ali