There are two ways that Users and Files may be imported from a Microsoft organization directory into a Curiosity system. It may be enabled by piggy backing onto an existing Microsoft Single Sign-On "application" or it may be enabled by creating a separate Microsoft application specifically for this import process.

The first approach is easier and will be described first. The second approach will be covered further down in this article. At a certain point, the two approaches converge and these common instructions will appear in the third section below.

When already using Microsoft Single Sign-On (SSO)

This presumes that you have

  • followed all of the steps in the Microsoft Single Sign-On article

  • that you still have administrative privileges to make the changes to your Azure organization

  • that you still have an administrator account for your Curiosity application.

Return to https://portal.azure.com, go to the "App registrations" page by searching for that term in the search bar at the top and then click on the application that you created to enable SSO.

You will have to give this application additional permissions, so click on the API permissions link in the left hand menu.

The permissions from an SSO-enabled Microsoft / Azure application would look like this currently:

To add the permissions required for importing, click the + Add a permission and then select the Microsoft Graph option that appears. Then click Delegated permissions from the next screen.

Use the search bar to locate and tick the following:

  • Directory.AccessAsUser.All

  • Files.Read.All

  • Group.Read.All

  • Sites.Read.All

  • User.ReadBasic.All

  • offline_access

Click Add permissions and the "Configured permissions" list should now look like the following:

Click Grant admin consent.

Finally, an additional "Redirect URI" is required for authorizing file access. Click on Authentication in the left hand menu and there will already be "Redirect URIs" entry in the "Web" section from when SSO was configured. Click Add URI, copy the existing value into the text box and change the URI segment "microsoftsso" to "onedriveimportauth". Click Save. If you are using a local installation of Curiosity then it should now look like this:

If your Curiosity system is cloud-hosted or internally hosted elsewhere, it will be fine so long as you copy and edit the existing URI.

Now the application configuration is complete on the Microsoft side and you are ready to jump to the third section of this article ("Creating a scheduled import task in Curiosity").

Skip over the next section, which is for Curiosity systems that do not use Microsoft SSO—unless you have additional Microsoft organizations that you wish to also import data from (it is possible to create multiple Data Connectors, as described in the third section, if you wish to do this).

Importing from a Microsoft organization that is not being used for SSO purposes in Curiosity

When you do not already have an "app registration" configured in Azure for SSO that you can extend for import files with, you have to create one specifically for the import task.

Each "application" will have three pieces of information (collectively referred to as its "credentials"):

  • a "Tenant ID" (also known as a "Directory ID")

  • a "Client ID" (also known as an "Application ID")

  • a "Client Secret"

You will require a Microsoft / Azure account for your organization that has administrative privileges. Log into Microsoft with that account and then go to https://portal.azure.com.

Click into the search bar at the top of the page and starting typing "app registrations" until the autocomplete box shows "App registrations" and as an option.

Click on the "App registrations" button and then click + New registration.

Enter a name such as "Curiosity Import".

Leave the "Who can use this application or access this API?" option as "Accounts in this organizational directory only".

Ensure that "Web" is selected in the drop-down list under "Redirect URI (optional)".

Each User that wishes for their files to be imported into Curiosity will have to individually authorize that access and this process will start within Curiosity but will redirect the User to Microsoft to log in to their account there. After this, they will be redirected back to Curiosity and so you need to tell this Azure application how to get back to Curiosity. This is the purpose of the Redirect URI. The format of the URI is:

{domain}/api/onedriveimportauth/completed-login-attempt

If your Curiosity application is hosted by us then it will look something like this:

https://acmecompany.curiosity.sh/api/onedriveimportauth/completed-login-attempt

If you have installed a local instance of the application with the default settings then it will look like this:

http://localhost:8080/api/onedriveimportauth/completed-login-attempt

Click Register.

The "Overview" page that is shown next has the first two pieces of information that you require, the "Application (client) ID" and "Directory (tenant) ID" -

Both consist of five sections of alphanumeric characters, separated by hyphens.

Generate a Client Secret by clicking on "Certificates & secrets" in the menu on the left and then clicking on + New client secret in the "Client secrets" section.

Enter a description - it's fine to use something like "Curiosity Import" again here.

Set "Expires" to Never.

Click Add.

There will now be a new row in the "Client secrets" section that shows the description and the secret's "Value" - this is a long piece of text consisting of upper and lower case letters, numbers, and symbols.

Important: Copy the value now because you will not be able to see it again!

Click API permissions in the left hand side menu, then + Add a permission, then select the Microsoft Graph option that is presented.

Next click Delegated permissions and use the search bar to locate and tick the following:

  • Directory.AccessAsUser.All

  • Files.Read.All

  • Group.Read.All

  • Sites.Read.All

  • User.ReadBasic.All

  • offline_access

Click Add permissions and the "Configured permissions" list should now look like the following:

Click Grant admin consent.

Now the application configuration is complete on the Microsoft side, you have the required three components of the credentials (Tenant ID, Client ID, Client Secret), and you are ready to perform the configuration required in Curiosity.

Configuring Curiosity

Within Curiosity, it will be necessary to configure a Data Connector that uses the Microsoft / Azure application to import the data. It will also be necessary for each User to individually authorize access to the Microsoft resources that they have access to (which will be covered later).

This individual authorization approach respects the permissions applied to the files within the Microsoft file store and ensures that only files relating to particular Users (either that they created or that have been shared with them) are imported.

It will not blindly import all files from the Microsoft organization. This is important as there may be particular Shared Libraries and User drives that should be imported while confidential information belonging to other Users should not be.

Within Curiosity, click the menu button at the top left, then click Sources Hub and then Microsoft Graph.

Click + Add and enter descriptive names for the "Name" and "Source".

At this point, you will either enable Use Credentials From Azure SSO If Enabled and leave Tenant ID, Client ID, and Client Secret blank (if you are importing the data using the first approach from this article) or you leave Use Credentials From Azure SSO If Enabled disabled and enter your credentials into those three boxes.

The "User File Import Permissions" and "Shared Library Import Permissions" options are explained in a section at the end of this article. For most use cases, the default options are appropriate.

For information about scheduling tasks and running them outside of their schedule, click here.

Click Save.

You will now see an entry in the Microsoft Graph list that looks like this:

Completing the configuration by authorizing access to data

If this task were to be run now then the logs would show zero items imported from zero accounts because each Microsoft account has to individually authorize access to its files. To do this for your account, click on the task again and then Authorize (this button is only enabled after the task has been configured and saved - note earlier, the button was present but disabled).

This will redirect you to a Microsoft page where you can log in and will then be asked to grant permissions. The permissions relate to those you set earlier in the "Configured permissions" list in the Azure portal, so they are all about reading data (no writing back from Curiosity to Microsoft can occur).

You will be redirected back to the "Sources Hub" page in Curiosity. The "Microsoft Graph" section now shows "1 active source".

If you click Microsoft Graph again and then select the task that you just configured, you will see that the Authorize button has been replaced with a key icon to indicate that your account has been authorized for data to be imported into Curiosity.

If you need to repeat the authorization process in the future, the key icon is a button that will take you through the Microsoft login-and-authorize process again.

In order to get all of the data for all of the Users whose data you want to import, each of them must individually log in and authorize access to their data. Non-Admin Users do not have access to the "Sources Hub", which is documented in the User Guide "Import your Files from other Data Sources".

Note that files are only imported when the file's owner has authorized that their data be imported, even if that file has been shared with others and they have authorized access to their data. This is described in more detail in the section further down about permissions.

When files are imported, if other Users in the Microsoft organization have access to those files and there are no User accounts in Curiosity yet for these people, Curiosity User accounts will automatically be created. If Curiosity User accounts do already exist (for example, if they have previously logged into Curiosity through the "Microsoft / Azure Single Sign On " integration)then these already-existing Curiosity User accounts will be given appropriate access to the imported files.

You have now completed the configuration of this import task! As an administrator of your Curiosity system, it makes sense to explicitly contact Users that have data in Microsoft that you want imported, so that they can log in and authorize access.

Which files, Users, and permissions are imported

It's important to note that files are only imported when the owner of that file has authorized that their data be imported. It is not sufficient for the importing of a particular file that a User that the file has been shared with to authorize access to their data if the owner of that file has not also authorized access.

For example, if -

  1. Alice shares a "ReviewOf2020.docx" with Bob

  2. Bob authorizes Curiosity to import his files but Alice does not

  3. When the import of Bob's data is performed, the file will not be included in that import (even though he has access to it in the Microsoft organization)

If Alice later does authorize access to her files then the document will be imported next time that the import task is run and both Alice and Bob will have access to it within Curiosity.

When files are imported that are shared with other Users in the Microsoft organization, if there is already a Curiosity User account with a matching email address then they will be given access to the file. If no Curiosity account exists for them then one will be created.

A note about "sharing" of files: A file is considered to be shared with someone if that second person has been given access to it via a link and they have opened the document via that link. For example, if Alice shares a file with Bob but Bob has never opened that file in OneDrive then it will not be considered to have been shared with him. This enables an individual to configure a file to be shared with the entire organization but for the link to that file to be treated as a "secret"—anyone in the organization that is provided with the link and opens it is then considered to have access to it and this is reflected in the access rights that are imported into Curiosity.

The above description presumes that the "Import Permissions" on the import task were left at the default values:

The other "User File Import Permissions" options are:

  1. Do Not Import

  2. Import As Private To Owner

  3. Import As Public To All Users

The first means that files from User drives will not be imported at all.

The second means that files from User drives will be imported but the information about which other Users will not be. This means that the files in Curiosity will only be accessible by the User that owns them. This works best when that User can log into Curiosity via SSO but the alternative is to explicitly set a password on the User account that the import process created and have that User log in with their Microsoft organization email and that password.

The third means that files from User drives will be imported and made available to every User of the Curiosity system.

The other "Shared Library Import Permissions" options are:

  1. Do Not Import

  2. Import As Public To All Users

These act in the same manner as these two options for User drives.

Did this answer your question?