CData Python Connector for Office 365 2019 - Online Help
Questions / Feedback?

Creating a Custom OAuth App

CData Python Connector for Office 365 2019 - Build 19.0.7416

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. In this OAuth flow, you will need to create an OAuth app: see Advanced Settings for a procedure.

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:

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

Copyright (c) 2020 CData Software, Inc. - All rights reserved.
Build 19.0.7416.0