Enabling Clients to Directly Retrieve Entra ID Tokens

You can set parameters to enable clients to directly retrieve Entra ID tokens on their own.

Oracle Database clients differ by platform and version for what flows they support. The following table shows what each client can support.

Database Clients Passing Using Client API Using File Location Database Client Direct Support
Thick clients (OCI C driver, Instant Clients Along with platform specific drivers that use the thick client (for example, JDBC-thick, ODP.NET unmanaged, Python-thick) Client versions 19.16+, not 21c, all 26ai
Supported for all flows (interactive, client credential, OBO, ROPC)		 Client versions 19.16+, not 21c, all 26ai
Supported for all flows (interactive, client credential, OBO, ROPC)		 Client version 23.4+
Interactive flow support only
JDBC-thin Client versions 19.16+, 21.7+, all 26ai
Supported for all flows (interactive, client credential, OBO, ROPC)		 Client versions 19.16+, 21.7+, all 26ai
Supported for all flows (interactive, client credential, OBO, ROPC)		 Client version 26ai
Supports the following flows (interactive, device code, client credential, managed identity, OBO, ROPC)
ODP.NET core, managed Client versions 19.16+, 21.7+, all 26ai
Supported for all flows (interactive, client credential, OBO, ROPC)		 Client versions 19.16+, 21.7+, all 26ai
Supported for all flows (interactive, client credential, OBO, ROPC)		 Client version 26ai
Supports the following flows (interactive, device code, client credential, managed identity, OBO, ROPC)
Python-thin Not supported Not supported Not supported
Node.js Not supported. Not supported Not supported

The connect string parameters are common across the database clients. Refer to each database client documentation (JDBC-thin, ODP.NET core, managed) for more specific information regarding this feature with those drivers. The following information is specifically for the OCI thick client/Instant client. However, the information about connect string parameters will remain consistent across the drivers.

To enable this feature in the client to get a token directly from Entra ID for a supported flow, you must set the following parameters in either the client’s sqlnet.ora file or in a connect string. The connect string takes precedence over sqlnet.ora.

In order for the database client to retrieve the Entra ID OAuth2 token, the database client must be able to connect with the Entra ID endpoint. If you are working behind a firewall, you may need to set a proxy to reach the internet. See the Troubleshooting Microsoft Entra ID Connections section if you’re not sure if you are able to connect to the internet.

Parameter Description
TOKEN_AUTH Sets the token authentication. This parameter is mandatory when you are asking the database client to get the database token or pick it up from a file location. This parameter is not required when you are passing the token through the client API.
Enter one of the following values: AZURE_INTERACTIVE tells the driver that it must use the Entra OAuth2 interactive (OAuth2 authorization) flow to get an access token for the database. This configures the database client to get the token directly from Entra ID without having to use an external script. This is for human users who are logging into tools such as SQLcl and can also open a browser window in their environment to authenticate
AZURE_DEVICE_CODE signals the database driver to follow the device code flow for requesting an Entra ID access token. This is also for human users, when their environment cannot open a browser: a command line only environment. A device code and Entra ID login URL is written out to the standard output of the tool and the user logs into Entra ID on their cellphone or laptop, and then enters the device code. Users are authenticated through a separate channel and then allowed to continue access the database if the authentication is successful.
AZURE_MANAGED_IDENTITY enables the driver to authenticate as an identity that has been assigned to the host system. The host system must be a resource which is managed by Entra ID, such as a virtual machine.
AZURE_SERVICE_PRINCIPAL enables the driver to authenticate using a secret or certificate of the registered application.
CLIENT_ID The unique application (client) ID assigned to your app by Entra ID when the app was registered. This app is your database client that will request to get an access token for the database for the user. This is not the client ID for the database server.
AZURE_DB_APP_ID_URI The application ID URI is a URI that uniquely identifies the database in your Entra ID. You get this value from the overview screen of your database Entra ID app registration.
TENANT_ID Specifies the Azure tenancy ID of the database.
REDIRECT_URI Optional parameter for setting the port number for the HTTP server. This URL obtains the authorization code from the Entra authentication endpoint and determines which port to use to receive the authorization code. If REDIRECT_URI is not set, then the default is http://localhost:8400. If 8400 is already in use, then Oracle AI Database tries the next available number after 8400, ranging from 8400 to 90000. If you explicitly specify an unavailable port number, then the connection fails.

See Oracle AI Database Net Services Reference for specific information about each parameter. The following is an example of specifying use of interactive flow to get a token.

conn /@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=example.us-phoenix-1.oraclecloud.com)(PORT=6010))
(SECURITY=(TLS_SERVER_DN_MATCH=YES)
(AZURE_DB_APP_ID_URI=https://oracledevelopment.onmicrosoft.com/11111111-11a1-1a11-111a-a11a11111111)
(TENANT_ID=1a111aa1-a1a1-1a11-a1a1-a11aaaaa1111)
(CLIENT_ID=aa11a111-111a-1a11-1aa1-1aa1a1aa1111)
(TOKEN_AUTH=AZURE_INTERACTIVE))(CONNECT_DATA=(SERVICE_NAME=cdb1_pdb3.regress.rdbms.dev.us.oracle.com)))

Client Credential Flow

The client credential flow allows on-premises applications and applications in non-Azure cloud environments to get an MS-EI OAuth2 token to connect to the Oracle AI Database.

The client credential flow is supported using the token file passing method and through the OCI-C client API since Oracle Database 19c (not Oracle Database 21c). The Oracle AI Database 26ai OCI-C client also supports getting the MS-EI OAuth2 token directly from the MS-EI endpoint without requiring a script to initially get the token. In order to get the token for the Client Credential flow, the client will need a client ID and a client secret from MS-EI when the application is registered using MS-EI app registration. This is different than when setting up a public client for DBAs to connect to the database using the interactive flow. A public client doesn’t need a client secret since the human user will be signing into Azure using their credentials. In the client credential flow, the application must have a client secret to authenticate to MS-EI and get a token. Since the client secret is sensitive, we recommend using an Oracle Wallet to store the client ID and client secret.

There are a few differences between the client used for interactive flow (for human users) and the client credential flow (for applications). In the interactive flow, users and groups are mapped to the database app roles in MS-EI enterprise applications. With the client credential flow, the client application can only be mapped to a database app role directly.

Follow the below steps to configure client credential flow between the Oracle AI Database and Microsoft Entra ID.

Register the Oracle AI Database with Microsoft Entra ID

Follow the below Microsoft documentation to create an app registration for the application client:

  1. Register an application

  2. Expose scopes in web API registrations

  3. Grant scopes permission to web API

Ensure that you:

Create an application role mapping in Oracle AI Database

In the previous step you created a new application role. You now have to create a schema mapping in the database and grant the appropriate roles and privileges to the schema for the new role.

  1. Log in to the Oracle AI Database instance as a user who has the CREATE USER or ALTER USER system privilege.

  2. Run the CREATE USER or ALTER USER statement with the IDENTIFIED GLOBALLY AS clause specifying the Azure application role name.

    For example, to create a new database global user account (schema) named hr_app and map it to an existing Entra ID application role named hrapp:

    CREATE USER hr_app IDENTIFIED GLOBALLY AS 'AZURE_ROLE=HRAPP';

Configure the Oracle Call Interface (OCI-C) client for client credential flow

You must define parameters for the OCI-C client to get an OAuth2 token for the application credential flow.

The following parameters can be defined either in the sqlnet.ora file or in the tnsnames.ora file. Parameters in the tnsnames.ora file will have precedence over the same parameter in sqlnet.ora.

Parameter Value Usage Notes
TOKEN_AUTH AZURE_SERVICE_PRINCIPAL This tells the OCI-C driver to follow the client credential flow
TENANT_ID The tenancy ID for the application app registration This may or may not be the same tenancy for the database app registration
AZURE_DB_APP_ID_URI This is from the database app registration This was configured when creating the database app registration
CLIENT_ID This is the client ID for the application app registration This is not the client id from the database app registration
AZURE_CREDENTIALS This is the location of the wallet holding the client secret  

Here is a sample connect string:

conn2=
    (DESCRIPTION=
        (ADDRESS=
            (PROTOCOL=tcps)
            (HOST=phoenix99201)
             (PORT=6679)
        )
        (SECURITY=
            (TLS_SERVER_CERT_DN="C=US,O=OracleCorporation,CN=sslserver3")
            (TOKEN_AUTH=AZURE_SERVICE_PRINCIPAL)
            (TENANT_ID=aaaaaaaa-bbbb-cccc-eeee)
            (AZURE_DB_APP_ID_URI=https://examplecorp.onmicrosoft.com/aaaa-bbbb-cccc-dddd)
            (CLIENT_ID=aaaa-bbbb-cccc-dddd-eeee)
            (AZURE_CREDENTIALS=/scratch/secret)
        )
        (CONNECT_DATA=
            (SERVICE_NAME=database.examplecorp.com)
        )
    )

The first four parameter values can be in the connect string or sqlnet.ora file. But the client secret needs to be in the wallet with the location identified by AZURE_CREDENTIALS.

The client secret is paired with the client ID in the wallet. The database driver will look up the client secret in the wallet using the CLIENT_ID parameter. The client ID is a case sensitive parameter so the case for the client ID in the wallet must match the case of the client ID in the connect string or sqlnet.ora.

When you display the wallet content, you will find something similar to:

oracle.security.azure.credential.<client id> = <client secret>

The CLIENT_ID and CLIENT_SECRET is obfuscated/encrypted in the wallet and only user with right privilege can open/view the value.

Create the wallet for storing the client secret

Use orapki to create the wallet and store the client secret.

  1. Create a wallet and set the wallet password:

    orapki wallet create -wallet . -auto_login_only

  2. Create an entry with the client id and client secret:

    orapki secretstore create_entry -wallet . -alias oracle.security.azure.credential.<CLIENT_ID> -secret <CLIENT_SECRET>

    Note: The CLIENT_ID value is case sensitive and must match the case of the CLIENT_ID vale in the connect string or sqlnet.ora file.

Related Topics

Enabling Clients to Retrieve Entra ID Tokens from a File Location

If you choose to retrieve the Entra ID location from a file location when you use the / slash login, then you will need to configure your client.

You can configure the Entra ID file location in either the sqlnet.ora file or the tnsnames.ora file.

On the client, set or check the following parameters in the tnsnames.ora connect string or in the sqlnet.ora file:

Note: To bring Oracle parameters in accord with the actual encryption and authentication methods for network connections, Oracle is deprecating all connect parameters prefixed with SSL_ in favor of parameters prefixed with TLS_. During this deprecation period, if both TLS_SERVER_DN_MATCH and SSL_SERVER_DN_MATCH parameters are configured, then the SSL_SERVER_DN_MATCH parameter is ignored.

The parameter values in the tnsnames.ora connect string take precedence over the sqlnet.ora settings for that connection. The following code is an example of a tnsnames.ora entry. In this case, TLS_SERVER_DN_MATCH is specified in sqlnet.ora and will not appear in the connect string:

(description=
  (retry_count=20)(retry_delay=3)
  (address=(protocol=tcps)(port=1522)
  (host=example.us-phoenix-
1.oraclecloud.com))
  (connect_data=(service_name=aaabbbccc_exampledb_high.example.oraclecloud.com))
  (security=(tls_server_cert_dn="CN=example.uscom-east-1.oraclecloud.com,
     OU=Oracle BMCS US, O=Example Corporation,
     L=Redwood City, ST=California, C=US")
  (TOKEN_AUTH=OAUTH)(TOKEN_LOCATION="/oracle/tokens/aad-token"))

After the connect string is updated with these parameters, the Azure user can log in to the Oracle Database instance by first running the external utility to get the token and then running the following command to start SQL*Plus. You can include the connect descriptor itself or use the name of the descriptor from the tnsnames.ora file.

connect /@exampledb_high

The database client is already configured to get an Azure OAuth2 token because TOKEN_AUTH has already been set, either through the connect string or the sqlnet.ora file. The database client gets the OAuth2 token and then sends the token to the Oracle Database instance.

Using Azure App Configuration Store for Network Service Configuration Information

You can store connect string and other network configuration information in Azure App Configuration Store.

See Azure App Configuration Store in the Oracle AI Database Net Services Administrator’s Guide for more information.