Added Instance Principal authentication support when using OCI Cloud

Native Authentication.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -37,6 +37,8 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
+#)  Added Instance Principal authentication support when using
+    :ref:`OCI Cloud Native Authentication <cloudnativeauthoci>`.
 #)  Use GitHub Arm Linux runner for builds. Supplied by wojiushixiaobai
     (`PR 496 <https://github.com/oracle/python-oracledb/pull/496>`__).
 #)  Fix bug with GitHub build action merge artifacts step

doc/src/user_guide/connection_handling.rst

@@ -4528,11 +4528,15 @@ the following table.
       - Description
       - Required or Optional
     * - ``auth_type``
-      - The authentication type. The value should be the string "ConfigFileAuthentication" or "SimpleAuthentication".
+      - The authentication type. The value should be the string "ConfigFileAuthentication", "SimpleAuthentication", or "InstancePrincipal".
 
-        In Configuration File Authentication, the location of the configuration file containing the necessary information must be provided. By default, this file is located at */home/username/.oci/config*, unless a custom location is specified during OCI IAM setup.
+        With Configuration File Authentication, the location of a configuration file containing the necessary information must be provided. By default, this file is located at */home/username/.oci/config*, unless a custom location is specified during OCI IAM setup.
 
-        In Simple Authentication, the individual configuration parameters can be provided at runtime.
+        With Simple Authentication, the individual configuration parameters can be provided at runtime.
+
+        With Instance Principal Authentication, OCI compute instances can be authorized to access services on Oracle Cloud such as Oracle Autonomous Database. Python-oracledb applications running on such a compute instance are automatically authenticated, eliminating the need to provide database user credentials. This authentication method will only work on compute instances where internal network endpoints are reachable. For more information on OCI compute instances, see `OCI Compute Instances <https://docs.oracle.com/en-us/iaas/compute-cloud-at-customer/topics/compute/compute-instances.htm>`__, `Creating a Compute Instance <https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/launchinginstance.htm>`__, and `Calling Services from a Compute Instance <https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm>`__.
+
+        See `OCI SDK Authentication Methods <https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm>`__ for more information.
       - Required
     * - ``user``
       - The Oracle Cloud Identifier (OCID) of the user invoking the API. For example, *ocid1.user.oc1..<unique_ID>*.
@@ -4571,6 +4575,15 @@ the following table.
 
         This parameter can be specified when the value of the ``auth_type`` key is "ConfigFileAuthentication".
       - Optional
+    * - ``scope``
+      - This parameter identifies all databases in the cloud tenancy of the authenticated user. The default value is *urn:oracle:db::id::**.
+
+        A scope that authorizes access to all databases within a compartment has the format *urn:oracle:db::id::<compartment-ocid>*, for example, urn:oracle:db::id::ocid1.compartment.oc1..xxxxxxxx.
+
+        A scope that authorizes access to a single database within a compartment has the format *urn:oracle:db::id::<compartment-ocid>::<database-ocid>*, for example, urn:oracle:db::id::ocid1.compartment.oc1..xxxxxx::ocid1.autonomousdatabase.oc1.phx.xxxxxx.
+
+        This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication", "ConfigFileAuthentication", or "InstancePrincipal".
+      - Optional
 
 All keys and values other than ``auth_type`` are used by the `OCI SDK
 <https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm>`__ API

src/oracledb/plugins/oci_tokens.py

@@ -44,6 +44,8 @@ def generate_token(token_auth_config, refresh=False):
         return _config_file_based_authentication(token_auth_config)
     elif auth_type == "simpleauthentication":
         return _simple_authentication(token_auth_config)
+    elif auth_type == "instanceprincipal":
+        return _instance_principal_authentication(token_auth_config)
     else:
         raise ValueError(
             f"Unrecognized auth_type authentication method {user_auth_type}"
@@ -86,6 +88,23 @@ def _get_key_pair():
     return {"private_key": private_key_pem, "public_key": public_key_pem}
 
 
+def _generate_access_token(client, token_auth_config):
+    """
+    Token generation logic used by authentication methods.
+    """
+    key_pair = _get_key_pair()
+    scope = token_auth_config.get("scope", "urn:oracle:db::id::*")
+
+    details = oci.identity_data_plane.models.GenerateScopedAccessTokenDetails(
+        scope=scope, public_key=key_pair["public_key"]
+    )
+    response = client.generate_scoped_access_token(
+        generate_scoped_access_token_details=details
+    )
+
+    return (response.data.token, key_pair["private_key"])
+
+
 def _config_file_based_authentication(token_auth_config):
     """
     Config file base authentication implementation: config parameters
@@ -103,21 +122,7 @@ def _config_file_based_authentication(token_auth_config):
     # Initialize service client with default config file
     client = oci.identity_data_plane.DataplaneClient(config)
 
-    key_pair = _get_key_pair()
-
-    response = client.generate_scoped_access_token(
-        generate_scoped_access_token_details=oci.identity_data_plane.models.GenerateScopedAccessTokenDetails(
-            scope="urn:oracle:db::id::*", public_key=key_pair["public_key"]
-        )
-    )
-
-    # access_token is a tuple holding token and private key
-    access_token = (
-        response.data.token,
-        key_pair["private_key"],
-    )
-
-    return access_token
+    return _generate_access_token(client, token_auth_config)
 
 
 def _simple_authentication(token_auth_config):
@@ -134,24 +139,18 @@ def _simple_authentication(token_auth_config):
     }
     oci.config.validate_config(config)
 
-    # Initialize service client with given configuration
     client = oci.identity_data_plane.DataplaneClient(config)
+    return _generate_access_token(client, token_auth_config)
 
-    key_pair = _get_key_pair()
 
-    response = client.generate_scoped_access_token(
-        generate_scoped_access_token_details=oci.identity_data_plane.models.GenerateScopedAccessTokenDetails(
-            scope="urn:oracle:db::id::*", public_key=key_pair["public_key"]
-        )
-    )
-
-    # access_token is a tuple holding token and private key
-    access_token = (
-        response.data.token,
-        key_pair["private_key"],
-    )
-
-    return access_token
+def _instance_principal_authentication(token_auth_config):
+    """
+    Instance principal authentication: for compute instances
+    with dynamic group access.
+    """
+    signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
+    client = oci.identity_data_plane.DataplaneClient(config={}, signer=signer)
+    return _generate_access_token(client, token_auth_config)
 
 
 def oci_token_hook(params: oracledb.ConnectParams):