Authorization for Organizations with Modern App-Only Authentication

If a tenant Microsoft 365 organization was added using modern app-only authentication with enabled security defaults, the client authorization process requires to obtain an assertion from Microsoft Azure.

Before you obtain an access token from the Veeam Backup for Microsoft 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 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 User.ReadWrite.All offline_access

where:

  • <tenant> — Microsoft 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 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 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 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 entire JSON document obtained in the response at the step 3.

Authorization for Organizations with Modern App-Only Authentication Important

You must enable tenant authentication to Veeam Backup for Microsoft 365 server with Microsoft organization credentials before obtaining an access and refresh tokens. For more information, see the Enabling Tenant Authentication section of the Veeam Backup for Microsoft 365 User Guide.

Request:

POST https://abc.tech.local:4443/v7/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 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. Wait for the response from the server. A successfully completed operation returns the response code 200 OK.

Response:

200 OK

 

Response Body:

{

 "access_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAWiVQHE17ukKKACU1FadiPgAAAAACAAAAAAAQZgAAAAEAACAAAABBmp7BJW8uJYXjAAzKLP7RQg-npYTa3WJuCDF1epSBuQAAAAAOgAAAAAIAACAAAADu5z8NJ6bpbkNFXZQMBvyQT-lJjweNUAxFlfF9SNRp_cAAAABxB6MV1zS80hO-4hi-5qTKFROoVJ7BQQuU0627YKh9wuLlB9yxAvMvFlQBpZG4wRSnupxP6NmIM33VZ_wemACBSN8MycVq7fKAWLC4bM8aJdMgB8qqmuIt6e1kw_cMv_QZ6dHpy71yYmXsGmckx9jU9b4DPtbrahaYkpm89kaj_PbCXaCSECuTvlGovpJnghBI1AqscNnmJv7vOLK2f-7caLFEeFZEc3xrjNpK8O217MYRB9DrYwDL_QElQ3kLnLRAAAAA692AYRZZ0qkBK9B-KFviPcloIvkqoMw6yyjNr7F8Agr79VS67ZNbBgnTGN4URE7dDUnl16pOyHae-GywAa-iuQ",

 "token_type": "bearer",

 "expires_in": 3600,

 "refresh_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAWiVQHE17ukKKACU1FadiPgAAAAACAAAAAAAQZgAAAAEAACAAAAD787JomHe0m9lhVth_dSVYeCLCxRGhU6p7QbxvDOxxwwAAAAAOgAAAAAIAACAAAABL3Cw8JRvasEGBVpefTq3mjoqQVhAxmvATLpOkZPBzwPAAAAD9TmcFCBQBiKAnnOKNe0-g5IvdjSsI8h6GVegxsZzl-L-PDkyEp18DUoKlWfgkTPOlXd7Qmvkdfmp-o1yuQp0Q2LzSecOPGzV9aZMkbug9I7XA6zt5EAu5sOJvkmbXMuYKgU2PRDItS565cE3irOmu72UbF5bsM0V7d5JdFzVZ65j__fafrZYJFqMLhq51XIuNfUSiyP2CSgtfP89v8QNRIfGGE542uGY0pTFXIlHG54Dnd1H75adM-rSaVlwLDbk9qsNWoT6QbHu6SUbz_l3K8K36oFKX0CYOhf0ybxoQRIdUTKx5al9q1IRuQ1HeC35AAAAA6qX2v4MHM9Gq29Ii0yJ_BwzLrzVeG6XPMHnHz-BZ4w871-7B9p0lPh9Brodh9ofazUFsHPUFFKp9W01Ym61NKw",

 ".issued": "Mon, 13 Dec 2022 13:18:43 GMT",

 ".expires": "Mon, 13 Dec 2022 14:18:43 GMT"

}

The response body contains access and refresh tokens. Copy both tokens, insert an access token in headers of further requests. A refresh token must be saved locally.

  1. When an access token expires you can either obtain it again or renew using a refresh token. To renew the access token, send POST HTTPS request to the Veeam Backup for Microsoft 365 token path. In the request body, enter the refresh token.

Request:

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

 

Request Body:

grant_type=refresh_token&refresh_token=<refresh_token>

Wait for the response from the server. A successfully completed operation returns response code 200 OK and a new pair of tokens in the response body.