Cloud native authentication support plugins.

Author: anthony-tuininga

doc/src/api_manual/connect_params.rst

@@ -64,15 +64,15 @@ ConnectParams Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=None, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=None)
+        extra_auth_params=None, handle=None)
 
     Sets the values for one or more of the parameters of a ConnectParams
     object.
 
     .. versionchanged:: 3.0.0
 
-        The ``use_sni``, ``thick_mode_dsn_passthrough``, and ``instance_name``
-        parameters were added.
+        The ``use_sni``, ``thick_mode_dsn_passthrough``, ``extra_auth_params``
+        and ``instance_name`` parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -242,6 +242,17 @@ ConnectParams Attributes
 
     This attribute is only supported in python-oracledb Thick mode.
 
+.. attribute:: ConnectParams.extra_auth_params
+
+    This read-only attribute is a dictionary containing the configuration
+    parameters necessary for Oracle Database authentication using
+    :ref:`Azure <azurecloudnativeauthplugin>` or
+    :ref:` <ocicloudnativeauthplugin>` cloud native authentication plugins.
+
+    This attribute is supported in both python-oracledb Thin and Thick modes.
+
+    .. versionadded:: 3.0.0
+
 .. attribute:: ConnectParams.host
 
     This read-only attribute is a string that returns the name or IP address of

doc/src/api_manual/module.rst

@@ -54,7 +54,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=0)
+        extra_auth_params=None, handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -408,6 +408,13 @@ Oracledb Methods
     python-oracledb Thick mode. The default value is the value of
     :attr:`defaults.thick_mode_dsn_passthrough`.
 
+    The ``extra_auth_params`` parameter is expected to be a dictionary
+    containing the configuration parameters necessary for Oracle Database
+    authentication using :ref:`Azure <azurecloudnativeauthplugin>` or
+    :ref:`OCI <ocicloudnativeauthplugin>` cloud native authentication plugins.
+    This value is used in both the python-oracledb Thin and Thick modes. See
+    :ref:`tokenauth`.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
@@ -418,9 +425,10 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name``, ``use_sni``, and
-        ``thick_mode_dsn_passthrough`` parameters were added.  The ``pool``
-        parameter was deprecated. Use :meth:`ConnectionPool.acquire()` instead.
+        The ``pool_alias``, ``instance_name``, ``use_sni``,
+        ``thick_mode_dsn_passthrough`` and ``extra_auth_params`` parameters
+        were added. The ``pool`` parameter was deprecated: use
+        :meth:`ConnectionPool.acquire()` instead.
 
     .. versionchanged:: 2.5.0
 
@@ -467,7 +475,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=0)
+        extra_auth_params=None, handle=0)
 
     Constructor for creating a connection to the database. Returns an
     :ref:`AsyncConnection Object <asyncconnobj>`. All parameters are optional
@@ -747,15 +755,22 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
+    The ``extra_auth_params`` parameter is expected to be a dictionary
+    containing the configuration parameters necessary for Oracle Database
+    authentication using :ref:`Azure <azurecloudnativeauthplugin>` or
+    :ref:`OCI <ocicloudnativeauthplugin>` cloud native authentication plugins.
+    This value is used in both the python-oracledb Thin and Thick modes. See
+    :ref:`tokenauth`.
+
     The ``thick_mode_dsn_passthrough`` and ``handle`` parameters are ignored in
     python-oracledb Thin mode.
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name``, ``use_sni``, and
-        ``thick_mode_dsn_passthrough`` parameters were added. The ``pool``
-        parameter was deprecated. Use :meth:`AsyncConnectionPool.acquire()`
-        instead.
+        The ``pool_alias``, ``instance_name``, ``use_sni``,
+        ``thick_mode_dsn_passthrough`` and ``extra_auth_params`` parameters
+        were added. The ``pool`` parameter was deprecated: use
+        :meth:`AsyncConnectionPool.acquire()` instead.
 
     .. versionchanged:: 2.5.0
 
@@ -800,7 +815,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=0)
+        extra_auth_params=None, handle=0)
 
     Contains all the parameters that can be used to establish a connection to
     the database.
@@ -1108,15 +1123,22 @@ Oracledb Methods
     python-oracledb Thick mode. The default value is the value of
     :attr:`defaults.thick_mode_dsn_passthrough`.
 
+    The ``extra_auth_params`` parameter is expected to be a dictionary
+    containing the configuration parameters necessary for Oracle Database
+    authentication using :ref:`Azure <azurecloudnativeauthplugin>` or
+    :ref:`OCI <ocicloudnativeauthplugin>` cloud native authentication plugins.
+    This value is used in both the python-oracledb Thin and Thick modes. See
+    :ref:`tokenauth`.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode.  It should be used with extreme caution. The
     default value is *0*.
 
     .. versionchanged:: 3.0.0
 
-        The ``use_sni``, ``thick_mode_dsn_passthrough``, and ``instance_name``
-        parameters were added.
+        The ``instance_name``, ``use_sni``, ``thick_mode_dsn_passthrough`` and
+        ``extra_auth_params`` parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -1174,7 +1196,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=0)
+        extra_auth_params=None, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -1603,6 +1625,13 @@ Oracledb Methods
     python-oracledb Thick mode. The default value is
     :attr:`defaults.thick_mode_dsn_passthrough`.
 
+    The ``extra_auth_params`` parameter is expected to be a dictionary
+    containing the configuration parameters necessary for Oracle Database
+    authentication using :ref:`Azure <azurecloudnativeauthplugin>` or
+    :ref:`OCI <ocicloudnativeauthplugin>` cloud native authentication plugins.
+    This value is used in both the python-oracledb Thin and Thick modes. See
+    :ref:`tokenauth`.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
@@ -1613,8 +1642,9 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name``, ``use_sni``, and
-        ``thick_mode_dsn_passthrough`` parameters were added.
+        The ``pool_alias``, ``instance_name``, ``use_sni``,
+        ``thick_mode_dsn_passthrough`` and ``extra_auth_params`` parameters
+        were added.
 
     .. versionchanged:: 2.5.0
 
@@ -1666,7 +1696,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=0)
+        extra_auth_params=None, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`AsyncConnectionPool object <asyncconnpoolobj>` for the pool.
@@ -2005,13 +2035,21 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
+    The ``extra_auth_params`` parameter is expected to be a dictionary
+    containing the configuration parameters necessary for Oracle Database
+    authentication using :ref:`Azure <azurecloudnativeauthplugin>` or
+    :ref:`OCI <ocicloudnativeauthplugin>` cloud native authentication plugins.
+    This value is used in both the python-oracledb Thin and Thick modes. See
+    :ref:`tokenauth`.
+
     The ``handle`` and ``thick_mode_dsn_passthrough`` parameters are ignored in
     python-oracledb Thin mode.
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name``, ``use_sni``, and
-        ``thick_mode_dsn_passthrough`` parameters were added.
+        The ``pool_alias``, ``instance_name``, ``use_sni``,
+        ``thick_mode_dsn_passthrough`` and ``extra_auth_params`` parameters
+        were added.
 
     .. versionchanged:: 2.5.0
 
@@ -2230,7 +2268,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=0)
+        extra_auth_params=None, handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -2602,15 +2640,22 @@ Oracledb Methods
     python-oracledb Thick mode. The default value is
     :attr:`defualts.thick_mode_dsn_passthrough`.
 
+    The ``extra_auth_params`` parameter is expected to be a dictionary
+    containing the configuration parameters necessary for Oracle Database
+    authentication using :ref:`Azure <azurecloudnativeauthplugin>` or
+    :ref:`OCI <ocicloudnativeauthplugin>` cloud native authentication plugins.
+    This value is used in both the python-oracledb Thin and Thick modes. See
+    :ref:`tokenauth`.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode. It should be used with extreme caution. The
     default value is *0*.
 
     .. versionchanged:: 3.0.0
 
-        The ``use_sni``, ``thick_mode_dsn_passthrough``, and ``instance_name``
-        parameters were added.
+        The ``use_sni``, ``instance_name``, ``thick_mode_dsn_passthrough``,
+        ``extra_auth_params`` and ``instance_name`` parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -2651,6 +2696,22 @@ Oracledb Methods
 
     .. versionadded:: 3.0.0
 
+.. function:: register_params_hook(hook_function)
+
+    Registers a user hook function that will be called internally by
+    python-oracledb prior to connection or pool creation. The hook function
+    accepts a copy of the parameters that will be used to create the pool or
+    standalone connection and may modify them. For example, the cloud native
+    authentication plugins modify the "access_token" parameter with a function
+    that will acquire the token using information found in the
+    "extra_auth_parms" parameter.
+
+    .. note::
+
+        This method is an extension to the DB API definition.
+
+    .. versionadded:: 3.0.0
+
 .. function:: register_password_type(password_type, hook_function)
 
     Registers a user hook function that will be called internally by
@@ -2778,6 +2839,17 @@ Oracledb Methods
     (number of seconds since the epoch; see the documentation of the standard
     Python time module for details).
 
+.. function:: unregister_params_hook(hook_function)
+
+    Unregisters a user function that was earlier registered with a call to
+    :meth:`oracledb.register_params_hook()`.
+
+    .. note::
+
+        This method is an extension to the DB API definition.
+
+    .. versionadded:: 3.0.0
+
 
 .. _interval_ym:
 
@@ -4424,3 +4496,30 @@ will use to connect to Oracle Database.  See :ref:`importconfigazureplugin`
 for more information.
 
 .. versionadded:: 3.0.0
+
+.. _ocicloudnativeauthplugin:
+
+Oracle Cloud Infrastructure (OCI) Cloud Native Authentication Plugin
+--------------------------------------------------------------------
+
+``oci_tokens`` is a plugin that uses the Oracle Cloud Infrastructure (OCI)
+Software Development Kit (SDK) to generate access tokens when authenticating
+with OCI Identity and Access Management (IAM) token-based authentication.
+Importing this plugin defines and
+:meth:`registers <oracledb.register_params_hook()>`, the built-in hook function
+that generates OCI IAM access tokens. See :ref:`cloudnativeauthoci`.
+
+.. versionadded:: 3.0.0
+
+.. _azurecloudnativeauthplugin:
+
+Azure Cloud Native Authentication Plugin
+----------------------------------------
+
+``azure_tokens`` is a plugin that uses the Microsoft Authentication Library
+(MSAL) to generate access tokens when authenticating with OAuth 2.0 token-based
+authentication. Importing this plugin defines and
+:meth:`registers <oracledb.register_params_hook()>`, the built-in hook function
+that generates OAuth2 access tokens. See :ref:`cloudnativeauthoauth`.
+
+.. versionadded:: 3.0.0

doc/src/api_manual/pool_params.rst

@@ -53,14 +53,14 @@ PoolParams Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=None, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        handle=None)
+        extra_auth_params=None, handle=None)
 
         Sets one or more of the parameters.
 
         .. versionchanged:: 3.0.0
 
-            The ``use_sni``, ``thick_mode_dsn_passthrough``, and
-            ``instance_name`` parameters were added.
+            The ``use_sni``, ``thick_mode_dsn_passthrough``,
+            ``extra_auth_params`` and ``instance_name`` parameters were added.
 
         .. versionchanged:: 2.5.0
 

doc/src/release_notes.rst

@@ -108,6 +108,19 @@ Common Changes
 #)  Added :meth:`oracledb.register_password_type()` to allow users to register
     a function that will be called when a password is supplied as a dictionary
     containing the key "type".
+#)  Added :ref:`cloud native authentication <tokenauth>` support through the
+    integration of Oracle Cloud Infrastructure (OCI) SDK and Azure SDK.
+#)  Added parameter ``extra_auth_params`` to :meth:`oracledb.connect()`,
+    :meth:`oracledb.connect_async()`, :meth:`oracledb.create_pool()`,
+    and :meth:`oracledb.create_pool_async()` which is used to specify the
+    configuration parameters required for cloud native authentication.
+#)  Added :meth:`oracledb.register_params_hook()` and
+    :meth:`oracledb.unregister_params_hook()` which allow users to register or
+    unregister a function that manipulates the parameters used for creating
+    pools or standalone connections. See
+    :ref:`oci_tokens <ocicloudnativeauthplugin>` and
+    :ref:`azure_tokens <azurecloudnativeauthplugin>` plugins which make use of
+    this functionality.
 #)  Added attributes :attr:`DbObjectAttribute.precision`,
     :attr:`DbObjectAttribute.scale`, and :attr:`DbObjectAttribute.max_size` that
     provide additional metadata about