JDBC Driver for Azure Cosmos DB

Build 26.0.9770

Establishing a Connection

Creating a JDBC Data Source

You can create a JDBC data source to connect from your Java application using the CData JDBC Driver for Azure Cosmos DB.

Follow these steps:

  1. Add the driver JAR file to the classpath. The JAR file is located in the installation directory's lib subfolder. Ensure that the .lic file is located in the same folder as the JAR file.
  2. Provide the driver class. For example: 
    cdata.jdbc.cosmosdb.CosmosDBDriver
  3. Provide the JDBC URL. For example: 
    jdbc:cosmosdb:AccountEndpoint=myAccountEndpoint;AccountKey=myAccountKey;

    Or, if there is a conflict in your application between drivers using the same URL format, use this form to ensure that you are using the CData driver: 

    jdbc:cdata:cosmosdb:AccountEndpoint=myAccountEndpoint;AccountKey=myAccountKey;

    Ensure that the URL starts with either jdbc:cosmosdb: or jdbc:cdata:cosmosdb:. The URL can include any of the connection properties in name-value pairs separated with semicolons.

Connecting to Azure Cosmos DB

Azure Cosmos DB supports connecting and authenticating by Account Key, through Azure AD, or through Azure Service Principal.

Account Key

Log in to the Azure Portal, select Azure Cosmos DB, and select your account.

Set the following to authenticate:

  • AccountEndpoint: The Cosmos DB account URL. Set this to the URI value found in the Settings > Keys blade of the Cosmos DB account.
  • AccountKey: A master key token or a resource token for connecting to Azure Cosmos DB. Set this to the PRIMARY KEY value found in the Settings > Keys blade of the Cosmos DB account.
  • TokenType: (optional). Set this to "master" (the default value) if you are using a Master Token, which is a full permissions token generated during account creation. Otherwise, set this property to "resource" if you are using a Resource Token, which is a custom permissions token generated when a database user is set up.

Entra ID (Azure AD)

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

Microsoft Entra ID is a multi-tenant, cloud-based identity and access management platform. It supports OAuth-based authentication flows that enable the driver to access Azure Cosmos DB endpoints securely.

Authentication to Entra ID always requires that you first create and register a custom OAuth application. This enables your application to define its own redirect URI, manage credential scope, and comply with organization-specific security policies.

For full instructions on how to create and register a custom OAuth application, see Creating an Entra ID (Azure AD) Application.

After setting AuthScheme to AzureAD, the steps to authenticate vary, depending on the environment. For details on how to connect from desktop applications, web-based workflows, or headless systems, see the following sections.

Desktop Applications

During the registration of your custom application, as described in Creating an Entra ID (Azure AD) Application, record the following values: client Id, client secret, and callback URL (redirect URI).

Then, set the following connection properties:

  • AuthScheme: AzureAD.
  • InitiateOAuth:
    • GETANDREFRESH: Use for the initial login. Launches the login page and saves tokens.
    • REFRESH: Use this setting when you have already obtained valid access and refresh tokens. Reuses stored tokens without prompting the user again.
  • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
  • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
  • CallbackURL: A redirect URI you defined during application registration.

After authentication, tokens are saved to OAuthSettingsLocation. These values persist across sessions and are used to automatically refresh the access token when it expires, so you don't need to log in again on future connections.

Web Applications

During registration of your custom application, as described in Creating an Entra ID (Azure AD) Application, record the following values: client Id, client secret, and callback URL (redirect URI).

Then, configure the following connection properties:

  • AuthScheme: AzureAD.
  • InitiateOAuth: OFF. This setting disables automatic login prompts.
  • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
  • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
  • CallbackURL: A redirect URI you defined during application registration.

Because web applications typically manage OAuth flows manually on the server-side, InitiateOAuth must be set to OFF. This allows you to explicitly control when and how tokens are retrieved and exchanged using stored procedures.

After configuring these properties, follow the steps below to obtain and exchange OAuth tokens:

  1. Call the GetOAuthAuthorizationURL stored procedure:
    • CallbackURL: Set to your registered redirect URI
  2. Open the returned URL in a browser. Sign in with a Microsoft Entra ID account and grant access.
  3. After signing in, you are redirected to your CallbackURL with a code parameter in the query string.
  4. Extract the code and pass it to the GetOAuthAccessToken stored procedure:
    • AuthMode: WEB.
    • Verifier: The authorization code from the CallbackURL.
  5. The procedure returns:
    • OAuthAccessToken: Used for authentication.
    • OAuthRefreshToken: Used to refresh the access token.
    • ExpiresIn: The lifetime of the access token in seconds.

To enable automatic token refresh, configure the following connection properties:

When InitiateOAuth is set to REFRESH, the driver uses the provided refresh token to request a new access token automatically.

After a successful connection, the driver saves the updated access and refresh tokens to the file specified by OAuthSettingsLocation.

You only need to repeat the full OAuth authorization flow if the refresh token expires, is revoked, or becomes invalid.

For more background on OAuth flows in Microsoft Entra ID, see Microsoft Entra Authentication Overview.

Headless Machines

Headless environments like CI/CD pipelines, background services, or server-based integrations do not have an interactive browser. To authenticate using AzureAD, you must complete the OAuth flow on a separate device with a browser and transfer the authentication result to the headless system.

Setup options:

  • Obtain and exchange a verifier code
    • Use another device to sign in and retrieve a verifier code, which the headless system uses to request tokens.
  • Transfer an OAuth settings file
    • Authenticate on another device, then copy the stored token file to the headless environment.

Using a Verifier Code

  1. On a device with a browser:
    • InitiateOAuth: OFF.
    • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
    • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.
    • Call the GetOAuthAuthorizationURL stored procedure to generate a sign-in URL.
    • Open the returned URL in a browser. Sign in and grant permissions to the driver. You are redirected to the callback URL, which contains the verifier code.
    • After signing in, save the value of the code parameter from the redirect URL. You will use this later to set the OAuthVerifier connection property.
  2. On the headless machine:
    • Set the following properties:
    • After tokens are saved, reuse them by setting:
      • InitiateOAuth: REFRESH.
      • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.
      • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
      • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.

Transferring OAuth Settings

  1. On a device with a browser:
    • Connect using the instructions in the Desktop Applications section.
    • After connecting, tokens are saved to the file path in OAuthSettingsLocation. The default filename is OAuthSettings.txt.

  2. On the headless machine:
    • Copy the OAuth settings file to the machine.
    • Set the following properties:
      • AuthScheme: AzureAD.
      • InitiateOAuth: REFRESH.
      • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.
      • OAuthClientId: The client Id that was generated when you registered your custom OAuth application.
      • OAuthClientSecret: The client secret that was generated when you registered your custom OAuth application.

After setup, the driver uses the stored tokens to refresh the access token automatically, no browser or manual login is required.

Azure Service Principal

Note: Microsoft has rebranded Azure AD as Entra ID. In topics that require the user to interact with the Entra ID Admin site, we use the same names Microsoft does. However, there are still CData connection properties whose names or values reference "Azure AD".

Azure Service Principal is role-based application-based authentication. This means that authentication is done per application, rather than per user. All tasks taken on by the application are executed without a default user context, but based on the assigned roles. The application access to the resources is controlled through the assigned roles' permissions.

For information about how to set up Azure Service Principal authentication, see Creating a Service Principal App in Entra ID (Azure AD).

Copyright (c) 2026 CData Software, Inc. - All rights reserved.
Build 26.0.9770