Skip to content

Latest commit

 

History

History
146 lines (109 loc) · 7.54 KB

national-cloud-deployments.md

File metadata and controls

146 lines (109 loc) · 7.54 KB
Raw

How to configure access to specific Microsoft Azure deployments

Caution

Before reading this document, please ensure you are running application version Version or greater. Use onedrive --version to determine what application version you are using and upgrade your client if required.

Process Overview

In some cases it is a requirement to utilise specific Microsoft Azure cloud deployments to conform with data and security requirements that requires data to reside within the geographic borders of that country. Current national clouds that are supported are:

  • Microsoft Cloud for US Government
  • Microsoft Cloud Germany
  • Azure and Office365 operated by VNET in China

In order to successfully use these specific Microsoft Azure deployments, the following steps are required:

  1. Register an application with the Microsoft identity platform using the Azure portal
  2. Configure the new application with the appropriate authentication scopes
  3. Validate that the authentication / redirect URI is correct for your application registration
  4. Configure the onedrive client to use the new application id as provided during application registration
  5. Configure the onedrive client to use the right Microsoft Azure deployment region that your application was registered with
  6. Authenticate the client

Step 1: Register a new application with Microsoft Azure

  1. Log into your applicable Microsoft Azure Portal with your applicable Office365 identity:
National Cloud Environment Microsoft Azure Portal
Microsoft Cloud for US Government https://portal.azure.com/
Microsoft Cloud Germany https://portal.azure.com/
Azure and Office365 operated by VNET https://portal.azure.cn/
  1. Select 'Azure Active Directory' as the service you wish to configure
  2. Under 'Manage', select 'App registrations' to register a new application
  3. Click 'New registration'
  4. Type in the appropriate details required as per below:

application_registration

  1. To save the application registration, click 'Register' and something similar to the following will be displayed:

application_registration_done

Note

The Application (client) ID UUID as displayed after client registration, is what is required as the 'application_id' for Step 4 below.

Step 2: Configure application authentication scopes

Configure the API permissions as per the following:

API / Permissions name Type Description Admin consent required
Files.ReadWrite Delegated Have full access to user files No
Files.ReadWrite.All Delegated Have full access to all files user can access No
Sites.ReadWrite.All Delegated Have full access to all items in all site collections No
offline_access Delegated Maintain access to data you have given it access to No

authentication_scopes

Step 3: Validate that the authentication / redirect URI is correct

Add the appropriate redirect URI for your Azure deployment:

authentication_response_uri

A valid entry for the response URI should be one of:

For a single-tenant application, it may be necessary to use your specific tenant id instead of "common":

Step 4: Configure the onedrive client to use new application registration

Update to your 'onedrive' configuration file (~/.config/onedrive/config) the following:

application_id = "insert valid entry here"

This will reconfigure the client to use the new application registration you have created.

Example:

application_id = "22c49a0d-d21c-4792-aed1-8f163c982546"

Step 5: Configure the onedrive client to use the specific Microsoft Azure deployment

Update to your 'onedrive' configuration file (~/.config/onedrive/config) the following:

azure_ad_endpoint = "insert valid entry here"

Valid entries are:

  • USL4 (Microsoft Cloud for US Government)
  • USL5 (Microsoft Cloud for US Government - DOD)
  • DE (Microsoft Cloud Germany)
  • CN (Azure and Office365 operated by VNET in China)

This will configure your client to use the correct Azure AD and Graph endpoints as per https://docs.microsoft.com/en-us/graph/deployments

Example:

azure_ad_endpoint = "USL4"

If the Microsoft Azure deployment does not support multi-tenant applications, update to your 'onedrive' configuration file (~/.config/onedrive/config) the following:

azure_tenant_id = "insert valid entry here"

This will configure your client to use the specified tenant id in its Azure AD and Graph endpoint URIs, instead of "common". The tenant id may be the GUID Directory ID (formatted "00000000-0000-0000-0000-000000000000"), or the fully qualified tenant name (e.g. "example.onmicrosoft.us"). The GUID Directory ID may be located in the Azure administration page as per https://docs.microsoft.com/en-us/onedrive/find-your-office-365-tenant-id. Note that you may need to go to your national-deployment-specific administration page, rather than following the links within that document. The tenant name may be obtained by following the PowerShell instructions on https://docs.microsoft.com/en-us/onedrive/find-your-office-365-tenant-id; it is shown as the "TenantDomain" upon completion of the "Connect-AzureAD" command.

Example:

azure_tenant_id = "example.onmicrosoft.us"
# or
azure_tenant_id = "0c4be462-a1ab-499b-99e0-da08ce52a2cc"

Step 6: Authenticate the client

Run the application without any additional command switches.

You will be asked to open a specific URL by using your web browser where you will have to login into your Microsoft Account and give the application the permission to access your files. After giving permission to the application, you will be redirected to a blank page. Copy the URI of the blank page into the application.

[user@hostname ~]$ onedrive 

Authorize this app visiting:

https://.....

Enter the response uri:

Example:

[user@hostname ~]$ onedrive 
Authorize this app visiting:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=22c49a0d-d21c-4792-aed1-8f163c982546&scope=Files.ReadWrite%20Files.ReadWrite.all%20Sites.ReadWrite.All%20offline_access&response_type=code&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient

Enter the response uri: https://login.microsoftonline.com/common/oauth2/nativeclient?code=<redacted>

Application has been successfully authorised, however no additional command switches were provided.

Please use --help for further assistance in regards to running this application.