Skip to content

OneDrive

A OneDrive file system gives IMan read and write access to a OneDrive for Business drive or a SharePoint document library, through Microsoft Graph.

IMan authenticates as a Microsoft Entra ID app registration holding an X.509 client certificate, and Graph application permissions grant it access to the drive. This is an app-only arrangement. IMan acts as itself, not on behalf of a signed-in user, so an integration can run unattended.

OneDrive for Business and SharePoint only

IMan cannot use a personal (consumer) OneDrive account. Personal accounts do not support the app-only certificate flow.

The drive's root is the root of the file system. Paths are relative to it and use forward slashes. The File Explorer opens on it. IMan writes each file in a single upload. Microsoft Graph caps a single upload at 250 MB, and a larger file fails on the write.

IMan reaches Graph at graph.microsoft.com and signs in through the public Entra endpoint. This screen cannot reach a tenant in a sovereign cloud.

Setting one up is a round trip through the Azure portal, but you can save the file system part way through. IMan can save as soon as it has the Tenant ID, Client ID, a drive target and a certificate. You do not need to upload the certificate to Azure first. Work in this order:

  1. Create the app registration and note its Tenant ID and Client ID.
  2. In IMan, enter them with the drive target, generate the certificate, copy the Public certificate box somewhere safe and save.
  3. Upload the certificate to the app registration, then grant the Graph permissions and consent to them.
  4. Test the file system.

IMan shows the public certificate once

IMan shows the Public certificate box until you save or leave the form, and does not show it again. Copy it before you save. If you lose it, tick Generate a self-signed certificate again and upload the new one.

The consent step needs a tenant administrator. You also need an IMan administrator account.

Setup > File Systems > OneDrive

The saved ONEDRVDOC file system with Type set to OneDrive, showing the Tenant ID and Client ID fields above the three drive targets, with only User Principal Name completed. Below them, Upload certificate reads Certificate loaded, and the Certificate Password box holds eight asterisks and the letters Pfx, with an eye button beside it

Tenant ID

The Entra directory (tenant) ID that the app registration belongs to.

Client ID (App registration)

The Entra application (client) ID of the app registration IMan authenticates as.

Choosing the drive

Three fields identify the drive. Complete at least one of them, using whichever one names the drive you want. If you fill more than one, IMan uses Drive ID, then Site ID, then User Principal Name, and ignores the rest.

User Principal Name

A user's own OneDrive, identified by their sign-in address, for example [email protected]. The user's Entra object ID works here too.

Site ID

A SharePoint site's default document library, identified by the site id as Microsoft Graph reports it, of the form contoso.sharepoint.com,<guid>,<guid>. Graph Explorer returns it for the request /sites/contoso.sharepoint.com:/sites/<site name>.

Drive ID (explicit, optional)

A specific Graph drive id, of the form b!.... Use this to reach a document library other than a site's default one. Graph Explorer lists a site's libraries and their ids for the request /sites/<site id>/drives.

Certificate

The X.509 certificate IMan presents to Entra. Either generate one or upload your own.

Generate a self-signed certificate — tick this and IMan creates the certificate for you.

  • Certificate Subject (CN) — the common name for the generated certificate, for example iman-onedrive-client.
  • Certificate Password (optional) — a password to protect the generated key.
  • Generate Certificate — creates the certificate and displays its public half in the Public certificate box below.

Copy the contents of that box and upload it to the app registration. It carries no private key. The private key stays in IMan, inside the encrypted file system record. There is no certificate to install on the server.

One certificate, valid for 100 years

Entra needs a single self-signed certificate. IMan generates one, unlike the authority and client pair it generates for AWS. It is valid for 100 years from the day you generate it. There is no renewal to plan.

Generate Certificate replaces the certificate every time you press it. To replace one, generate the new certificate, upload its public half to the app registration alongside the old one, save the file system and then remove the old certificate from the app registration. An app registration holds several certificates at once. The file system keeps authenticating throughout.

Uploading your own — leave the check box unticked, then use Choose certificate under Upload certificate (.pfx / .p12) to select the file, entering its Certificate Password if it has one. Upload the matching public certificate to the app registration.

When you reopen a saved file system, Upload certificate reads Certificate loaded. and the Certificate Password box beneath it shows ********, followed by the last three characters when the password is eight or more characters long. Press the eye button beside the box to show the stored password, and press it again to hide it. Showing a stored password needs the Can reveal a stored secret in full permission. To change the password, click in the box and type the new one. Leave the box empty to keep the stored password.

Setting up the app registration in Azure

The steps below outline the setup for a typical Microsoft 365 subscription. They may vary with the level of subscription and administrative privileges, and they do not cover Entra permissions in full. The Azure portal changes more often than this page, so follow the numbered steps and treat the screenshots as illustrations.

Create the app registration

  1. Sign in to the Azure portal with a user that has rights to create an app registration, and open Microsoft Entra ID then App registrations.

    The App registrations list in Microsoft Entra ID, filtered to the IMan registrations, with the New registration button above it

  2. Click New registration, give the application a name and register it.

  3. On the Overview page, note the Directory (tenant) ID and the Application (client) ID.

    The app registration Overview page, showing the Application (client) ID and the Directory (tenant) ID

  4. Return to IMan, complete the file system, generate the certificate, copy the Public certificate box and save. Saving the certificate to a .cer file makes the next step easier.

Upload the certificate

  1. Open Certificates & secrets, then the Certificates tab, and click Upload certificate.

    The Upload certificate pane with the public certificate file selected and a description entered

  2. Upload the public certificate generated by IMan and confirm. Do not create a client secret. The certificate replaces it.

Grant the Graph permissions

  1. Open API permissions, click Add a permission and select Microsoft Graph.

    The Request API permissions pane, with Microsoft Graph offered as the API to add a permission from

  2. Choose Application permissions, not delegated permissions. IMan runs with no signed-in user, and a delegated permission will not work.

    The Request API permissions pane with Application permissions selected and Files.ReadWrite.All ticked, its Admin consent required column reading Yes

  3. Add the permission that matches how far the app registration should reach:

    • Files.ReadWrite.All reaches every user's OneDrive and every SharePoint document library in the tenant. It is the only one of these permissions that serves every drive target.
    • Sites.ReadWrite.All reaches SharePoint document libraries only. Choose it where the app registration must never see a user's OneDrive.
    • Sites.Selected reaches only the SharePoint sites an administrator grants it individually, through each site's permissions. Identify the library by Site ID or Drive ID. A User Principal Name target is not a site.

    Where IMan will only read, the corresponding .Read.All permission is sufficient.

  4. Click Grant admin consent and confirm. Until an administrator grants consent, the permissions are requested but inactive. IMan then authenticates successfully, but Graph refuses access to the drive.

    The Configured permissions list with the Graph application permissions added and showing Not granted, and the Grant admin consent button above them

The first two permissions reach the whole tenant

Files.ReadWrite.All and Sites.ReadWrite.All grant access to every drive they cover, not only the one named in the file system. Where that is too broad, use Sites.Selected and grant the app registration the sites it needs. A user's OneDrive has no narrower permission.

Complete the file system in IMan

Return to the File Systems screen, open the file system and use Test to confirm the certificate authenticates and IMan can list the drive.

A successful test shows a green tick in the File System Results pane.

What the test proves

Test lists the root of the drive. It proves the certificate matches one uploaded to the app registration, that the Tenant ID and Client ID are right, that the drive target resolves and that a consented permission covers it. It writes nothing.

If the test fails

An error code beginning AADSTS — Entra refused the sign-in. The certificate does not match one uploaded to the app registration, or the Tenant ID or Client ID is wrong. Regenerating the certificate in IMan without uploading the new public half produces this too.

A Graph request failed with 404 — the drive target does not resolve. Check the User Principal Name, Site ID or Drive ID.

A Graph request failed with 403 — the certificate authenticated and the drive exists. The permission is missing, or an administrator has not consented to it.

Watching a drive

To trigger an integration from activity in the drive, tick Enable native change notifications and optionally set a Poll Interval.

OneDrive needs no queue. IMan detects changes by running a Microsoft Graph delta query against the drive on each poll. Poll Interval (seconds, optional) sets how often. Leave it empty and IMan polls every 15 seconds.

A File Event on a OneDrive file system can watch for Created, Modified and Deleted. A File Event cannot watch for Renamed, because the delta feed reports a renamed item as an ordinary change that looks the same as an edit. A file moved within the drive arrives the same way, as Modified at its new path, and IMan reports nothing at the old one. Folders never appear in the feed. Creating or deleting a folder triggers nothing.

The File Event's Path does not narrow which events fire

On a cloud file system, a File Event matches events on file name alone. Its Path does not restrict them. The delta query covers the whole drive. A File Event on inbox with the filter *.csv also fires when a matching file lands anywhere else in the drive, including a folder the integration itself writes to. Name the files that a File Event should react to with a pattern that nothing else in the drive uses.

The first poll, and every Scheduler restart, reports the whole drive

IMan holds its place in the delta feed in memory. On the first poll after you enable notifications, and again whenever the Realisable Scheduler Service restarts, IMan has no place to resume from and enumerates the entire drive. IMan reports every file in it again. It reports a file as Created if nobody has edited it since its upload, and as Modified otherwise. A File Event watching either triggers its integration as though the files had just arrived.

An integration that reads a OneDrive file system must tolerate files it has already processed. See File Events for what this means in practice.