4.6. Managing Multi-Factor Authentication¶

Multi-factor authentication (MFA) adds a layer of security by additionally requiring timed one-time passwords (TOTP) generated by Google Authenticator.

MFA is primarily intended to protect administrative accounts, but you can enable it for regular users as well. It is disabled by default.

To manage MFA, use the vzapi --os-cloud local-credential mfa * commands. In particular:

• To enable MFA for a specific user, e.g., admin, run vzapi --os-cloud local-credential mfa enable <username>. For example:

  # vzapi --os-cloud local-credential mfa enable admin
  {
      "activated": false,
      "blob": "MFWWO4TGMRYHA23RNJXWMZLXNY",
      "id": "a09896fe33f94490953602394a1bc59c",
      "name": "admin",
      "type": "totp",
      "user_id": "6fcd14baaa4b47f1a9de372037c2b68a"
  }
  The MFA credentials have been successfully enabled for the user admin
  

  On the next login, after entering the login and password, the user will be asked to scan the provided QR code with Google Authenticator and enter a one-time password. If the user does that, MFA becomes activated. The next time, the user will need to enter a one-time password without having to scan the QR code. If the user clicks Cancel, MFA remains enabled but not activated. In that case, the user will be able to log in with the user name and password as before, but will see the QR code every time until MFA is activated.

  The blob value in the output is the setup key the user will need to enter manually if they are unable to scan the QR code.

  The activated value indicates whether the user has scanned the QR code, paired the mobile device, and thus activated MFA for their account.

  Note

  After activating MFA for the admin, use vzapi --os-cloud local-credential <cmd> instead of vzapi --os-cloud local <cmd> in commands run by the admin. The reason is that activating MFA forbids using plain password authentication and thus makes it impossible for the admin to use the vzapi tool the old way.

• To show users for which MFA is enabled, run vzapi --os-cloud local-credential mfa list. For example:

  # vzapi --os-cloud local-credential mfa list
  [
      {
          "activated": false,
          "blob": "MFWWO4TGMRYHA23RNJXWMZLXNY",
          "id": "a09896fe33f94490953602394a1bc59c",
          "name": "admin",
          "type": "totp",
          "user_id": "6fcd14baaa4b47f1a9de372037c2b68a"
      },
      {
          "activated": true,
          "blob": "NRWHE5D2NN4XO3DPOR3WK5DPPA",
          "id": "fdddab7c9b694b25b488e558840ae599",
          "name": "user1",
          "type": "totp",
          "user_id": "73b1aab1dcf546aea2b458fb24400bc5"
      }
  ]
  

• To disable MFA for a specific user, run vzapi --os-cloud local-credential mfa disable <username>. For example:

  # vzapi --os-cloud local-credential mfa disable admin
  The MFA credentials have been successfully disabled for the user admin
  

• To reset, that is disable and immediately enable, MFA for a specific user, run vzapi --os-cloud local-credential mfa reset <username>. For example:

  # vzapi --os-cloud local-credential mfa reset admin
  The MFA credentials have been successfully disabled for the user admin
  {
      "activated": false,
      "blob": "MFWWO4TGMRYHA23RNJXWMZLXNY",
      "id": "a09896fe33f94490953602394a1bc59c",
      "name": "admin",
      "type": "totp",
      "user_id": "6fcd14baaa4b47f1a9de372037c2b68a"
  }
  The MFA credentials have been successfully enabled for the user admin
  

  After that, the user will have to scan the QR code and activate MFA anew.