OneDrive Connector

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

SharePoint document libraries. Only the SharePoint sites the user is following will be listed. This is not present 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 their 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: select the Web platform option and then 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 something 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. If desired, select Token configuration to add the optional upn claim to the ID token. This is usually not necessary; See credential mapping.

  7. 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.

  8. App registration is complete.

OneDrive Configuration Encryption

All configuration information, including OneDrive secrets and user credential information, is encrypted with a secret key on the node servicing the request before storing it locally and uploading it to GCS cloud services for distribution to other nodes in the endpoint. The encryption key is only available locally to the node and is secured such that only the node admin has access.

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.

When registering credentials, the Microsoft account username must match the mapped username on the collection (by default the Globus account username, unless identity mapping is configured). The Microsoft account username is determined from the preferred_username claim of the MS ID token as long as it is an email address, otherwise the email claim is used. In most cases the preferred_username claim will be correct, but if the optional upn claim is enabled in the app registration, that will be used instead.

Alternately, the storage-gateway --ms-allow-any-account command-line option can be set to allow access to any Microsoft account.

Empty files

The Creation of empty files is now supported. (new in 5.4.64)

Limitations

Items shared via OneDrive from an external Azure Tenant are not currently accessible via Globus.

Items shared via OneDrive links (eg. if you receive a link via e-mail) are not accessible via Globus.

Appendix A: Document Types for the OneDrive Connector

OneDriveStoragePolicies Document

Connector-specific storage gateway policies for the OneDrive connector

One of the following schemas:

​

{
  "DATA_TYPE": "onedrive_storage_policies#1.0.0",
  "auth_callback": "string",
  "client_id": "string",
  "secret": "string",
  "tenant": "string",
  "user_api_rate_limit": 0
}

OneDriveUserCredentialPolicies Document

Connector-specific user credential policies for the OneDrive connector

One of the following schemas:

​

{
  "DATA_TYPE": "onedrive_user_credential_policies#1.0.0",
  "access_token": "string",
  "email": "string",
  "refresh_token": "string",
  "scopes": [
    "openid",
    "email",
    "profile",
    "offline_access",
    "files.readwrite.all"
  ],
  "sub": "string",
  "tid": "string",
  "token_expiry": "2019-08-24T14:15:22Z"
}

Appendix B: User Consents and Access Control

If a user grants consent for sites.readwrite.all during their MS login process, even if the Azure App configuration does not explicitly allow it, the GCS credential flow will include the permission.

To restrict access to only the desired paths (e.g. preventing access to /Shared), Endpoint Admins can leverage Restrict Paths policies.