Configuring an ADF Linked Service Connection for Office 365
For information on how to enable a connection for use with linked services, see Configuring a Linked Service Connection.
Field labels in this walkthrough follow the underlying Azure Data Factory property names, with the connection column that carries each value named alongside. The exact labels shown in the BimlFlex Connection Editor may differ.
After selecting Office 365 from the Linked Service Type dropdown, the form required for creating an Office 365 Linked Service will appear.
Source Only Connector
An Office 365 connection is used as a source. It is not available as a target.
Each Office 365 object is copied whole from the Microsoft 365 table that the dataset names through the TargetObjectName parameter. The copy has no source query, and the copy source passes the TargetSchemaName and TargetObjectName parameters.
The copy source reads the setting keys below from the object's settings. Each key is a setting of the Setting Editor's Azure group, in the section Data Factory Copy Source Members, with the label the table names. These settings are blank by default. A key is written to the copy source only when it holds a value, and none of the keys carries a default.
| Setting key | Label | ADF copy source property | Value |
|---|---|---|---|
allowedGroups | Allowed Groups | allowedGroups | A comma separated list of user groups, each written as one entry of the list |
userScopeFilterUri | User Scope Filter Uri | userScopeFilterUri | A Microsoft Graph filter applied across the tenant (for example, https://graph.microsoft.com/v1.0/users?$filter=Department eq 'Finance') |
dateFilterColumn | Date Filter Column | dateFilterColumn | The name of the DateTime column that limits the time range |
startTime | Start Time | startTime | The start DateTime value of the range |
endTime | End Time | endTime | The end DateTime value of the range |
outputColumns | Output Columns | outputColumns | A comma separated list of column names, each written as one name entry of the list |
The value of a setting with the key applies to every Office 365 object, and a Setting Override on an object sets the value for that object. Add on the Azure group's Overrides tab opens the Add Setting Override form, where the Attribute Type is Object, the Connection and the Object select the object, the Setting is picked by its label (shown as Allowed Groups (Data Factory Copy Source Members)), and the Override Value holds the member's text, with comma separated items for Allowed Groups and Output Columns.
Azure Data Factory requires startTime and endTime when dateFilterColumn is set, and requires dateFilterColumn for the Microsoft 365 tables that have DateTime columns.
The Office 365 copy source carries no additional columns. When the object has additional columns, such as derived configuration columns, they are not written to the copy source, and the build reports a warning that names the object.
Choosing an Authentication Method
| Method | Credentials | Additional Settings |
|---|---|---|
| Service principal key | Service Principal Tenant Id, Service Principal Id and Service Principal Key | office365TenantId |
Recommendation: Store the Service Principal Key in Azure Key Vault rather than entering it as plaintext.
Complete Example: Service Principal Key with Azure Key Vault
| Field | Example Value |
|---|---|
| Connect via Integration Runtime | AutoResolveIntegrationRuntime |
| Additional Settings | {"settings": {"office365TenantId": "<tenant-id-of-microsoft-365-organization>"}} |
| Service Principal Tenant Id | contoso.onmicrosoft.com |
| Service Principal Id | <client-id-of-app-registration> |
| Azure Key Vault Linked Service | bfx-kv |
| Secret Name (for Service Principal Key) | BFX-SRC-Office365ClientSecret |
Required Fields
Common Required Fields
An Office 365 Linked Service connection uses a single Authentication Type, so the same fields are required on every connection.
These common required fields are:
- Connect via Integration Runtime
- Office 365 Tenant Id
- Service Principal Tenant Id
- Service Principal Id
- Service Principal Key (or Azure Key Vault)
Connect via Integration Runtime
Connect via Integration Runtime names the integration runtime for an Office 365 Linked Service connection.
The default value is AutoResolveIntegrationRuntime.
To use another runtime, select it from the dropdown or choose + New to add one.
When a custom value is saved in the linked service form, it will be added to the custom integration runtimes.
The custom values that appear in this dropdown can be maintained in Settings under Azure - AzureIntegrationRuntime.
The runtime is stored in the connection's LS_ConnectVia_IntegrationRuntime column. Any value other than AutoResolveIntegrationRuntime is written to the linked service as the runtime it connects through.
Azure Data Factory supports only an Azure integration runtime for this connector. The self-hosted integration runtime and the managed virtual network integration runtime are not supported.
The region of the Azure integration runtime must match the region of the Microsoft 365 tenant's mailboxes.
Office 365 Tenant Id
The Office 365 Tenant Id identifies the Microsoft Entra tenant that the Microsoft 365 organization belongs to.
The Office 365 Tenant Id is stored in the connection's Additional Settings (LS_AdditionalSettings) under the key office365TenantId, and maps to the ADF office365TenantId property.
The Additional Settings hold a JSON object with the keys under settings (for example, {"settings": {"office365TenantId": "<tenant-id-of-microsoft-365-organization>"}}). When the Additional Settings are not valid JSON, the build reports a warning that names the connection and the keys are ignored.
For an organization that reads its own Microsoft 365 data, the Office 365 Tenant Id and the Service Principal Tenant Id hold the same tenant ID. When the application belongs to another company, the Office 365 Tenant Id is the tenant of the Microsoft 365 organization and the Service Principal Tenant Id is the tenant of the company that owns the application.
Service Principal Tenant Id
The Service Principal Tenant Id identifies the Microsoft Entra tenant that the application registration belongs to (for example, contoso.onmicrosoft.com).
It is stored in the connection's LS_Tenant column and maps to the ADF servicePrincipalTenantId property.
Authentication Type
The Office 365 Linked Service connection signs in with a service principal and its key. BimlFlex does not read the connection's Authentication Type column for this connector.
Azure Data Factory also accepts a service principal certificate for this connector. BimlFlex writes the key form, and no certificate credential is written to the linked service.
Service principal key
The Service Principal Id supplies the client ID of the Microsoft Entra application and is stored in the connection's LS_ServicePrincipalId column. It maps to the ADF servicePrincipalId property.
The Service Principal Key supplies the application key as plaintext in the LS_ServicePrincipalKey column, or as an Azure Key Vault reference stored in the LS_ServicePrincipalKeyKVS_ fields that resolves to the key at runtime. It maps to the ADF servicePrincipalKey property.
When an Azure Key Vault reference is set, the plaintext key is not written to the linked service.
When the connection's LS_EncryptedCredential column holds an Encrypted Credential value, it is also written to the linked service.
It is suggested that Azure Key Vault be used in place of manually entering the Service Principal Key.
Azure Data Factory Linked Service Additional Information
For additional information on ADF Office 365 Linked Service and its connection requirements see the Azure Data Factory Microsoft 365 (Office 365) Connector documentation.