Added support for token authentication (Azure OAuth and IAM) via the new

parameter "access_token" to oracledb.connect() and
oracledb.create_pool().

Author: anthony-tuininga

doc/src/api_manual/connect_param.rst

@@ -33,9 +33,9 @@ ConnectParams Methods
   that are found in the connect string override any currently stored values.
 
 .. method:: ConnectParams.set(user=None, proxy_user=None, password=None, \
-    newpassword=None, wallet_password=None, host=None, port=None, protocol=None, \
-    https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
-    server_type=None, cclass=None, purity=None, expire_time=None, retry_count=None, \
+    newpassword=None, wallet_password=None, access_token=None, host=None, \
+    port=None, protocol=None, https_proxy=None, https_proxy_port=None, service_name=None, \
+    sid=None, server_type=None, cclass=None, purity=None, expire_time=None, retry_count=None, \
     retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, \
     ssl_server_cert_dn=None, wallet_location=None, events=None, externalauth=None, \
     mode=None, disable_oob=None, stmtcachesize=None, edition=None, tag=None, \

doc/src/api_manual/module.rst

@@ -48,12 +48,12 @@ Oracledb Methods
         This method is an extension to the DB API definition.
 
 .. function:: connect(dsn=None, pool=None, conn_class=None, params=None, user=None, \
-    proxy_user=None, password=None, newpassword=None, wallet_password=None, \
+    proxy_user=None, password=None, newpassword=None, wallet_password=None, access_token=None, \
     host=None, port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \
     service_name=None, sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, \
     expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, \
-    ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, \
-    events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
+    ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, events=False, \
+    externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
     stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, matchanytag=False, \
     config_dir=oracledb.defaults.config_dir, appcontext=[], shardingkey=[], supershardingkey=[], \
     debug_jdwp=None, handle=0)
@@ -125,6 +125,17 @@ Oracledb Methods
     is not needed for cwallet.sso files that are used in the python-oracledb Thick
     mode.
 
+    The ``access_token`` parameter is expected to be a string or a 2-tuple or
+    a callable. If it is a string, it specifies an Azure AD OAuth2 token used
+    for Open Authorization (OAuth 2.0) token based authentication. If it is a
+    2-tuple, it specifies the token and private key strings used for Oracle
+    Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based
+    authentication. If it is a callable, it returns either a string or a 2-tuple
+    used for OAuth 2.0 or OCI IAM token based authentication and is useful when
+    the pool needs to expand and create new connections but the current
+    authentication token has expired. This value is used in both the
+    python-oracledb Thin and Thick modes.
+
     The ``host`` parameter is expected to be a string which specifies the name or IP
     address of the machine hosting the listener, which handles the initial
     connection to the database. This value is used in both the python-oracledb
@@ -285,9 +296,9 @@ Oracledb Methods
     should be used with extreme caution. The default value is 0.
 
 .. function:: ConnectParams(user=None, proxy_user=None, password=None, \
-    newpassword=None, wallet_password=None, host=None, port=1521, protocol="tcp", \
-    https_proxy=None, https_proxy_port=0, service_name=None, sid=None, \
-    server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \
+    newpassword=None, wallet_password=None, access_token=None, host=None, \
+    port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, service_name=None, \
+    sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \
     retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, ssl_server_dn_match=True, \
     ssl_server_cert_dn=None, wallet_location=None, events=False, externalauth=False, \
     mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, \
@@ -324,6 +335,17 @@ Oracledb Methods
     is not needed for cwallet.sso files that are used in the python-oracledb Thick
     mode.
 
+    The ``access_token`` parameter is expected to be a string or a 2-tuple or
+    a callable. If it is a string, it specifies an Azure AD OAuth2 token used
+    for Open Authorization (OAuth 2.0) token based authentication. If it is a
+    2-tuple, it specifies the token and private key strings used for Oracle
+    Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based
+    authentication. If it is a callable, it returns either a string or a 2-tuple
+    used for OAuth 2.0 or OCI IAM token based authentication and is useful when
+    the pool needs to expand and create new connections but the current
+    authentication token has expired. This value is used in both the
+    python-oracledb Thin and Thick modes.
+
     The ``host`` parameter is expected to be a string which specifies the name or IP
     address of the machine hosting the listener, which handles the initial
     connection to the database. This value is used in both the python-oracledb
@@ -489,16 +511,15 @@ Oracledb Methods
         wait_timeout=0, max_lifetime_session=0, session_callback=None, \
         max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \
         user=None, proxy_user=None, password=None, newpassword=None, \
-        wallet_password=None, host=None, port=1521, protocol="tcp", \
-        https_proxy=None, https_proxy_port=0, service_name=None, sid=None, \
-        server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, \
+        wallet_password=None, access_token=None, host=None, port=1521, \
+        protocol="tcp", https_proxy=None, https_proxy_port=0, service_name=None, \
+        sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, \
         expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, \
-        ssl_server_dn_match=True, ssl_server_cert_dn=None, \
-        wallet_location=None, events=False, externalauth=False, \
-        mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
-        stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, \
-        matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], \
-        shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0)
+        ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, \
+        events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, \
+        disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \
+        tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \
+        appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -619,6 +640,17 @@ Oracledb Methods
     ``wallet_password`` parameter is not needed for cwallet.sso files that are
     used in the python-oracledb Thick mode.
 
+    The ``access_token`` parameter is expected to be a string or a 2-tuple or
+    a callable. If it is a string, it specifies an Azure AD OAuth2 token used
+    for Open Authorization (OAuth 2.0) token based authentication. If it is a
+    2-tuple, it specifies the token and private key strings used for Oracle
+    Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based
+    authentication. If it is a callable, it returns either a string or a 2-tuple
+    used for OAuth 2.0 or OCI IAM token based authentication and is useful when
+    the pool needs to expand and create new connections but the current
+    authentication token has expired. This value is used in both the
+    python-oracledb Thin and Thick modes.
+
     The ``host`` parameter is expected to be a string which specifies the name
     or IP address of the machine hosting the listener, which handles the
     initial connection to the database. This value is used in both the
@@ -894,15 +926,15 @@ Oracledb Methods
     wait_timeout=0, max_lifetime_session=0, session_callback=None, \
     max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \
     user=None, proxy_user=Nonde, password=None, newpassword=None, \
-    wallet_password=None, host=None, port=1521, protocol="tcp", \
+    wallet_password=None, access_token=None, host=None, port=1521, protocol="tcp", \
     https_proxy=None, https_proxy_port=0, service_name=None, sid=None, \
     server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, \
     expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, \
     ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, \
-    events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
-    stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, \
-    matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], \
-    shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0)
+    events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, \
+    disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \
+    tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \
+    appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -993,6 +1025,17 @@ Oracledb Methods
     ``wallet_password`` parameter is not needed for cwallet.sso files that are
     used in the python-oracledb Thick mode.
 
+    The ``access_token`` parameter is expected to be a string or a 2-tuple or
+    a callable. If it is a string, it specifies an Azure AD OAuth2 token used
+    for Open Authorization (OAuth 2.0) token based authentication. If it is a
+    2-tuple, it specifies the token and private key strings used for Oracle
+    Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based
+    authentication. If it is a callable, it returns either a string or a 2-tuple
+    used for OAuth 2.0 or OCI IAM token based authentication and is useful when
+    the pool needs to expand and create new connections but the current
+    authentication token has expired. This value is used in both the
+    python-oracledb Thin and Thick modes.
+
     The ``host`` parameter is expected to be a string which specifies the name
     or IP address of the machine hosting the listener, which handles the
     initial connection to the database. This value is used in both the

doc/src/api_manual/pool_params.rst

@@ -35,15 +35,15 @@ PoolParams Methods
 .. method:: PoolParams.set(min=None, max=None, increment=None, connectiontype=None, \
     getmode=None, homogeneous=None, timeout=None, wait_timeout=None, \
     max_lifetime_session=None, session_callback=None, max_sessions_per_shard=None, \
-    soda_metadata_cache=None, ping_interval=None, user=None, proxy_user=None, password=None, \
-    newpassword=None, wallet_password=None, host=None, port=None, protocol=None, \
-    https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
-    server_type=None, cclass=None, purity=None, expire_time=None, retry_count=None, \
-    retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, \
-    ssl_server_cert_dn=None, wallet_location=None, events=None, externalauth=None, \
-    mode=None, disable_oob=None, stmtcachesize=None, edition=None, tag=None, \
-    matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], \
-    debug_jdwp=None, handle=None)
+    soda_metadata_cache=None, ping_interval=None, user=None, proxy_user=None,\
+    password=None, newpassword=None, wallet_password=None, access_token=None, \
+    host=None, port=None, protocol=None, https_proxy=None, https_proxy_port=None, \
+    service_name=None, sid=None, server_type=None, cclass=None, purity=None, \
+    expire_time=None, retry_count=None, retry_delay=None, tcp_connect_timeout=None, \
+    ssl_server_dn_match=None, ssl_server_cert_dn=None, wallet_location=None, \
+    events=None, externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \
+    edition=None, tag=None, matchanytag=None, config_dir=None, appcontext=[], \
+    shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=None)
 
   Sets one or more of the parameters.
 

doc/src/release_notes.rst

@@ -38,6 +38,9 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
+#)  Added support for token authentication (Azure OAuth and IAM) via the new
+    parameter `access_token` to :func:`oracledb.connect()` and
+    :func:`oracledb.create_pool()`.
 #)  Added method :func:`oracledb.is_thin_mode()` to support determining whether
     the driver is using thin mode or not
     (`issue 16 <https://github.com/oracle/python-oracledb/issues/10>`__).

doc/src/user_guide/appendix_a.rst

@@ -74,9 +74,13 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - No
       - Yes
       - Yes
-    * - Oracle Cloud Infrastructure Identity and Access Management (IAM) Tokens
-      - No
+    * - Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Tokens (see :ref:`iamauth`)
+      - Yes
+      - Yes
       - Yes - in connection string with appropriate Oracle Client
+    * - Open Authorization (OAuth 2.0) (see :ref:`oauth2`)
+      - Yes
+      - Yes
       - Yes - in connection string with appropriate Oracle Client
     * - Kerberos and Radius authentication
       - No

doc/src/user_guide/appendix_b.rst

@@ -177,6 +177,22 @@ bare name as a hostname is important to you in the python-oracledb Thin mode,
 then you can alter the connection string to include a port number such as
 ``hostname:1521`` or a protocol such as ``tcp://hostname``.
 
+Token Based Authentication
+--------------------------
+
+In the python-oracledb Thin mode:
+
+- When connecting to Oracle Cloud Database with mutual TLS (mTLS) using OAuth2
+  tokens, you need to explicitly set the ``config_dir``, ``wallet_location``,
+  and ``wallet_password`` parameters of :func:`~oracledb.connect` or
+  :func:`~oracledb.create_pool()`. See, :ref:`autonomousdb`.
+
+- :ref:`Open Authorization (OAuth 2.0) token based authentication connection
+  strings <oauth2connstr>` and :ref:`Oracle Cloud Infrastructure (OCI) Identity
+  and Access Management (IAM) token based authentication connection strings
+  <iamauthconnstr>` are not supported. Use ``access_token`` parameter of
+  :func:`oracledb.ConnectParams()` instead. See :ref:`tokenauth`.
+
 Transport Layer Security (TLS) Support
 --------------------------------------