Last Updated: May 5, 2021

The Globus OneDrive storage connector can be used for access and sharing of data on Microsoft OneDrive. The connector is available as an add-on subscription to organizations with a Globus Standard subscription - please contact us for pricing.

This document describes how to install the OneDrive Connector and configure OneDrive Storage Gateways and Collections. After these steps are complete, any Globus user you have authorized can register a credential to access OneDrive files that they have access to and, if enabled, can create guest collections for sharing access using those credentials by following the instructions in How To Share Data Using Globus.

This document assumes that you or another administrator has already installed Globus Connect Server v5.4.21 or higher on all data transfer nodes, and that you have an administrator role on that endpoint.

The installation must be done by a system administrator, and has the following distinct set of steps:

  • Register a Microsoft Azure Application which the connector will use to access the OneDrive APIs.

  • Create a storage gateway on the endpoint configured to use the OneDrive Connector.

  • Create a mapped collection using the OneDrive Storage Gateway to provide access to OneDrive Storage Gateway data.

Please contact us at support@globus.org if you have questions or need help with configuration and use of the OneDrive Connector.


OneDrive Connector Virtual Filesystem

OneDrive presents its data as a hierarchical list of files and folders, much like a POSIX filesystem.

The OneDrive Connector provides these subdirectories at the root directory of a OneDrive Connector storage gateway:

/My files

The user’s OneDrive storage. This is treated as the home directory on collections created using the OneDrive Connector.

/Shared

Files and directories that have been shared with the user.

/Shared libraries

The Shared document libraries that the user is following (not available on OneDrive Personal accounts).

Registration of endpoint with Microsoft

The Globus Connect Server v5 endpoint needs to be registered as an application with Microsoft so that users can authorize the endpoint to access OneDrive on their behalf. The following steps describe how the endpoint can be registered as an Azure application to obtain a client id and secret.

Prerequisites

It is necessary that these steps be performed on a fully functional Globus Connect Server 5 endpoint.

You will need a Microsoft account to complete these steps, and the registration will be stored under that account. This account is only for registration of the application and has no bearing on which user accounts will be allowed to use this endpoint to access data.

Supported Account Types

One of the application settings is Supported Account Types. This defines which user accounts will be able to access their OneDrive storage with this connector. The options are:

  • Single Tenant: Only users from the same organization as the application registration will be able to log in and access thier storage.

  • Multitenant: Users from any organization will be able to log in and access their storage. However, the application will require an organization admin’s approval before its users may log in. See Grant tenant-wide admin consent to an application.

  • Multitenant and Personal Accounts: Any organization and any OneDrive personal users will be able to log in and access their storage. As with multitenant, the application will require an organization admin’s approval before its users may log in. OneDrive Personal users may log in without approval.

  • Personal Accounts: Only OneDrive Personal users will be able to log in and access their storage.

Registration Steps

  1. To register the endpoint with Microsoft, go to Microsoft Azure App registrations

  2. Select + New registration to add a new registration.

    1. For Name, enter a name such as Globus Connect Server. This will be displayed to users of your collection when they are prompted to log in to Microsoft during credential registration.

    2. For Supported account types choose the desired account type. See Supported Account Types.

    3. For Redirect URI: set the value that was displayed when the endpoint was created.

      If you don’t have that value handy, you can run the command

      globus-connect-server endpoint show

      You’ll see output that looks somthing like this:

      Display Name:    Test Endpoint
      ID:              669ec822-ca79-455c-89a7-cccb7aefbf8e
      Subscription ID: 6e62e6d7-e368-45f4-a23d-fb41243e8005
      Public:          True
      GCS Manager URL: https://21542.data.globus.org
      Network Use:     normal

      You can construct the auth callback URL by appending /api/v1/authcallback to the value of the GCS Manager URL. In this example case, the result is https://21542.data.globus.org/api/v1/authcallback.

    4. Select Register

  3. Select API permissions to configure the permissions required for OneDrive access.

    1. Select +Add a permission

      1. Select Microsoft Graph, and then Delegated permissions.

      2. Under OpenId permissions, check email, offline_access, openid, profile.

      3. Under Files, check Files.ReadWrite.All.

      4. Under User, check User.Read.

      5. Under Sites, check Sites.ReadWrite.All. This is only required if access to shared document libraries is desired.

      6. Select Add permissions to save these selections

  4. Select Certificates & secrets to create a secret

    1. Select + New client secret

      1. Enter a description and choose an expiration time, if desired. The storage-gateway will need to be updated if the secret changes.

    2. Make note of the Value. This will be used to configure the storage gateway --ms-client-secret option

  5. If desired, select Branding to configure additional login screen details.

  6. Select Overview

    1. Note the Application (client) ID. This will be used to configure the storage gateway --ms-client-id option.

    2. If you chose Single Tenant for supported account types, note the Directory (tenant) ID. This will be used to configure the storage gateway --ms-tenant option.

  7. App registration is complete.

Storage Gateway

A OneDrive Storage Gateway is created with the command globus-connect-server storage-gateway create onedrive, and can be updated with the command globus-connect-server storage-gateway update onedrive.

Before looking into the policy options specific to the OneDrive Connector, please familiarize yourself with the Globus Connect Server v5 Data Access Guide which describes the steps to create and update a storage gateway, using the POSIX connector as an example. The commands to create and update a storage gateway for the OneDrive Connector are similar.

OneDrive Connector Storage Gateway Policies

The OneDrive Connector has policies to manage application credentials, and set the user api rate limit.

Application Credentials

The --ms-client-id and --ms-client-secret command-line options provide information for Globus Connect Server to authenticate with OneDrive Connector. These values must be configured in order to be able to access data on collections created with the OneDrive Connector type.

These are configured after registering the application with Microsoft as described in the OneDrive Connector configuration guide.

Example 1. Setting OneDrive Connector Application Credentials.

For our example, we’ll assume we’ve obtained credentials as described above. We’ll use the command-line options --ms-client-id and --ms-client-secret to configure these on our storage gateway.

    --ms-client-id CLIENT_ID \
    --ms-client-secret CLIENT_SECRET

If the application is registered with Supported Account Types set to Single Tenant, the command-line option --ms-tenant is also required. This should be set to the tenant id of the organization.

    --ms-tenant TENANT_ID

User API Rate Limit

The optional --ms-user-api-rate-limit command-line option allows you to configure a value for the User API Rate Limit in order to try to avoid throttling issues when interacting with the OneDrive API. While the connector will attempt to gracefully handle retries when throttling occurs, it is better to avoid throttling. The value of the setting is a number of API operations per second per user. Microsoft does not publish explicit rate limits, but the connector default is set at 20 requests per second.

Example 2. Setting a User API Rate Limit

For our example, we’ll use the default. If we wanted to set a limit of 25 operations per second per user, we would use the following --ms-user-api-rate-limit option.

    --ms-user-api-rate-limit 25

Creating the Storage Gateway

Now that we have decided on all our policies, we’ll use the command to create the storage gateway.

% globus-connect-server storage-gateway create onedrive \
    "OneDrive Storage Gateway" \
    --domain example.org \
    --ms-client-id CLIENT_ID \
    --ms-client-secret CLIENT_SECRET

Storage Gateway Created: 7187a9a0-68e4-48ea-b3b9-7fd06630f8ab

This was successful and outputs the ID of the new storage gateway ( 7187a9a0-68e4-48ea-b3b9-7fd06630f8ab in this case) for our reference. Note that this will always be a unique value if you run the command. If you forget the id of a storage gateway, you can always use the command globus-connect-server storage-gateway list to get a list of the storage gateways on the endpoint.

You can also add other policies to configure additional identity mapping and path restriction policies as described in the Globus Connect Server v5 Data Access Guide.

Note that this creates the storage gateway, but does not yet make it accessible via Globus and HTTPS. You’ll need to follow the steps in the next section.

Collection

A OneDrive Collection is created with the command globus-connect-server collection create, and can be updated with the command globus-connect-server collection update.

As the OneDrive Connector does not introduce any policies beyond those used by the base collection type, you can follow the sequence in the Collections Section of the Globus Connect Server v5 Data Access Guide. Recall however, that the paths are interpreted as described above in OneDrive Connector Virtual Filesystem.

User Credential

As mentioned above, access to mapped collections on a OneDrive require users to register credentials. These credentials are created by performing an authentication flow with Microsoft. This is initiated by visiting the Credentials tab of the collection. The user is directed to that page when they first attempt to access that collection.

Appendix A: Limitations

Empty files

OneDrive does not allow the creation of empty files (size 0), so transfers of these files will fail.

Appendix B: Document Types for the OneDrive Connector

OneDriveStoragePolicies Document

This type describes the public and private policies for a OneDrive Storage Gateway.

Name

Type

Description

DATA_TYPE

string onedrive_storage_policies#1.0.0

Type of this document

client_id

string

Client ID registered with the Azure console to access OneDrive.[Private]

secret

string

Secret created in the Azure console to access OneDrive with the client_id in this policy.[Private]

tenant

string

Tenant ID of the Microsoft organization. Required when Supported Account Types of the Azure application is set to Single tenant.[Private]

user_api_rate_limit

integer

User API Rate Limit associated with this client ID in operations per second per user.[Private]

auth_callback

string <uri>

URL of the auth callback that must be registered on the Azure console for the application client_id in order to process Microsoft credentials.

{
  "DATA_TYPE": "onedrive_storage_policies#1.0.0",
  "client_id": "string",
  "secret": "string",
  "tenant": "string",
  "user_api_rate_limit": 1000,
  "auth_callback": "https://example.globus.org/api/v1/authcallback"
}

OneDriveUserCredentialPolicies Document

The OneDriveUserCredentialPolicies document describes the OneDrive-specific policy information included in a UserCredential. This document contains read-only data about the user’s credentials.

Name

Type

Description

DATA_TYPE

string onedrive_user_credential_policies#1.0.0

Type of this document

sub

string

OAuth subject identifier claim.

email

string <email>

OAuth email claim.

access_token

string

OAuth access token.

refresh_token

string

OAuth refresh token.

scopes

array (string)

OAuth scopes associated with this access token.

token_expiry

string <date-time>

OAuth access token expiration time.

{
  "DATA_TYPE": "onedrive_user_credential_policies#1.0.0",
  "sub": "string",
  "email": "user@example.com",
  "access_token": "string",
  "refresh_token": "string",
  "scopes": [
    "openid",
    "email",
    "profile",
    "offline_access",
    "files.readwrite.all"
  ],
  "token_expiry": "2020-02-04T21:44:12Z"
}