Authorization for Organizations with Modern App-Only Authentication

In this article

    In the scenario of data restore for Office 365 organizations with modern app-only authentication and enabled security defaults, the authorization process differs from the regular one. Before you obtain an access token from the Veeam Backup for Microsoft Office 365 REST API server, you must first obtain an assertion from Microsoft Azure. 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 you provide the assertion to the Veeam Backup for Microsoft Office 365 REST API server, you can continue working with REST API in the regular way.

    Authorization for Organizations with Modern App-Only Authentication 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 a device code 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=04b07795-8ddb-461a-bbee-02f9e1bf7b46&scope=Directory.AccessAsUser.All%20User.ReadWrite.All%20offline_access

    where:

    • <tenant> — Microsoft Office 365 organization name in the *.onmicrosoft.com format. For example: abc.onmicrosoft.com.
    • client_id — application ID. In this example, Azure CLI is used.
    • scope — permissions for the application. The following permissions are required:
    • One of the following permissions: Directory.Read.All, Directory.ReadWrite.All or Directory.AccessAsUser.All
    • One of the following permissions: User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All or User.ReadWrite.All
    • offline_access

    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 Office 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=04b07795-8ddb-461a-bbee-02f9e1bf7b46&device_code=<device_code>

    where:

    • <tenant> — Microsoft Office 365 organization name in the *.onmicrosoft.com format. For example: abc.onmicrosoft.com.
    • client_id — application ID. In this example, Azure CLI is used.
    • <device_code> — device code obtained in the device_code element of the response body at the step 1.

    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 Office 365 REST API. To do this, send the POST HTTPS request to the Veeam Backup for Microsoft Office 365 token path. In the request body, provide the entire JSON document obtained in the response at the step 3.

    Request:

    POST https://abc.tech.local:4443/v5/Token

     

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

     

    Request Body:

    grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=<tenant>&assertion={"token_type":"Bearer","scope":"...","expires_in":3599,"ext_expires_in":3599,"access_token":"<access_token>","refresh_token":"<refresh_token>"}

    where <tenant> is a Microsoft Office 365 organization name in the *.onmicrosoft.com format. For example: abc.onmicrosoft.com.

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

    1. For the client_id parameter, enter the organization name in the *.onmicrosoft.com format.
    2. For the assertion parameter, enter the entire JSON response obtained at the step 3.
    1. Obtain an access token and refresh token in the regular way. For more information, see Authorization and Security.