Authenticating to OneDrive
OneDrive uses the OAuth authentication standard. To authenticate using OAuth, you will need to create an app to obtain the OAuthClientId, OAuthClientSecret, and CallbackURL connection properties.
Using OAuth Authentication
OAuth requires the authenticating user to interact with OneDrive using the browser. The provider facilitates this in various ways as described below.
You will need to register an app to obtain the OAuthClientId and OAuthClientSecret.
You need to create an OAuth app to use in the web flow.
You need to create an OAuth app.
In the headless OAuth flow, users need to authenticate via a browser on another machine. You will need to create a custom OAuth app.
Creating a Custom OAuth App
To connect to OneDrive, you authenticate to Azure AD. Azure AD implements the OAuth authentication standard. The provider facilitates OAuth in various ways as described below.
Create and Configure a Custom OAuth App
This step is only necessary for Web applications.
Desktop applications can use the provider's embedded credentials. You can register your own application to customize the permissions the provider requests or to display your own information, instead of provider information, when users log into OneDrive to grant permissions to the provider.
Create the App
You can follow the procedure below to register an app. To register an application, you will need both a OneNote for business account and an Azure AD subscription associated with your OneNote for business account.
- In the Azure portal, click Azure Active Directory.
- Click App Registrations on the Overview section and then click 'New registration'.
- In the resulting dialog, enter a name to be displayed to users when they are prompted to grant permissions to your application.
- Select the Web App/Web API option in the Application Type menu (the provider makes calls to the Microsoft Graph API).
- Select a Sign-On URL. This value is not used by the provider or in the authentication step, so it can be set to your home page or an arbitrary URL like http://localhost.
- Click Create.
Configure the App
Follow the steps below to obtain the OAuth client credentials and configure the permissions your app will request.
- Select the new app. On the resulting section, the Application Id is displayed. That is the value of the OAuthClientId property you need to set.
- If users in other organizations will use your app to connect to data in their own organization, select Properties on the Settings section. On the section that appears, select Yes in the Multi-Tenanted option.
- Select 'Certificates & secrets' on the 'Manage' section. Press 'New client secret' to create a new OAuthClientSecret. Add a description for the Key, select the expiration time and click Add. The new Client Secret's value is then displayed. Copy and save that value and use it on the OAuthClientSecret property.
Click Reply URLs on the Settings section.
If you are making a desktop application, set the Reply URL to http://localhost:33333, or another port of your choice. Note that you must specify the port that the provider will listen on.
If you are making a Web application, set the Reply URL to a page of your app where you would like users to return after they authorize your application.
- Select 'API permissions' on the 'Manage' section and then click 'Add a permission'. Select the Microsoft Graph API and then add the permissions your app will seek. Hit the 'Grant admin consent' button afterwards for the new permissions to take effect.
Select App Permissions
The Files.ReadWrite.All delegated permission allows access to the full functionality of the provider.
Alternatively, you can select the permission Files.Read.All.
Customizing the SSL Configuration
By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.
Connecting Through a Firewall or Proxy
To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.
In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.
Set the following properties:
- To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
- To tunnel the connection, set FirewallType to TUNNEL.
- To authenticate, specify FirewallUser and FirewallPassword.
- To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.
Troubleshooting the Connection
To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
- The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. If you are using a self-signed certificate, there is only one certificate in the chain.
To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.
- DirectoryRetrievalDepth: How many folders deep you want to get results for Folders, Files, SharedResources and Permissions tables.
- DriveId: The ID of the Drive that you want to use when getting data for tables Files, Folders, SharedResources and Permissions.
- ListGroupDrives: Indicates if you would like to list your group drives or not when querying the Drives table. Useful if you're using a OneDrive for Business account.