Make externalauth a common parameter (which is optional for standalone

connections).

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -23,6 +23,9 @@ Thick Mode Changes
 #)  Added support for getting the message id of the AQ message which generated
     a notification.
 #)  Fixed the ability to use external authentication with connection pools.
+#)  Added the ability to use `externalauth` as a connection parameter for
+    standalone connections in addition to creating pools. For standalone
+    connections, this parameter is optional.
 
 
 oracledb 1.0.1 (June 2022)

src/oracledb/base_impl.pxd

@@ -157,6 +157,7 @@ cdef class ConnectParamsImpl:
         public str user
         public str proxy_user
         public bint events
+        public bint externalauth
         public uint32_t mode
         public str edition
         public list appcontext
@@ -201,7 +202,6 @@ cdef class PoolParamsImpl(ConnectParamsImpl):
         public type connectiontype
         public uint32_t getmode
         public bint homogeneous
-        public bint externalauth
         public uint32_t timeout
         public uint32_t wait_timeout
         public uint32_t max_lifetime_session

src/oracledb/connect_params.py

@@ -74,6 +74,7 @@ def __init__(self, *,
                  ssl_server_cert_dn: str=None,
                  wallet_location: str=None,
                  events: bool=False,
+                 externalauth: bool=False,
                  mode: int=oracledb.AUTH_MODE_DEFAULT,
                  disable_oob: bool=False,
                  stmtcachesize: int=oracledb.defaults.stmtcachesize,
@@ -175,6 +176,9 @@ def __init__(self, *,
           query notification and high availability event notifications
           (default: False)
 
+        - externalauth: a boolean indicating whether to use external
+          authentication (default: False)
+
         - mode: authorization mode to use. For example
           oracledb.AUTH_MODE_SYSDBA (default: oracledb.AUTH_MODE_DEFAULT)
 
@@ -246,6 +250,7 @@ def __repr__(self):
                f", ssl_server_cert_dn={self.ssl_server_cert_dn!r}" + \
                f", wallet_location={self.wallet_location!r}" + \
                f", events={self.events!r}" + \
+               f", externalauth={self.externalauth!r}" + \
                f", mode={self.mode!r}" + \
                f", disable_oob={self.disable_oob!r}" + \
                f", stmtcachesize={self.stmtcachesize!r}" + \
@@ -356,6 +361,13 @@ def expire_time(self) -> Union[list, int]:
         """
         return self._impl.expire_time
 
+    @property
+    def externalauth(self) -> bool:
+        """
+        A boolean indicating whether to use external authentication.
+        """
+        return self._impl.externalauth
+
     @property
     @_address_attr
     def host(self) -> Union[list, str]:
@@ -602,6 +614,7 @@ def set(self, *,
             ssl_server_cert_dn: str=None,
             wallet_location: str=None,
             events: bool=None,
+            externalauth: bool=None,
             mode: int=None,
             disable_oob: bool=None,
             stmtcachesize: int=None,
@@ -697,6 +710,9 @@ def set(self, *,
           This value is only used in thick mode and is needed for continuous
           query notification and high availability event notifications
 
+        - externalauth: a boolean indicating whether to use external
+          authentication
+
         - mode: authorization mode to use. For example
           oracledb.AUTH_MODE_SYSDBA
 

src/oracledb/connection.py

@@ -1035,6 +1035,7 @@ def connect(dsn: str=None, *,
 
             # other parameters
             events: bool=None,
+            externalauth: bool=None,
             mode: int=None,
             disable_oob: bool=None,
             stmtcachesize: int=None,

src/oracledb/impl/base/connect_params.pyx

@@ -154,6 +154,7 @@ cdef class ConnectParamsImpl:
         self._default_description.set_from_description_args(args)
         self._default_description.set_from_security_args(args)
         self._default_address.set_from_args(args)
+        _set_bool_param(args, "externalauth", &self.externalauth)
 
     cdef int _copy(self, ConnectParamsImpl other_params) except -1:
         """
@@ -163,6 +164,7 @@ cdef class ConnectParamsImpl:
         self.user = other_params.user
         self.proxy_user = other_params.proxy_user
         self.events = other_params.events
+        self.externalauth = other_params.externalauth
         self.mode = other_params.mode
         self.edition = other_params.edition
         self.appcontext = other_params.appcontext

src/oracledb/impl/base/pool_params.pyx

@@ -52,7 +52,6 @@ cdef class PoolParamsImpl(ConnectParamsImpl):
         self.connectiontype = pool_params.connectiontype
         self.getmode = pool_params.getmode
         self.homogeneous = pool_params.homogeneous
-        self.externalauth = pool_params.externalauth
         self.timeout = pool_params.timeout
         self.wait_timeout = pool_params.wait_timeout
         self.max_lifetime_session = pool_params.max_lifetime_session
@@ -82,7 +81,6 @@ cdef class PoolParamsImpl(ConnectParamsImpl):
         self.connectiontype = args.get("connectiontype")
         _set_uint_param(args, "getmode", &self.getmode)
         _set_bool_param(args, "homogeneous", &self.homogeneous)
-        _set_bool_param(args, "externalauth", &self.externalauth)
         _set_uint_param(args, "timeout", &self.timeout)
         _set_uint_param_with_deprecated_name(args, "wait_timeout",
                                              "waitTimeout", &self.wait_timeout)

src/oracledb/impl/thick/connection.pyx

@@ -324,6 +324,8 @@ cdef class ThickConnImpl(BaseConnImpl):
             _raise_from_odpi()
         if params.username_len == 0 and params.password_len == 0:
             conn_params.externalAuth = 1
+        else:
+            conn_params.externalAuth = user_params.externalauth
         if params.cclass is not None:
             conn_params.connectionClass = params.cclass_ptr
             conn_params.connectionClassLength = params.cclass_len

src/oracledb/pool.py

@@ -553,7 +553,6 @@ def create_pool(dsn: str=None, *,
                 connectiontype: Type["connection_module.Connection"]=None,
                 getmode: int=None,
                 homogeneous: bool=True,
-                externalauth: bool=None,
                 timeout: int=0,
                 wait_timeout: int=0,
                 max_lifetime_session: int=0,
@@ -590,6 +589,7 @@ def create_pool(dsn: str=None, *,
 
                 # other parameters
                 events: bool=None,
+                externalauth: bool=None,
                 mode: int=None,
                 disable_oob: bool=None,
                 stmtcachesize: int=None,

src/oracledb/pool_params.py

@@ -57,7 +57,6 @@ def __init__(self, *,
                  connectiontype: Type["oracledb.Connection"]=None,
                  getmode: int=oracledb.POOL_GETMODE_WAIT,
                  homogeneous: bool=True,
-                 externalauth: bool=False,
                  timeout: int=0,
                  wait_timeout: int=0,
                  max_lifetime_session: int=0,
@@ -88,6 +87,7 @@ def __init__(self, *,
                  ssl_server_cert_dn: str=None,
                  wallet_location: str=None,
                  events: bool=False,
+                 externalauth: bool=False,
                  mode: int=oracledb.AUTH_MODE_DEFAULT,
                  disable_oob: bool=False,
                  stmtcachesize: int=oracledb.defaults.stmtcachesize,
@@ -129,9 +129,6 @@ def __init__(self, *,
           homogeneous (same user) or heterogeneous (multiple users) (default:
           True)
 
-        - externalauth: a boolean indicating whether to use external
-          authentication (default: False)
-
         - timeout: length of time (in seconds) that a connection may remain
           idle in the pool before it is terminated. If it is 0 then connections
           are never terminated (default: 0)
@@ -243,6 +240,9 @@ def __init__(self, *,
           query notification and high availability event notifications
           (default: False)
 
+        - externalauth: a boolean indicating whether to use external
+          authentication (default: False)
+
         - mode: authorization mode to use. For example
           oracledb.AUTH_MODE_SYSDBA (default: oracledb.AUTH_MODE_DEFAULT)
 
@@ -300,7 +300,6 @@ def __repr__(self):
                f", connectiontype={self.connectiontype!r}" + \
                f", getmode={self.getmode!r}" + \
                f", homogeneous={self.homogeneous!r}" + \
-               f", externalauth={self.externalauth!r}" + \
                f", timeout={self.timeout!r}" + \
                f", wait_timeout={self.wait_timeout!r}" + \
                f", max_lifetime_session={self.max_lifetime_session!r}" + \
@@ -328,6 +327,7 @@ def __repr__(self):
                f", ssl_server_cert_dn={self.ssl_server_cert_dn!r}" + \
                f", wallet_location={self.wallet_location!r}" + \
                f", events={self.events!r}" + \
+               f", externalauth={self.externalauth!r}" + \
                f", mode={self.mode!r}" + \
                f", disable_oob={self.disable_oob!r}" + \
                f", stmtcachesize={self.stmtcachesize!r}" + \
@@ -348,13 +348,6 @@ def connectiontype(self) -> Type["oracledb.Connection"]:
         """
         return self._impl.connectiontype
 
-    @property
-    def externalauth(self) -> bool:
-        """
-        A boolean indicating whether to use external authentication.
-        """
-        return self._impl.externalauth
-
     @property
     def getmode(self) -> int:
         """
@@ -473,7 +466,6 @@ def set(self, *,
             connectiontype: Type["oracledb.Connection"]=None,
             getmode: int=None,
             homogeneous: bool=None,
-            externalauth: bool=None,
             timeout: int=None,
             wait_timeout: int=None,
             max_lifetime_session: int=None,
@@ -504,6 +496,7 @@ def set(self, *,
             ssl_server_cert_dn: str=None,
             wallet_location: str=None,
             events: bool=None,
+            externalauth: bool=None,
             mode: int=None,
             disable_oob: bool=None,
             stmtcachesize: int=None,
@@ -541,9 +534,6 @@ def set(self, *,
         - homogeneous: a boolean indicating whether the connections are
           homogeneous (same user) or heterogeneous (multiple users)
 
-        - externalauth: a boolean indicating whether to use external
-          authentication
-
         - timeout: length of time (in seconds) that a connection may remain
           idle in the pool before it is terminated. If it is 0 then connections
           are never terminated
@@ -649,6 +639,9 @@ def set(self, *,
           This value is only used in thick mode and is needed for continuous
           query notification and high availability event notifications
 
+        - externalauth: a boolean indicating whether to use external
+          authentication
+
         - mode: authorization mode to use. For example
           oracledb.AUTH_MODE_SYSDBA
 

tests/README.md

@@ -34,6 +34,33 @@ This directory contains the test suite for python-oracledb.
 
         python drop_schema.py
 
+4.  Enable tests that require extra configuration
+
+    The following test(s) are automatically skipped if their required
+    environment variable(s) and setup is not available.
+
+    4.1  test_5000_externalauth.py
+
+         This test aims to test the usage of external authentication.
+
+         - Set the PYO_TEST_EXTERNAL_USER environment variable to the externally
+           identified user that will be connected using external authentication.
+
+         - Set up external authentication. See
+           [Connecting Using External Authentication][4] for creating an
+           Oracle Wallet or enabling OS authentication.
+
+         - Run the following SQL commands as a user with administrative
+           privileges (such as SYSTEM or ADMIN) to allow the external user to
+           connect to the database and behave as proxy for testing external
+           authentication with proxy:
+
+               grant create session to <External User>;
+
+               alter user <Schema Owner> grant connect through <External User>;
+
+
 [1]: https://github.com/oracle/python-oracledb/blob/main/tests/create_schema.py
 [2]: https://github.com/oracle/python-oracledb/blob/main/tests/test_env.py
 [3]: https://github.com/oracle/python-oracledb/blob/main/tests/drop_schema.py
+[4]: https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connecting-using-external-authentication