MacOS ODB Client Setup With EntraID Integration

A customer that does all of their Oracle database development and administration from Apple Silicon based MacOS computers and asked what the most efficient method is for setting up Oracle suite of database client tools on MacOS where the tools are setup for Entra ID integration.  I worked with them to get everything setup and am sharing my notes in case anyone else would like to do the same. Note that this is just one of many ways that you could set everything up.  There is nothing special about the $HOME/.oracle directory.  I just used a single base directory ($HOME/.oracle) for simplicity.

1. Setup Base Directory

Make a base directory in which to store the environment, TNS admin data, wallets, and downloaded software

mkdir -p $HOME/.oracle/env $HOME/.oracle/bits $HOME/.oracle/admin $HOME/.oracle/instant_client

2. Download Software

Download the following software into $HOME/.oracle/bits:

• JDK SE 21 [ARM64 Compressed Archive]
• Oracle 26ai Instant Client [Basic Package and SQL*Plus Package]
• SQLcl
• SQL Developer 

3. Extract Software Into Desired Directories

Extract and place each software package in respective folders in $HOME/.oracle in a Terminal window:

cd $HOME/.oracle
tar -zxf bits/jdk-21_macos-aarch64_bin.tar.gz
mv jdk-21.0.11.jdk/Contents jdk
$ rmdir jdk-21.0.11.jdk
unzip -qo bits/sqlcl-26.1.2.132.1334.zip
unzip -qo -d $HOME/Applications $HOME/.oracle/bits/sqldeveloper-24.3.1.347.1826-macos-x64.app.zip
hdiutil attach $HOME/.oracle/bits/instantclient-basic-macos.arm64-23.26.1.0.0.dmg -mountpoint /Volumes/ic_basic
rsync -Ha /Volumes/ic_basic/. $HOME/.oracle/instant_client/. 
hdiutil detach /Volumes/ic_basic
hdiutil attach bits/instantclient-sqlplus-macos.arm64-23.26.1.0.0.dmg -mountpoint /Volumes/ic_sqlplus
rsync -Ha /Volumes/ic_sqlplus/. $HOME/.oracle/instant_client/.
hdiutil detach /Volumes/ic_sqlplus

Download ojdbc-extensions 1.0.6 and make product.conf config file:

cd $HOME/.oracle
mkdir -p ojdbc-extensions/1.0.6
cd ojdbc-extensions
curl -sko o11.jar https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/23.26.2.0.0/ojdbc11-23.26.2.0.0.jar
JAVA_HOME=$HOME/.oracle/jdk/Home
$JAVA_HOME/bin/java -jar o11.jar get-deps --coords com.oracle.database.jdbc/ojdbc-provider-azure/1.0.6 --path 1.0.6

4. Setup SQL Developer For Entra ID Integration

Backup existing SQL Developer product.conf and install new product.conf that includes the JDK 21 home and specifies all of the ojbc-extensions libraries to load:

cd $HOME/.oracle/ojdbc-extensions
export JAVA_HOME=$HOME/.oracle/jdk/Home
echo "SetJavaHome $JAVA_HOME" > $HOME/.sqldeveloper/24.3.1/product.conf
productfile="$HOME/.sqldeveloper/24.3.1/product.conf"
cp ${productfile} ${productfile}-$(date +'%Y%m%d%H%M%S')
find 1.0.6 -name "*.jar"|sed -e "s/^/AddJavaLibFile \$HOME\/.oracle\/ojdbc-extensions\//g" >> ${productfile}

5. Add ojdbc-extensions To SQLcl For Entra ID Integration

Link the ojdbc-extensions/1.0.6 directory to sqlcl/lib/sdks/jdbc-azure so that SQLcl will load the ojbc-extensions on startup:

mkdir -p $HOME/.oracle/sqlcl/lib/sdks
ln -s $HOME/.oracle/ojdbc-extensions/1.0.6 $HOME/.oracle/sqlcl/lib/sdks/jdbc-azure

6. Make Environment File For Client Runtime

Make environment variables:

$ cat /Users/buz/.oracle/env/ora.env 
export JAVA_HOME=$HOME/.oracle/jdk/Home
export TNS_ADMIN=$HOME/.oracle/admin
PATH=$JAVA_HOME/bin:$HOME/.oracle/sqlcl/bin:$HOME/.oracle/instant_client:$HOME/Applications/SQLDeveloper.app/Contents/Resources/sqldeveloper/sqldeveloper/bin:$PATH

7. Create Oracle Database Server Name Resolution File

Make tnsnames.ora file. Note that this output is just sample output from my lab.

$ cat $HOME/.oracle/admin/tnsnames.ora
HRDB_26ai =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = hrdb.dbauthdemo.com)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = hrdb)
    )
  )

HRDB_26ai_SSL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = hrdb.dbauthdemo.com)(PORT = 2484))
    (SECURITY=(WALLET_LOCATION=SYSTEM))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = hrdb)
    )
  )

PDB1_26ai_ENTRA = 
  (DESCRIPTION=
    (ADDRESS=(PROTOCOL=TCPS)(HOST=hrdb.dbauthdemo.com)(PORT=2484))
    (SECURITY=
      (SSL_SERVER_DN_MATCH=TRUE)
      (SSL_SERVER_CERT_DN="CN=hrdb.dbauthdemo.com")
      (WALLET_LOCATION=SYSTEM)
      (TOKEN_AUTH=AZURE_INTERACTIVE)
      (TENANT_ID=8d2aef2e-f5e0-46fc-86c2-82604520aea9)
      (CLIENT_ID=e5124a85-ac3e-14a4-f2ca-1ad635cf781a)
      (AZURE_DB_APP_ID_URI=https://dbauthdemo.com/e5124a85-ac3e-14a4-f2ca-1ad635cf781a)
    )
    (CONNECT_DATA=
      (SERVER=DEDICATED)
      (SERVICE_NAME=pdb1)
    )
  )

PDB1_26ai =
  (DESCRIPTION=
    (ADDRESS=(PROTOCOL=TCP)(HOST=hrdb.dbauthdemo.com)(PORT=1521))
    (CONNECT_DATA=
      (SERVER = DEDICATED)
      (SERVICE_NAME=pdb1)
    )
  )

PDB1_26ai_SSL =
  (DESCRIPTION=
    (ADDRESS=(PROTOCOL=TCPS)(HOST=hrdb.dbauthdemo.com)(PORT=2484))
    (SECURITY=(WALLET_LOCATION=SYSTEM))
    (CONNECT_DATA=
      (SERVER=dedicated)
      (SERVICE_NAME=pdb1)
    )
  )

8. Test Each Client

Load environment variables:

. $HOME/.oracle/env/ora.env

SQL*Plus Local Account Over TLS

sqlplus system@PDB1_26ai

SQL*Plus Entra ID Integration Over TLS

Note that as of May, 2026, the SQL*Plus for MacOS does not yet support Entra ID integration. You will see the following error message:

ERROR: ORA-25723: Unsupported platform

However, for when SQL*Plus eventually does support Entra ID integration, here is a sample command for connecting to an Entra ID integrated database:

sqlplus /@PDB1_26ai_ENTRA

SQLcl Local Account Over TLS

Note, if you see an SLF4J errors, they can be ignored.

sql -thin system@PDB1_26ai

SQLcl Entra ID Integration Over TLS

sql -thin /@PDB1_26ai_ENTRA

SQL Developer

Either open SQL Developer from the application bar or from the command line

sqldeveloper

Then, add connection profiles with the following parameters for Entra ID integrated databases:

Name: <your_database_preferred_name>

Database Type: Oracle

Authentication Type: OS

Connection Type: TNS

Network Alias: <select desired database>

Once the SQL Developer connection is configured, double-click the connection to connect.

I hope you found this helpful!

Blessings