Configuring an ADF Linked Service Connection for REST

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 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 Rest Service from the Linked Service Type dropdown, the form required for creating a REST Linked Service will appear.

Source Only Connector

A connection with the System Type Rest Service or Dynamics Business Central selects this Linked Service Type and is used as a source. It is not available as a target.

Each object of a Rest Service connection is read by a copy activity whose source is a REST source over the connection's REST resource dataset.

Choosing an Authentication Method

Method	Credentials	Additional Settings
Anonymous	None	None
Basic	Username and Password	None
AAD Service Principal	Service Principal Id, Service Principal Key, Tenant and AAD Resource Id	None
OAuth2 Client Credential	Client ID, Client Secret and Token Endpoint	None
System-Assigned Managed Identity	AAD Resource Id	None

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

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

Complete Example: OAuth2 Client Credential with Azure Key Vault

Field	Example Value
Connect via Integration Runtime	AutoResolveIntegrationRuntime
Base Url	https://api.contoso.com/v1/
Authentication Type	OAuth2ClientCredential
Token Endpoint	https://login.contoso.com/oauth2/token
Client ID	<client-id-of-contoso-app>
Azure Key Vault Linked Service	bfx-kv
Secret Name (for Client Secret)	BFX-SRC-ContosoApiClientSecret
Scope	api.read

Required Fields

Common Required Fields

Most required fields for a REST 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
• Enable Server Certificate Validation

Authentication Type Dependent Required Fields

The remaining field requirements are dependent on Authentication Type.

Required fields for Anonymous:

• None

Required fields for Basic:

• Username
• 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

Required fields for OAuth2 Client Credential:

• Token Endpoint
• Client ID
• Client Secret (or Azure Key Vault)

Optional fields:

• Scope
• Resource

Required fields for System-Assigned Managed Identity:

• AAD Resource Id

Connect via Integration Runtime

Connect via Integration Runtime names the integration runtime for a REST 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.

Base Url

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

Authentication Type

The REST Linked Service connection can use Anonymous, Basic, AAD Service Principal, OAuth2 Client Credential or System-Assigned Managed Identity authentication. The selected value is stored in the connection's LS_AuthenticationType column and maps to the ADF authenticationType property, with the values Anonymous, Basic, AadServicePrincipal, OAuth2ClientCredential and ManagedServiceIdentity.

For Anonymous, no credentials are required.

When using Basic, a Username and Password are required.

For AAD Service Principal, a Service Principal Id, Service Principal Key, Tenant and AAD Resource Id are required.

For OAuth2 Client Credential, a Token Endpoint, Client ID and Client Secret are required.

For System-Assigned Managed Identity, an AAD Resource Id is required.

Anonymous

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

Basic

Basic authentication signs in to the REST service with a Username and Password.

The Username is stored in the connection's LS_Username column and maps to the ADF userName property. The Password field accepts the password as plaintext in the LS_Password column, or an Azure Key Vault reference held in the LS_PasswordKVS_ fields that resolves to the password at runtime. It maps to the ADF password property.

note

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

AAD Service Principal

AAD Service Principal authentication requests access to the REST 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 supplies the key of the application as plaintext in the LS_ServicePrincipalKey column, or as an Azure Key Vault reference held in the LS_ServicePrincipalKeyKVS_ fields that resolves to the key at runtime. It maps to the ADF servicePrincipalKey property. 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 AAD Resource Id is the Microsoft Entra resource the connection requests authorization for (for example, https://management.core.windows.net). It is stored in the connection's LS_AadResourceId column and maps to the ADF aadResourceId 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. Supported values are AzurePublic, AzureChina, AzureUsGovernment and AzureGermany. When it is not set, Azure Data Factory uses the cloud environment of the data factory.

note

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

OAuth2 Client Credential

OAuth2 Client Credential authentication acquires an access token from the token endpoint of an authorization server.

The Token Endpoint is stored in the connection's LS_TokenEndpoint column and maps to the ADF tokenEndpoint property. The Client ID is stored in the connection's LS_ServicePrincipalId column and maps to the ADF clientId property. The Client Secret is entered as plaintext in the LS_ServicePrincipalKey column, or as an Azure Key Vault reference held in the LS_ServicePrincipalKeyKVS_ fields that resolves to the secret at runtime. It maps to the ADF clientSecret property.

The Scope describes the access that is requested. It is stored in the connection's LS_Scope column and maps to the ADF scope property. The Resource is the target service or resource the access is requested for. It is stored in the connection's LS_Resource column and maps to the ADF resource property. BimlFlex writes the Scope and the Resource to the linked service when their columns are set.

note

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

System-Assigned Managed Identity

System-Assigned Managed Identity authentication requests access to the REST service with the managed identity of the data factory. The generated linked service carries the Authentication Type ManagedServiceIdentity.

The AAD Resource Id is the Microsoft Entra resource the connection requests authorization for. It is stored in the connection's LS_AadResourceId column and maps to the ADF aadResourceId property.

Auth Headers

Auth Headers are additional HTTP request headers for authentication, and apply to every Authentication Type. They are stored in the connection's LS_AuthHeaders column as a list of header names and values, and map to the ADF authHeaders property. Each header with a name and a value is written to the linked service, with its value as a secure string. Header values are entered as plaintext.

Enable Server Certificate Validation

The Enable Server Certificate Validation setting is stored in the connection's LS_EnableServerCertificateValidation column and corresponds to the ADF enableServerCertificateValidation property.

Azure Data Factory Linked Service Additional Information

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