JDBC Driver for OData

Build 20.0.7587

Creating a Custom OAuth App

Creating a custom application in most services requires registering as a developer and creating an app in the UI of the service. This is not necessarily true for all services. In some you must contact the serive provider to create the app for you. However it is done, you must obtain the values for OAuthClientId, OAuthClientSecret, and CallbackURL.

Obtain OAuth URLs

You will need the following URLs to complete the OAuth interaction. These URLs are often obtained from the API reference for your data source.

  • OAuthRequestTokenURL: Required for OAuth 1.0. In OAuth 1.0 this is the URL where the app makes a request for the request token.
  • OAuthAuthorizationURL: Required for OAuth 1.0 and 2.0. This is the URL where the user logs into the service and grants permissions to the application. In OAuth 1.0 if permissions are granted the request token is authorized.
  • OAuthAccessTokenURL: Required for OAuth 1.0 and 2.0. This is the URL where the request for the access token is made. In OAuth 1.0 the authorized request token is exchanged for the access token.
  • OAuthRefreshTokenURL: Required for OAuth 2.0. In OAuth 2.0 this is the URL where the refresh token is exchanged for a new access token when the old one expires. Note that for your data source this may be the same as the access token URL.
  • CallbackURL: Required depending on your data source; your data source may require you to define this URL when you create an app. This is the URL you want to be used as a trusted redirect URL (also called a callback URL), where the user will return with the token that verifies that they have granted your app access.

    Note that your data source may require the port.

Set Additional Azure AD OAuth Properties

In addition to the OAuth URLs and the following properties, set AzureResource and AzureTenant when authenticating to Azure AD OAuth endpoints.

Authenticate to OData from a Desktop Application

After setting the required URLs and the following connection properties you are ready to connect:

  • OAuthVersion: Set this to 1.0 or 2.0.
  • OAuthGrantType: By default, the driver negotiates the browser-login flow. This is the "CODE" grant type. However, OAuth 2.0 also supports an exchange of login credentials for the access token; to use this grant type, set this property to "PASSWORD".
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the access token in the connection string.
  • OAuthClientId: Set this to the client Id in your app settings. This is also called the consumer key.
  • OAuthClientSecret: Set this to the client secret in your app settings. This is also called the consumer secret.
  • OAuthParams: Set this to a comma-separated list of any additional parameters required by your data source.
  • CallbackURL: Set this to the localhost callback url you would like to use for a response from the OAuthAuthorizationURL. We recommend using http://localhost:33333 if possible.

Authenticate to OData from a Web Application

To obtain the access token set the required URLs and the following connection properties:

  • OAuthVersion: Set this to 1.0 or 2.0.
  • OAuthClientId: Set this to the client Id in your app settings. This is also called the consumer key.
  • OAuthClientSecret: Set this to the client secret in your app settings. This is also called the consumer secret.
  • OAuthParams: Set this to a comma-separated list of additional parameters required by your data source.
When connecting via a Web application, or if the driver is not authorized to open a browser window, you need to exchange temporary verification values for the access token:
  1. Call GetOAuthAuthorizationUrl. The stored procedure returns the URL of the OAuth endpoint.
  2. Log in at the OAuth endpoint and and grant the application permissions. You are redirected back to the callback URL.

    If you set the ResponseType parameter to "implicit" in OAuth 2.0 the stored procedure returns the OAuthAccessToken.

    Otherwise, call GetOAuthAccessToken.

To connect to data in OAuth 2.0 set the required URLs and OAuthAccessToken.

To connect to data in OAuth 1.0 set the required URLs and the following connection properties:

  • OAuthClientId
  • OAuthClientSecret
  • OAuthAccessToken
  • OAuthAccessTokenSecret

When the access token expires you will need to obtain a new token. In OAuth 1.0 call GetOAuthAccessToken to obtain another access token. In OAuth 2.0 call RefreshOAuthAccessToken to exchange the refresh token for a new OAuthAccessToken.

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