Align syntax with node-oracledb and other drivers.

Author: anthony-tuininga

doc/src/user_guide/connection_handling.rst

@@ -1227,8 +1227,8 @@ syntax is::
     {
         "user": "scott",
         "password": {
-            "type": "oci-vault",
-            "uri": "oci.vaultsecret.my-secret-id"
+            "type": "ocivault",
+            "value": "oci.vaultsecret.my-secret-id"
             "authentication": {
                 "method": "OCI_INSTANCE_PRINCIPAL"
             }
@@ -1241,15 +1241,16 @@ syntax is::
         }
     }
 
-Passwords can optionally be stored using the Azure Key Vault. To do this, you
-must define the Azure Key Vault credentials in the ``password`` key. In
-this, the ``azure_client_id`` and ``azure_tenant_id`` must be specified. Also,
-either ``azure_client_secret`` or ``azure_client_certificate_path`` should be
-specified. For example::
+Passwords can optionally be stored using the Azure Key Vault. To do this,
+you must ``import oracledb.plugins.azure_config_provider`` in your application and you must
+define the Azure Key Vault credentials in the ``password`` key.
+In this, the ``azure_client_id`` and ``azure_tenant_id`` must be specified.
+Also, either ``azure_client_secret`` or ``azure_client_certificate_path``
+should be specified. For example::
 
     "password": {
-        "type": "azure-vault",
-        "uri": "<Azure Key Vault URI>",
+        "type": "azurevault",
+        "value": "<Azure Key Vault URI>",
         "authentication": {
             "azure_tenant_id": "<tenant_id>",
             "azure_client_id": "<client_id>",
@@ -1260,8 +1261,8 @@ specified. For example::
 Or::
 
     "password": {
-        "type": "azure-vault",
-        "uri": "<Azure Key Vault URI>",
+        "type": "azurevault",
+        "value": "<Azure Key Vault URI>",
         "authentication": {
             "azure_tenant_id": "<tenant_id>",
             "azure_client_id": "<client_id>",
@@ -1277,7 +1278,7 @@ configuration provider is:
 
 .. code-block:: python
 
-    configociurl = "config-ociobject://abc.oraclecloud.com/n/abcnamespace/b/abcbucket/o/abcobject?oci_tenancy=abc123&oci_user=ociuser1&oci_fingerprint=ab:14:ba:13&oci_key_file=ociabc/ocikeyabc.pem"
+    configociurl = "config-ociobject://abc.oraclecloud.com/n/abcnamespace/b/abcbucket/o/abcobject?authentication=oci_default&oci_tenancy=abc123&oci_user=ociuser1&oci_fingerprint=ab:14:ba:13&oci_key_file=ociabc/ocikeyabc.pem"
 
 To create a :ref:`standalone connection <standaloneconnection>` you could use
 this like:
@@ -1286,7 +1287,7 @@ this like:
 
     import oracledb.plugins.oci_config_provider
 
-    configociurl = "config-ociobject://abc.oraclecloud.com/n/abcnamespace/b/abcbucket/o/abcobject?oci_tenancy=abc123&oci_user=ociuser1&oci_fingerprint=ab:14:ba:13&oci_key_file=ociabc/ocikeyabc.pem"
+    configociurl = "config-ociobject://abc.oraclecloud.com/n/abcnamespace/b/abcbucket/o/abcobject?authentication=oci_default&oci_tenancy=abc123&oci_user=ociuser1&oci_fingerprint=ab:14:ba:13&oci_key_file=ociabc/ocikeyabc.pem"
 
     connection = oracledb.connect(dsn=configociurl)
 

src/oracledb/plugins/azure_config_provider.py

@@ -47,20 +47,25 @@
 )
 
 
+def _get_authentication_method(parameters):
+    auth_method = parameters.get("authentication", parameters.get("method"))
+    if auth_method is not None:
+        auth_method = auth_method.upper()
+        if auth_method == "AZURE_DEFAULT":
+            auth_method = None
+    return auth_method
+
+
 def _get_credential(parameters):
     """
     Returns the appropriate credential given the input supplied by the original
     connect string.
     """
 
     tokens = []
-    auth = parameters.get("authentication")
-    if auth is not None:
-        auth = auth.upper()
-        if auth == "AZURE_DEFAULT":
-            auth = None
+    auth_method = _get_authentication_method(parameters)
 
-    if auth is None or auth == "AZURE_SERVICE_PRINCIPAL":
+    if auth_method is None or auth_method == "AZURE_SERVICE_PRINCIPAL":
         if "azure_client_secret" in parameters:
             tokens.append(
                 ClientSecretCredential(
@@ -69,7 +74,7 @@ def _get_credential(parameters):
                     _get_required_parameter(parameters, "azure_client_secret"),
                 )
             )
-        if "azure_client_certificate_path" in parameters:
+        elif "azure_client_certificate_path" in parameters:
             tokens.append(
                 CertificateCredential(
                     _get_required_parameter(parameters, "azure_tenant_id"),
@@ -79,25 +84,79 @@ def _get_credential(parameters):
                     ),
                 )
             )
-    if auth is None or auth == "AZURE_MANAGED_IDENTITY":
+    if auth_method is None or auth_method == "AZURE_MANAGED_IDENTITY":
         client_id = parameters.get("azure_managed_identity_client_id")
         if client_id is not None:
             tokens.append(ManagedIdentityCredential(client_id=client_id))
 
     if len(tokens) == 0:
-        message = "Authentication options not available in Connection String"
+        message = (
+            "Authentication options were not available in Connection String"
+        )
         raise Exception(message)
     elif len(tokens) == 1:
         return tokens[0]
     tokens.append(EnvironmentCredential())
     return ChainedTokenCredential(*tokens)
 
 
-def _get_required_parameter(parameters, name):
+def _get_password(pwd_string, parameters):
+    try:
+        pwd = json.loads(pwd_string)
+    except json.JSONDecodeError:
+        message = (
+            "Password is expected to be JSON"
+            " containing Azure Vault details."
+        )
+        raise Exception(message)
+
+    pwd["value"] = pwd.pop("uri")
+    pwd["type"] = "azurevault"
+
+    # make authentication section
+    pwd["authentication"] = authentication = {}
+
+    authentication["method"] = auth_method = _get_authentication_method(
+        parameters
+    )
+
+    if auth_method is None or auth_method == "AZURE_SERVICE_PRINCIPAL":
+        if "azure_client_secret" in parameters:
+            authentication["azure_tenant_id"] = _get_required_parameter(
+                parameters, "azure_tenant_id"
+            )
+            authentication["azure_client_id"] = _get_required_parameter(
+                parameters, "azure_client_id"
+            )
+            authentication["azure_client_secret"] = _get_required_parameter(
+                parameters, "azure_client_secret"
+            )
+
+        elif "azure_client_certificate_path" in parameters:
+            authentication["azure_tenant_id"] = (
+                _get_required_parameter(parameters, "azure_tenant_id"),
+            )
+            authentication["azure_client_id"] = (
+                _get_required_parameter(parameters, "azure_client_id"),
+            )
+            authentication["azure_client_certificate_path"] = (
+                _get_required_parameter(
+                    parameters, "azure_client_certificate_path"
+                )
+            )
+
+    if auth_method is None or auth_method == "AZURE_MANAGED_IDENTITY":
+        authentication["azure_managed_identity_client_id"] = parameters.get(
+            "azure_managed_identity_client_id"
+        )
+    return pwd
+
+
+def _get_required_parameter(parameters, name, location="connection string"):
     try:
         return parameters[name]
     except KeyError:
-        message = f'Parameter named "{name}" missing from connection string'
+        message = f'Parameter named "{name}" is missing from {location}'
         raise Exception(message) from None
 
 
@@ -134,7 +193,7 @@ def _parse_parameters(protocol_arg: str) -> dict:
 
 
 def password_type_azure_vault_hook(args):
-    uri = _get_required_parameter(args, "uri")
+    uri = _get_required_parameter(args, "value", '"password" key section')
     credential = args.get("credential")
 
     if credential is None:
@@ -144,7 +203,7 @@ def password_type_azure_vault_hook(args):
         auth = args.get("authentication")
         if auth is None:
             raise Exception(
-                "Azure Vault authentication details are not provided."
+                "Azure Vault authentication details were not provided."
             )
         credential = _get_credential(auth)
 
@@ -182,17 +241,8 @@ def _process_config(parameters, connect_params):
     config["user"] = _get_setting(client, key, "user", label, required=False)
     pwd = _get_setting(client, key, "password", label, required=False)
     if pwd is not None:
-        try:
-            pwd = json.loads(pwd)
-            pwd["type"] = "azure-vault"
-            pwd["credential"] = credential
-        except json.JSONDecodeError:
-            message = (
-                "Password is expected to be JSON"
-                " containing Azure Vault details."
-            )
-            raise Exception(message)
-    config["password"] = pwd
+        config["password"] = _get_password(pwd, parameters)
+
     config["config_time_to_live"] = _get_setting(
         client, key, "config_time_to_live", label, required=False
     )
@@ -217,5 +267,5 @@ def config_azure_hook(protocol, protocol_arg, connect_params):
     _process_config(parameters, connect_params)
 
 
-oracledb.register_password_type("azure-vault", password_type_azure_vault_hook)
+oracledb.register_password_type("azurevault", password_type_azure_vault_hook)
 oracledb.register_protocol("config-azure", config_azure_hook)

src/oracledb/plugins/oci_config_provider.py

@@ -90,13 +90,11 @@ def _get_config(parameters, connect_params):
     if connect_params.user is None:
         config["user"] = settings.get("user")
         if "password" in settings:
-            pwd = settings["password"]
-            if settings["password"]["type"] == "oci-vault":
-                pwd["credential"] = credential
-                pwd["auth"] = auth_method
-
-            # password should be stored in JSON and not plain text.
-            config["password"] = pwd
+            config["password"] = pwd = settings["password"]
+            if pwd["type"] == "ocivault":
+                authentication = pwd.setdefault("authentication", {})
+                authentication.setdefault("method", auth_method)
+                authentication["credential"] = credential
 
     # config cache settings
     config["config_time_to_live"] = settings.get("config_time_to_live")
@@ -116,12 +114,18 @@ def _get_credential(parameters):
     Returns the appropriate credential given the input supplied by the original
     connect string.
     """
-    auth = parameters.get("authentication")
-    if auth is not None:
-        auth = auth.upper()
+    auth_method = parameters.get("authentication", parameters.get("method"))
+
+    if auth_method is not None:
+        auth_method = auth_method.upper()
+
+    # if region is not in connection string, retrieve from object server name.
+    region = parameters.get(
+        "oci_region", _retrieve_region(parameters.get("objservername"))
+    )
 
     try:
-        if auth is None or auth == "OCI_DEFAULT":
+        if auth_method is None or auth_method == "OCI_DEFAULT":
             # Default Authentication
             # default path ~/.oci/config
             return oci_from_file(), None
@@ -136,30 +140,30 @@ def _get_credential(parameters):
                 fingerprint=parameters["oci_fingerprint"],
                 key_file=parameters["oci_key_file"],
                 private_key_content=public_key,
-                region=_retrieve_region(parameters.get("objservername")),
+                region=region,
             )
             return provider, None
 
-    if auth == "OCI_INSTANCE_PRINCIPAL":
+    if auth_method == "OCI_INSTANCE_PRINCIPAL":
         signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
         return (
-            dict(region=_retrieve_region(parameters.get("objservername"))),
+            dict(region=region),
             signer,
         )
 
-    elif auth == "OCI_RESOURCE_PRINCIPAL":
-        rps = oci.auth.signers.get_resource_principals_signer()
-        return {}, rps
+    elif auth_method == "OCI_RESOURCE_PRINCIPAL":
+        signer = oci.auth.signers.get_resource_principals_signer()
+        return {}, signer
     else:
-        msg = "Authentication options not available in Connection String"
+        msg = "Authentication options were not available in Connection String"
         raise Exception(msg)
 
 
-def _get_required_parameter(parameters, name):
+def _get_required_parameter(parameters, name, location="connection string"):
     try:
         return parameters[name]
     except KeyError:
-        message = f'Parameter named "{name}" missing from connect string'
+        message = f'Parameter named "{name}" is missing from {location}'
         raise Exception(message) from None
 
 
@@ -186,23 +190,24 @@ def _parse_parameters(protocol_arg: str) -> dict:
 
 
 def password_type_oci_vault_hook(args):
-    secret_id = args.get("uri")
-    credential = args.get("credential")
+    secret_id = _get_required_parameter(
+        args, "value", '"password" key section'
+    )
+    authentication = args.get("authentication")
+    if authentication is None:
+        raise Exception(
+            "OCI Key Vault authentication details were not provided."
+        )
 
     # if credentials are not present, create credentials with given
     # authentication details.
+    credential = authentication.get("credential")
     if credential is None:
-        auth = _get_required_parameter(args, "auth")
-        if auth is None:
-            raise Exception(
-                "OCI Key Vault authentication details are not provided."
-            )
-        credential, signer = _get_credential(auth)
-    auth_method = args.get("auth")
+        credential, signer = _get_credential(authentication)
 
+    auth_method = authentication.get("method")
     if auth_method is not None:
         auth_method = auth_method.upper()
-
     if auth_method is None or auth_method == "OCI_DEFAULT":
         secret_client_oci = oci_secrets_client(credential)
     elif auth_method == "OCI_INSTANCE_PRINCIPAL":
@@ -216,18 +221,18 @@ def password_type_oci_vault_hook(args):
             config=credential, signer=signer
         )
 
-    get_secret_bundle_request = {"secret_id": secret_id}
     get_secret_bundle_response = secret_client_oci.get_secret_bundle(
-        **get_secret_bundle_request
+        secret_id=secret_id
     )
     # decoding the vault content
     b64content = get_secret_bundle_response.data.secret_bundle_content.content
     return base64.b64decode(b64content).decode()
 
 
 def _retrieve_region(objservername):
-    arr = objservername.split(".")
-    return arr[1].lower().replace("_", "-")
+    if objservername is not None:
+        arr = objservername.split(".")
+        return arr[1].lower().replace("_", "-")
 
 
 def _stream_to_string(stream):
@@ -244,5 +249,5 @@ def config_oci_hook(
     _get_config(parameters, connect_params)
 
 
-oracledb.register_password_type("oci-vault", password_type_oci_vault_hook)
+oracledb.register_password_type("ocivault", password_type_oci_vault_hook)
 oracledb.register_protocol("config-ociobject", config_oci_hook)