Veeam Backup for Microsoft Office 365 RESTful API: Adding MFA-enabled Organizations
This is another part of my collection of blog posts on getting started with the RESTful API for Veeam Backup for Microsoft Office 365. A while ago, Veeam release version 4c which included support for Office 365 tenants using modern app-only authentication with disabled legacy protocols. This introduced some changes to the RESTful API and how to work with certain endpoints. In this post, we’ll discuss on how to add the organization.
Before getting started
There are 2 ways of adding an organization with MFA:
- Organizations with MFA
- Organizations with MFA and Legacy Protocols
As a reminder, in the first blog post, I explained how you can authenticate against the API which should be used here as well.
Once you are logged in as a VBO administrator and you have your Bearer token, let’s get started.
The next part is adding the organization, keep in mind this blog post was written when v4c was the latest release and it may be needed to adjust the version in the API endpoints.
Organizations with MFA
In the first example, we’ll add an organization which has MFA-enabled. To add our organization we will perform a POST request against “/v4/Organizations” which requires a JSON parameter.
There are 2 options which we can use here.
- Create a new Azure AD application
- Use an existing Azure AD application (in case you’ve set it up before)
In both cases, you will need an application certificate before you can make the request. This is in the form of a Base64 string which can be generated using Openssl.
Create a new Azure AD application
The full JSON looks something like this, where you configure Exchange and SharePoint Online settings with the relevant certificate and certificate password.
{
"IsExchangeOnline": "true",
"exchangeOnlineSettings": {
"UseApplicationOnlyAuth": true,
"UseMfa": true,
"ApplicationCertificate": "BASE64STRING",
"ApplicationCertificatePassword": "XXXXXX"
},
"IsSharePointOnline": "true",
"SharePointOnlineSettings": {
"SharePointSaveAllWebParts": true,
"UseApplicationOnlyAuth": true,
"UseMfa": true,
"ApplicationCertificate": "BASE64STRING",
"ApplicationCertificatePassword": "XXXXXX"
},
"userCode": "ABC123XYZ",
"type": "Office365",
"newApplicationName": "appcert"
}
Let’s split it down for some more in-depth information. Within the Exhange part, there are 2 main parameters. The first is if you want to use it (IsExchangeOnline) and if this is set to true, you’ll have to add the exchangeOnlineSettings which have 4 parameters which are self-explaining.
"IsExchangeOnline": "true",
"exchangeOnlineSettings": {
"UseApplicationOnlyAuth": true,
"UseMfa": true,
"ApplicationCertificate": "BASE64STRING",
"ApplicationCertificatePassword": "XXXXXX"
},
If we look at SharePoint, it is pretty much the same story. There is one extra parameter which will allow VBO to enable the export mode for SharePoint Web Parts. For more information, check out Veeam’s user guide.
"IsSharePointOnline": "true",
"SharePointOnlineSettings": {
"SharePointSaveAllWebParts": true,
"UseApplicationOnlyAuth": true,
"UseMfa": true,
"ApplicationCertificate": "BASE64STRING",
"ApplicationCertificatePassword": "XXXXXX"
},
The final part of the JSON contains 3 parameters. Within the newApplicationName, you specify the name of the Azure AD application. Type is set to Office365 and the userCode.
"userCode": "ABC123XYZ", "type": "Office365", "newApplicationName": "appcert"
The userCode can be obtained by performing a POST request against “/v4/DeviceCode“. Within the targetRegion, you specify the region of the organization which you will add.
{
"targetRegion": "worldwide"
}
There are multiple options available here:
- Worldwide
- USgovCommunity
- Germany
- China
- USgovDefence
This will provide us with a userCode which we can then use.
Important here is to perform the task requested. So head on over to microsoft.com/devicelogin and paste the userCode before moving forward with the API request for adding the organization.
Once we have combined everything and perform the API request, the Azure AD application will be created and the organization will be added.
Use an existing Azure AD application
When you already have an Azure AD application which you want to (re-)use, the JSON parameter will look slightly different.
{
"IsExchangeOnline": "true",
"exchangeOnlineSettings": {
"Account": "administrator@foonet.be",
"ApplicationId": "abcd1234-1234-5678-azer-12345abcdef",
"UseApplicationOnlyAuth": true,
"UseMfa": true,
"ApplicationCertificate": "BASE64STRING",
"ApplicationCertificatePassword": "XXXXXX"
},
"IsSharePointOnline": "true",
"SharePointOnlineSettings": {
"SharePointSaveAllWebParts": true,
"officeOrganizationName": "company.onmicrosoft.com",
"ApplicationId": "abcd1234-1234-5678-azer-12345abcdef",
"UseApplicationOnlyAuth": true,
"UseMfa": true,
"ApplicationCertificate": "BASE64STRING",
"ApplicationCertificatePassword": "XXXXXX"
},
"region": "worldwide",
"type": "Office365",
}
The big difference compared to creating a new Azure AD application, is the requirement of adding additional parameters to both exchangeOnlineSettings and SharePointOnlineSettings.
For exchangeOnlineSettings:
- ApplicationId: this is the existing application ID
- Account: the account used for impersonation within Exchange Online Web Services
For SharePointOnlineSettings:
- ApplicationId: this is the existing application ID
- officeOrganizationName: the name of the organization
And finally, the last part of the JSON is different as well. We now have to specify the region and the type compared to a user code, type and application name.
"region": "worldwide", "type": "Office365",
Adding an organization with MFA and legacy protocols
If you want to enable legacy protocols which provides extended functionaliy, you will work with an application ID and secret or certificate combined with a username and application password. For a full blog post on how to set this up, head over to the official Veeam blog.
The JSON parameter will look a lot like the previous ones used.
{
"type": "Office365",
"region": "Worldwide",
"isExchangeOnline": true,
"isSharePointOnline": true,
"exchangeOnlineSettings": {
"account": "administrator@company.onmicrosoft.com",
"Password": "securepassword",
"grantAdminAccess": true,
"useMfa": true,
"ApplicationId":"abcd1234-1234-5678-azer-12345abcdef",
"ApplicationSecret":"appsecret"
},
"sharePointOnlineSettings": {
"account": "administrator@company.onmicrosoft.com",
"Password": "securepassword",
"grantAdminAccess": true,
"useMfa": true,
"ApplicationId":"abcd1234-1234-5678-azer-12345abcdef",
"ApplicationSecret":"appsecret"
}
}
The big difference here is that we’ll use an ApplicationId with an ApplicationSecret combined with an account and password to grant access to the organization.
Adding an organization with basic authentication
If you still want to use the basic authentication, have a look at my initial blog post on creating your infrastructure. Keep in mind that with Microsoft changing things, this method will most likely go away in the future.
What’s next?
In the next part, we’ll discuss how to perform restores for MFA organizations and more specifically on how to log in as a tenant and perform your desired restore.
Missed a part? Have a look at the full list!
