Configuring an ADF Linked Service Connection for OData

note

For information on how to enable a connection for use with linked services, see Configuring a Linked Service Connection.

note

Field labels in this walkthrough follow the BimlFlex Connection Editor, with the connection column that carries each value and the Azure Data Factory property it maps to named alongside.

After selecting OData from the Linked Service Type dropdown, the form required for creating an OData Linked Service will appear. The OData option is offered on connections that use the OData System Type.

Source Only Connector

An OData connection is used as a source. It is not available as a target.

Each object of an OData connection is read by a copy activity whose source is an OData source over the connection's OData resource dataset. The dataset carries the path of the resource from its RelativeUrl parameter and maps it to the ADF path property. It carries no schema and no table. When the object's relative URL is set, the copy source passes it in the RelativeUrl parameter. In the object editor, an object on an OData connection carries the Relative URL and Collection Reference fields under Rest Settings, its Relative URL cell is editable in the bulk edit grid, and the Query Overrides panel is not shown for it, as for a Rest Service connection. The copy source reads the resource whole and carries no query. Azure Data Factory reads the resource at the Base Url followed by the path.

Choosing an Authentication Method

Method	Credentials	Additional Settings
Anonymous	None	None
Basic	User Name and Password	None
Windows	User Name and Password	None
AAD Service Principal	Service Principal Id, Service Principal Key, Tenant and AAD Resource Id	Azure Cloud Type (optional)

Auth Headers can be added to a connection of any Authentication Type.

Recommendation: Store the Password and the Service Principal Key in Azure Key Vault rather than entering them as plaintext.

Complete Example: AAD Service Principal with Azure Key Vault

The values below are made up for illustration.

Field	Example Value
Connect via Integration Runtime	AutoResolveIntegrationRuntime
Base Url	https://odata.contoso.com/service/
Authentication Type	AAD Service Principal
Service Principal Id	00000000-0000-0000-0000-000000000001
AKV Linked Service (Service Principal Key, Azure Key Vault tab)	bfx-kv
Secret Name (Service Principal Key, Azure Key Vault tab)	BFX-ODataServicePrincipalKey
Tenant	contoso.onmicrosoft.com
Azure Cloud Type	AzurePublic
AAD Resource Id	https://odata.contoso.com/

With these values, BimlFlex writes the linked service with the url, authenticationType, servicePrincipalId, tenant, azureCloudType and aadResourceId properties and the servicePrincipalKey property as an Azure Key Vault secret reference. No connectVia property is written, because the runtime is AutoResolveIntegrationRuntime.

Required Fields

Common Required Fields

Most required fields for an OData Linked Service connection depend on the Authentication Type used. There are some fields that are required regardless of Authentication Type.

These common required fields are:

• Connect via Integration Runtime
• Base Url
• Authentication Type

Optional fields are:

• Auth Headers

Authentication Type Dependent Required Fields

The remaining field requirements are dependent on Authentication Type.

Required fields for Anonymous:

• None

Required fields for Basic:

• User Name
• Password (or Azure Key Vault)

Required fields for Windows:

• User Name
• Password (or Azure Key Vault)

Required fields for AAD Service Principal:

• Service Principal Id
• Service Principal Key (or Azure Key Vault)
• Tenant
• AAD Resource Id

Optional field:

• Azure Cloud Type

Connect via Integration Runtime

Connect via Integration Runtime names the integration runtime for an OData Linked Service connection. Azure Data Factory connects to an OData service through the Azure integration runtime or a self-hosted integration runtime. Use a self-hosted integration runtime when the OData service is inside an on-premises network or a virtual network. The default value is AutoResolveIntegrationRuntime. To use another runtime, select it from the dropdown or choose + New to add one. The custom values that appear in this dropdown can be maintained in Settings under Azure, in the AzureIntegrationRuntime setting.

The runtime is stored in the connection's LS_ConnectVia_IntegrationRuntime column and maps to the ADF connectVia property. Any value other than AutoResolveIntegrationRuntime is written to the linked service as the runtime it connects through.

Base Url

The Base Url is the root URL of the OData service (for example, https://odata.contoso.com/service/). It is stored in the connection's LS_Url column and maps to the ADF url property.

Authentication Type

The Authentication Type select offers Anonymous, Basic, Windows and AAD Service Principal. The selected value is stored in the connection's LS_AuthenticationType column and maps to the ADF authenticationType property, with the values Anonymous, Basic, Windows and AadServicePrincipal. The form does not preselect a value.

For Anonymous, no credentials are required, and the form shows no credential fields.

For Basic and Windows, the form shows the User Name and Password fields, and a User Name and Password are required.

For AAD Service Principal, the form shows the Service Principal Id, Service Principal Key, Tenant, Azure Cloud Type and AAD Resource Id fields. A Service Principal Id, Service Principal Key, Tenant and AAD Resource Id are required.

The Auth Headers grid is shown for every Authentication Type.

BimlFlex writes each credential property to the linked service only when its column holds a value. When the Authentication Type is not AAD Service Principal, saving the connection clears the Azure Cloud Type. The other credential fields keep their values when the Authentication Type changes, so clear the fields of one Authentication Type before selecting another.

Anonymous

Anonymous authentication connects to the OData service without credentials. Auth Headers can carry an API key or another request header the service expects.

Basic

Basic authentication signs in to the OData service with a User Name and Password.

The User Name is stored in the connection's LS_Username column and maps to the ADF userName property.

The Password field has a Password tab for the password as text, and an Azure Key Vault tab beside it for a reference that resolves to the password at runtime. The form saves the tab that is selected, a password entered as text in the LS_Password column or the Azure Key Vault reference in the LS_PasswordKVS_ fields, and saving the connection clears the other. BimlFlex writes a password from the LS_Password column to the ADF password property as a secure string. The Azure Key Vault reference is named by the AKV Linked Service, the Secret Name and an optional Secret Version, and BimlFlex writes it as the password secret when both the AKV Linked Service and the Secret Name are filled.

A Basic connection needs a User Name and exactly one form of the password, the text password or the Azure Key Vault reference.

note

It is suggested that Azure Key Vault be used in place of manually entering the Password.

Windows

Windows authentication signs in to the OData service with the User Name and Password of a Windows account.

It uses the same User Name and Password fields as Basic authentication, stored in the LS_Username column and the LS_Password column or the LS_PasswordKVS_ fields, and written to the ADF userName and password properties. Enter the User Name with its domain, for example BFXDOMAIN\bfx_reader.

A Windows connection needs a User Name and exactly one form of the password, the text password or the Azure Key Vault reference.

AAD Service Principal

AAD Service Principal authentication requests access to the OData service with a Microsoft Entra application.

The Service Principal Id supplies the client ID of the application and is stored in the connection's LS_ServicePrincipalId column. It maps to the ADF servicePrincipalId property.

The Service Principal Key field has a Service Principal Key tab for the key as text, and an Azure Key Vault tab beside it for a reference that resolves to the key at runtime. The form saves the tab that is selected, a key entered as text in the LS_ServicePrincipalKey column or the Azure Key Vault reference in the LS_ServicePrincipalKeyKVS_ fields, and saving the connection clears the other. BimlFlex writes a key from the LS_ServicePrincipalKey column to the ADF servicePrincipalKey property as a secure string, and writes the Azure Key Vault reference as the servicePrincipalKey secret when both the AKV Linked Service and the Secret Name are filled.

The Tenant is the tenant ID or domain name under which the application resides. It is stored in the connection's LS_Tenant column and maps to the ADF tenant property.

The Azure Cloud Type is the Azure cloud environment in which the application is registered. It is stored in the connection's LS_AzureCloudType column and maps to the ADF azureCloudType property. The select offers (none), AzurePublic, AzureChina, AzureUsGovernment and AzureGermany. When it is (none), no azureCloudType property is written and Azure Data Factory uses the cloud environment of the service.

The AAD Resource Id is the Microsoft Entra resource the connection requests authorization for (for example, https://odata.contoso.com/). It is stored in the connection's LS_AadResourceId column and maps to the ADF aadResourceId property.

note

It is suggested that Azure Key Vault be used in place of manually entering the Service Principal Key.

Auth Headers

Auth Headers are additional HTTP request headers for authentication, and apply to every Authentication Type. Each row of the Auth Headers grid takes a header Name and a Value. The headers are stored in the connection's LS_AuthHeaders column as a list of header names and values, and map to the ADF authHeaders property. BimlFlex writes each header that has a name to the linked service, with its value as a secure string. A header without a name is not written. Header values are entered as plaintext.

Azure Data Factory Linked Services Additional Information

For additional information on ADF OData Linked Service and its connection requirements see the Azure Data Factory OData Connector documentation.