Multi-Factor Authentication

In this article

    You can configure multi-factor authentication (MFA) for additional security of user accounts. In Veeam Service Provider Console, this authentication method is based on the TOTP algorithm and requires a user to install an authenticator application on the trusted device. Veeam Service Provider Console supports all applications that use TOTP mechanism, however we recommend Google Authenticator.

    You can enable and disable MFA for a user account using REST API.

    Multi-Factor Authentication Important!

    After you enable MFA for a user, that user can no longer authenticate with user name and password to the Veeam Service Provider Console REST API. Before you assign a second authentication factor to the account that requires access to REST API, configure one of the authorization methods described in sections API Key-Based Authentication and Asymmetric Authentication.

    Configuring MFA for Own Account

    To enable MFA for your user account:

    1. Send the HTTP GET request to the /authentication/keys/totp-secret path. The server will return the following data in the response body:
    • secret — MFA secret.
    • secretUrl — URL that contains MFA secret and user account data.

    Request:

    POST https://<hostname>:1280/api/v3/authentication/keys/totp-secret

     

    Request Headers:

    Content-type: application/json

    Authorization: Bearer <API-Key>

     

    Response Code:

    200 OK

     

    Response Body:

    {

     "data": {

       "secret": "3QEYAIQAKPC2A4ENSZEXHL4OQLWJ4XNC",

       "secretUrl": "otpauth://totp/vspc%5cAdministrator?secret=3QEYAIQAKPC2A4ENSZEXHL4OQLWJ4XNC&issuer=My%20Company%20Portal"

     }

    }

    1. Install an authenticator application on the trusted device and enter the secret key to create an account.

    The application will generate a verification code.

    Multi-Factor Authentication Tip:

    You can use a QR code to create an account in the authenticator application:

    1. On another device, open a QR code generator in a web browser.
    2. In the QR code generator, insert the secretUrl link that you received at step 1. The QR code generator will display a QR code.
    3. On your trusted device, open an authenticator application and scan the displayed QR code using the device camera.

    The application will automatically create an account and generate a six-digit verification code.

    1. Send the HTTP POST request to the /users/{userUid}/logins/totp path, where userUid is UID of your user. Additionally you must provide the following query string parameters:
    • secretUrl — URL-encoded secret that you received at step 1.
    • code — active security code.
    • description — description for a new user identity.

    The server will return a response containing a resource representation of a new user identity associated with MFA.

    Request:

    POST https://<hostname>:1280/api/v3/users/955b0b80-03b2-49fd-bf38-14785ecff0a8/logins/totp?secretUrl=otpauth://totp/vspc%5cAdministrator?secret=3QEYAIQAKPC2A4ENSZEXHL4OQLWJ4XNC&issuer=My%20Company%20Portal&code=324568&description=MFA for Alpha Administrator

     

    Request Headers:

    Content-type: application/json

    Authorization: Bearer <API-Key>

     

    Response Code:

    200 OK

     

    Response Body:

    {

     "data": {

       "id": 12,

       "userUid": "955b0b80-03b2-49fd-bf38-14785ecff0a8",

       "userName": "alpha_admin",

       "companyId": "3b139961-6b11-4fd8-9e87-c2be1b0e9ca8",

       "companyName": "Alpha",

       "identityProviderName": "TOTP",

       "description": "MFA for Alpha Administrator",

       "identifierInProvider": "11217524525076510964",

       "scopes": [],

       "status": "enabled",

       "parameters": "",

       "creationDate": "2020-08-18T16:02:26.0136931+00:00"

     }

    }

    Enabling MFA for Other Users

    To enable MFA for other users, send the HTTP PATCH the following request to the /users/{userUid} path, where {userUid} is UID of a user:

    [

     {

      "op": "replace",

      "path": "mfaPolicyStatus",

      "value": "enabled",

     }

    ]

    Enabled MFA only affects users that access Veeam Service Provider Console Portal. On the next authorization session, these users will be prompted to configure MFA. Authentication to Veeam Service Provider Console REST API remains intact.

    Disabling MFA

    To disable MFA for other users, send the HTTP PATCH the following request to the /users/{userUid} path, where {userUid} is UID of a user:

    [

     {

      "op": "replace",

      "path": "mfaPolicyStatus",

      "value": "disabled",

     }

    ]

    If you want to permanently disable MFA for a specific user, you can delete the associated user identity resource. For details, see Delete User Identity.

    I want to report a typo

    There is a misspelling right here:

     

    I want to let the Veeam Documentation Team know about that.