Office 365 Advanced Settings

To connect to Office 365, 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 Office 365 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 an Office 365 for business account and an Azure AD subscription associated with your Office 365 for business account.

1. In the Azure portal, click Azure Active Directory.
2. Click App Registrations on the Overview blade and then click New application registration.
3. In the resulting dialog, enter a name to be displayed to users when they are prompted to grant permissions to your application.
4. Select the Web App/Web API option in the Application Type menu. (The provider makes calls to the Microsoft Graph API.)
5. 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.
6. Click Create.

Configure the App

Follow the steps below to obtain the OAuth client credentials and configure the permissions your app will request.

1. Select the new app. On the resulting blade, the Application Id is displayed. You will need to set the OAuthClientId property to this.
2. If users in other organizations will use your app to connect to data in their own organization, select Properties on the Settings blade. On the blade that appears, select Yes in the Multi-Tenanted option.
3. Select Keys on the Settings blade. Provide a description for the Key and select a duration in the menu and click Save. The key value is then displayed. Copy and save the key value, the value for OAuthClientSecret.

4. Click Reply URLs on the Settings blade.

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

6. Select Required Permissions on the Settings blade and then click Add on the resulting blade. Select the Microsoft Graph API and then select the permissions your app will seek. Hit the Grant Permissions button afterwards for the new permissions to take effect.

Select App Permissions

The following delegated permissions allow access to the full functionality of the provider.

• Have full access to all files user can access.
• Have full access to user contacts.
• Have full access to user calendars.
• Send mail as a user.
• Read and write access to user mail.
• Access directory as the signed-in user.
• Read and write all groups.

Authenticate to Office 365 from a Desktop Application

You can connect with the provider's embedded OAuth credentials. To do so, set InitiateOAuth to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

To use a custom app's OAuth credentials, set the following connection properties when you connect:

• OAuthClientId: Set this value to the Application Id in your app settings.
• OAuthClientSecret: Set this value to the key value in your app settings.
• CallbackURL: Set this value to the Reply URL in your app settings.
• InitiateOAuth: Set this value to GETANDREFRESH.

When you connect to data, the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

1. Extracts the access token from the callback URL and authenticates requests.
2. Exchanges the returned refresh token for a new, valid access token.
3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Authenticate to Office 365 from a Web Application

You can use the OAuth flow for Web applications to connect via a Web application or when the provider is not authorized to open a browser window. 

To obtain the OAuthAccessToken, set the following connection properties:

• OAuthClientId: Set this value to the Application Id in your app settings.
• OAuthClientSecret: Set this value to the key value in your app settings.
• CallbackURL: Set this value to the Reply URL in your app settings.

When you connect via a Web application, you exchange temporary verification values for the access token. With the preceding properties set, follow the steps below to call stored procedures to complete the exchange:

1. Call GetOAuthAuthorizationURL. The stored procedure returns the URL to the OAuth endpoint.

2. Log in and authorize the application. You are redirected back to the URL you specified as the callback URL.

   When you are redirected, the callback URL contains the verifier in the code query string parameter.

3. Call the GetOAuthAccessToken stored procedure with the following parameters set:

    

   Name	Value
   AuthMode	WEB
   Verifier	Set this to the verifier code.

    

To make requests to Office 365, set OAuthAccessToken to the values returned in step 3.

 To automatically refresh the OAuthAccessToken when it expires, set InitiateOAuth=GETANDREFRESH.

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

HTTP Proxies

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.

Other Proxies

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.