Authorization for Organizations with Modern Authentication and Legacy Protocols or Basic Authentication

In this article

    To explore and restore backups using Veeam Backup for Microsoft 365 REST API, clients from tenant Microsoft 365 organizations added using modern authentication with legacy protocols allowed or basic authentication must authenticate themselves.

    Authorization for Organizations with Modern Authentication and Legacy Protocols or Basic Authentication Note

    Tenants must use the same Microsoft organization credentials that they use to connect to the Veeam Backup for Microsoft 365 server on a service provider side for self-restore procedures using Veeam Explorers.

    Veeam Backup for Microsoft 365 REST API authorization process is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and refresh token:

    • Access token is a string that represents authorization issued to the client and must be used in all requests during the current session.
    • Refresh token is a string that represents authorization granted to the client and can be used to obtain a new access token when the current access token expires.

    Veeam Backup for Microsoft 365 REST API authorization process involves the following procedures:

    Requesting Authorization

    To obtain a pair of tokens, a client sends the POST HTTPS request to the Veeam Backup for Microsoft 365 REST API token path. The request body must contain credentials for authenticating to the tenant Microsoft organization.

    A successfully completed operation returns the 200 OK response code and an access and refresh tokens in the response body. The client inserts the access token in headers of further requests to Veeam Backup for Microsoft 365 REST API. The refresh token must be saved locally.

    Authorization for Organizations with Modern Authentication and Legacy Protocols or Basic Authentication Tip

    For more information on how to authorize your access using a client application, see Example Requests and Responses. Alternatively, you can use Swagger UI. For more information, see Evaluation in Swagger UI.

    Using Refresh Token

    To obtain a new pair of tokens in case the access token expires or becomes invalid, the client sends the POST HTTPS request with the refresh token in the request body to the Veeam Backup for Microsoft 365 REST API token path. A successfully completed operation returns the 200 OK response code and a new pair of tokens in the response body.

    Performing Logout

    The given access token expires in 60 minutes once issued. When the client finishes working with the Veeam Explorer for Microsoft Exchange, Veeam Explorer for Microsoft SharePoint, Veeam Explorer for Microsoft OneDrive for Business or Veeam Explorer for Microsoft Teams, they can stop the restore session manually. Otherwise, the session will be stopped automatically. For more information, see Stopping Restore Sessions.

    Example Requests and Responses

    The following example illustrates how the client and server communicate using requests and responses.

    1. To obtain access and refresh tokens, send the POST HTTPS request to the Veeam Backup for Microsoft 365 token path. In the request body, enter the credentials for authenticating to the tenant Microsoft organization.

    Request:

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

     

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

     

    Request Body:

    grant_type=password&username=<tenant_administrator>&password=<password>

    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 2021 13:18:43 GMT",

     ".expires": "Mon, 13 Dec 2021 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/v6/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.