Establishing a Connection
Connecting to OData
To connect, you need to set the Url to a valid OData service root URI in addition to the authentication values.
Also, you can specify a CacheLocation to store the metadata of your OData organization. This keeps the CData ADO.NET Provider for OData 2019 from having to send requests for metadata on each connection.
Fine-Tuning Data Access
Set the following properties to control how the provider models OData APIs as a database:
- NavigationPropertiesAsViews: By default, the provider models navigation properties as views. This enables access to related entities, even though these entities may not be linked by a foreign key in your OData service.
- SupportsExpand: If your API does not support the $expand parameter, set this property to avoid an error when NavigationPropertiesAsViews is set. If this is the case for your API, specify the base entity's primary key in the WHERE clause to access navigation properties.
- DataFormat: Set this property to JSON or XML. Otherwise, the provider uses the default format defined by the service.
- ODataVersion: Use this to override the version detected by the provider. This is useful if your application supports an older OData version.
- UseIdUrl: By default the provider returns the direct URL to an entity as the primary key. By setting this to false, the entity key is returned.
- UseSimpleNames: Set this to true to return only alphanumeric characters in column names. This can help you to avoid SQL escapes and errors in SQL-based tools.
Authenticating to OData
The provider supports the major authentication schemes, including HTTP and Windows.
Set AuthScheme to use the following authentication types.
- HTTP Authentication: The provider supports authentication with HTTP Basic, Digest, and custom headers. To use Basic or Digest, set the User and Password. You can specify other authentication values in CustomHeaders.
- Windows (NTLM): Set the Windows User and Password to connect and set AuthScheme to "NTLM".
- Kerberos and Kerberos Delegation: To authenticate with Kerberos, set AuthScheme to NEGOTIATE. To use Kerberos Delegation, set AuthScheme to KERBEROSDELEGATION. If needed, provide the User, Password, and KerberosSPN. By default, the provider attempts to communicate with the SPN at the specified Url.
Securing OData Connections
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.
Using OAuth Authentication
OAuth requires the authenticating user to interact with OData using the browser. Most OData services will not require OAuth. This section is only for OData endpoints that require OAuth. The provider facilitates this in various ways as described below.
Required OAuth Connection Properties
There are several required connection properties to establish an OAuth connection. These must be obtained from the API documentation of the OData service you are connecting to.
- OAuthVersion: The version of OAuth being used. Enter 1.0 or 2.0.
- OAuthAccessTokenURL: The URL to retrieve the OAuth access token from.
- OAuthAuthorizationURL: The URL that needs to be opened in the browser for the user to grant permissions.
- OAuthRefreshTokenURL: The URL to use when refreshing an expired access token.
- OAuthRequestTokenURL: The URL the service provides to retrieve request tokens from. Required in OAuth 1.0.
- OAuthGrantType: The grant type for the OAuth flow. Can be either CLIENT, CODE or PASSWORD.
- OAuthParams: A comma-separated list of other parameters to submit in the request for the OAuth access token in the format paramname=value.
Creating a Custom OAuth App
In addition to the previously mentioned connection properties, you will need to register an app to obtain the OAuthClientId and OAuthClientSecret.
Desktop Authentication with your OAuth AppFollow the steps below to authenticate with the credentials for a custom OAuth app.
Get an OAuth Access Token
After setting the following, you are ready to connect:
- OAuthClientId: Set this to the Client Id in your app settings.
- OAuthClientSecret: Set this to the Client Secret in your app settings.
- CallbackURL: Set this to the Redirect URL in your app settings.
- InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken. .
- Extracts the access token from the callback URL and authenticates requests.
- Obtains a new access token when the old one expires.
- Saves OAuth values in OAuthSettingsLocation to be persisted across connections.