Authorization for Organizations with Modern App-Only Authentication
If a tenant Microsoft 365 organization was added using modern app-only authentication, the client authorization process requires to obtain an assertion from Microsoft Identity platform.
Before you obtain an access token from the Veeam Backup for Microsoft 365 REST API server, you must first obtain an assertion from Microsoft Identity platform. An assertion is a document in the JSON format that contains an access token and refresh token for a Microsoft Entra 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.
|
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.
- 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 — Microsoft Entra application ID.
- 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." } |
- 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.
- 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 Microsoft Identity platform 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 — Microsoft Entra application ID.
- <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>" } |
- Log in to the Veeam Backup for Microsoft 365 REST API. To do this, send the POST HTTPS request to the Veeam Backup for Microsoft 365 REST API token path. In the request body, provide the entire JSON document obtained in the response at the step 3.
|
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/v8/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:
- For the client_id parameter, enter the organization name in the *.onmicrosoft.com format.
- For the assertion parameter, enter the entire JSON response obtained at the step 3.
- Wait for the response from the server. A successfully completed operation returns the response code 200 OK.
Response: 200 OK
Response Body: { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJGREVBOEQ4M0Y2OEIyNjRGREY3OEFGN0FDQ0MyRkI3M0EyNTYxODEiLCJ0eXAiOiJKV1QifQ.eyJ0b2tlblR5cGUiOiJBY2Nlc3MiLCJqdGkiOiI5ODcyODJmMi1lNTAyLTQ2NmItYjg5OC0yZjhiZjJhMmZkNDMiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW5pc3RyYXRvciIsImNyZWRlbnRpYWxLZXkiOiI3ODY5MzYzZC1hMGI0LTQzYTQtYWY2NS05NGY4MTJhMTZhY2EiLCJjcmVkZW50aWFsVHlwZSI6IlVzZXJuYW1lUGFzc3dvcmQiLCJhbnRpZm9yZ2VyeSI6IlRydWUiLCJleHAiOjE3MjMxMzExNTMsImlzcyI6IjEyNy4wLjAuMSJ9.N8TH45jADWm6I_78ri61QOZo9ZdViUZ4C9cllMvsl78lCVNmgQAcbZ7rFhWkTHtVCgMgQkatr-7E1c7oQJMkjnI608Avjp4rGVkjYehpBzQ9dFPnvrrA_Ei74ucERiETCQRRuNStearJ2XLKmPja6CbNIZ6pE-JegEk2gz_zvJ0qYlsoa2_xP78cLFCuQD_O5ODycLNF4l3WRnFkMm8GTbpulArmoK7LoK-v1M7p-18XrXRBhMAq_EONln9630STnANzhUYX0eR7NWpU_-01YdL0zWqXpOByx-Msu66QZBb5wjLPYkWeEtHewpjOO31UYJXfMN7nbZ-nWS728xWxcQ", "refresh_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJGREVBOEQ4M0Y2OEIyNjRGREY3OEFGN0FDQ0MyRkI3M0EyNTYxODEiLCJ0eXAiOiJKV1QifQ.eyJ0b2tlblR5cGUiOiJSZWZyZXNoIiwianRpIjoiOTg3MjgyZjItZTUwMi00NjZiLWI4OTgtMmY4YmYyYTJmZDQzIiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvbmFtZSI6IkFkbWluaXN0cmF0b3IiLCJjcmVkZW50aWFsS2V5IjoiNzg2OTM2M2QtYTBiNC00M2E0LWFmNjUtOTRmODEyYTE2YWNhIiwiY3JlZGVudGlhbFR5cGUiOiJVc2VybmFtZVBhc3N3b3JkIiwiYW50aWZvcmdlcnkiOiJUcnVlIiwiZXhwIjoxNzIzMTM0NzUzLCJpc3MiOiIxMjcuMC4wLjEifQ.EBbhHDhyoO2NMdma2V4G9nue2QWQPQLt7lMM2YrAmjtTxA7QysJEi7P08cqQOo0Gk12FQsTxx-0s_BvpG6FRXwrN7Y409SIP26VdbQJ8Qx2ctkHhtR4CnBJDv6Td9EuOCPK7VHZ7WUkK1_rmmn6VT4u4vtKLMoFAg5kxQg_57VCL9eF73FzJLZRvW-TJPd2egJbI0ReW4Ujlx1BOhape_iZ0gDMLmD5-vfVzZLaxDIhZFgfR4QDUykh0R7pwb4qZO68uQ6vvAwzjy5X7V5Giw7DTE6dvDYoFY8sphsy-GlHJofcvG_lJ8meAdc5LwIsLgN2vwsWdotPb2pK8deeoRw", "token_type": "bearer", "expires_in": 3600, "userName": "Administrator", ".issued": "2024-08-07T15:56:22.9188632Z", ".expires": "2024-08-07T16:56:22.9188632Z" } |
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.
- When an access token expires you can either obtain it again or renew using a refresh token. To renew the access token, send the POST HTTPS request to the Veeam Backup for Microsoft 365 REST API token path. In the request body, enter the refresh token.
Request: POST https://abc.tech.local:4443/v8/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.