Authorization for Restore Operators

In this article

    Veeam Backup for Microsoft 365 allows restore operators to perform self-service restore of backed-up data using Restore Portal. For more information about Restore Portal, see the Data Restore Using Restore Portal section of the Veeam Backup for Microsoft 365 User Guide.

    To access Restore Portal using Veeam Backup for Microsoft 365 REST API, a restore operator must obtain an assertion from Microsoft Azure using the MSAL protocol. An assertion is a document in the JSON format that contains an access token and refresh token for an Azure AD application used for data restore. Once a restore operator provides the assertion to the Veeam Backup for Microsoft 365 REST API server, they can obtain an access token from the Veeam Backup for Microsoft 365 REST API server and continue working with REST API in the regular way.

    Authorization for Restore Operators Tip

    For more information on authentication against the Microsoft identity platform, see Microsoft Docs.

    The following example illustrates how to obtain an assertion with an access token.

    1. Obtain an MSAL access token through the Microsoft Graph API. To do this, send the POST HTTPS request to the /devicecode endpoint of the Microsoft identity platform authentication server. In the request body, provide the application ID and permissions required for the application.

    Request:

    POST https://login.microsoftonline.com/<tenant>/oauth2/v2.0/devicecode

     

    Content-type: application/x-www-form-urlencoded

     

    Request Body:

    client_id=<application_id>&scope=api%3A%2F%2F<application_id>%2Faccess_as_user%20openid%20profile%20offline_access

    where:

    • <tenant> — Microsoft 365 organization name in the *.onmicrosoft.com format. For example: abc.onmicrosoft.com.
    • <application_id> — ID of the Azure AD application used to connect to Restore Portal. For more information on how to get this parameter value, see Getting Restore Portal Settings.
    • scope — permissions for the application.

    Wait for the response from the server.

    Response Body:

    {

    "user_code":"...",

    "device_code":"...",

    "verification_uri":"https://microsoft.com/devicelogin",

    "expires_in":900,

    "interval":5,

    "message":"To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ... to authenticate."

    }

    1. Follow the link obtained in the verification_uri element of the response body and authenticate using credentials of the Microsoft 365 organization and user code obtained in the user_code element of the response body at the step 1.
    2. Obtain an assertion with an access token through the Microsoft Graph API. To do this, send the POST HTTPS request to the /token endpoint of the authentication server. In the request body, provide the application ID and device code.

    Request:

    POST https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

     

    Content-type: application/x-www-form-urlencoded

     

    Request Body:

    grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=<application_id>&device_code=<device_code>

    where:

    Wait for the response from the server.

    Response Body:

    {

    "token_type":"Bearer",

    "scope":"...",

    "expires_in":3599,

    "ext_expires_in":3599,

    "access_token":"<access_token>",

    "refresh_token":"<refresh_token>"

    }

    1. Log in to Veeam Backup for Microsoft 365 REST API. To do this, send the POST HTTPS request to the Veeam Backup for Microsoft 365 token path. In the request body, provide the access token obtained in the response at the step 3.

    Request:

    POST https://abc.tech.local:4443/v6/token

     

    Content-type: application/x-www-form-urlencoded

     

    Request Body:

    grant_type=operator&client_id=<userId.tenantId>&assertion=<access_token>

    where:

    Alternatively, you can use Swagger UI. In this case, you must provide values for the following parameters:

    1. From the grant_type drop-down list, select operator.
    2. For the client_id parameter, enter the user ID and tenant ID in the following format: userId.tenantId. For information on how to obtain these values, see Obtaining User ID and Tenant ID.
    3. For the assertion parameter, enter the access token obtained in the access_token element of the response body at the step 3.

    Once a restore operator has logged in to Veeam Backup for Microsoft 365 REST API, you can create a restore session to the restore operator. For more information, see Creating Restore Session for Restore Operator.

    Obtaining User ID and Tenant ID

    To provide a value for the client_id parameter, you must obtain a user ID and tenant ID. You can obtain these values in one of the following ways:

    1. Request an additional access token. To do this, send the POST HTTPS request to the /token endpoint of the authentication server. In the request body, provide the application ID and the refresh token obtained at the step 3 of the authorization procedure.

    Request:

    POST https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

     

    Content-type: application/x-www-form-urlencoded

     

    Request Body:

    client_id=<application_id>&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default%20openid%20profile%20offline_access&grant_type=refresh_token&refresh_token=<refresh_token>

    1. Using the obtained access token, send the following GET HTTPS request to obtain a user ID:

    Request:

    GET https://graph.microsoft.com/v1.0/me?$select=id

     

    Content-type: application/x-www-form-urlencoded

    1. Using the obtained access token, send the following GET HTTPS request to obtain a tenant ID:

    Request:

    GET https://graph.microsoft.com/v1.0/organization?$select=id

     

    Content-type: application/x-www-form-urlencoded

    • Use an external tool (for example, you can view the required parameter values using Azure Portal in Azure AD).
    • Decode the access token obtained at the step 3 of the authorization procedure. Then collect values of the following parameters:
    • oid — user ID
    • tid — tenant ID