1) Add new region ap-hyderabad-1

2) Enhance the support of authenticate with resource principal, add parameter logger to SignatureProvider.create_with_resource_principal
3) Added a new method SignatureProvider.get_resource_principal_claim
4) Added a new class ResourcePrincipalClaimKeys

CHANGELOG.rst

@@ -11,19 +11,23 @@ Unreleased
 Added
 _____
 
-* Added NoSQLHandleConfig.set_ssl_cipher_suites() to allow the user to configure
-  preferred SSL ciphers, and NoSQLHandleConfig.get_ssl_cipher_suites() to get
-  the ssl cipher setting.
-* Added NoSQLHandleConfig.set_ssl_protocol() to allow the user to configure
-  preferred SSL protocol, and NoSQLHandleConfig.get_ssl_protocol() to get the
-  ssl protocol setting.
-* Added NoSQLHandleConfig.set_ssl_ca_certs() to allow the user to configure SSL
-  CA certificates, and NoSQLHandleConfig.get_ssl_ca_certs() to get the SSL CA
+* Added NoSQLHandleConfig.set_ssl_cipher_suites to allow the user to configure
+  preferred SSL ciphers, and NoSQLHandleConfig.get_ssl_cipher_suites to get the
+  ssl cipher setting.
+* Added NoSQLHandleConfig.set_ssl_protocol to allow the user to configure
+  preferred SSL protocol, and NoSQLHandleConfig.get_ssl_protocol to get the ssl
+  protocol setting.
+* Added NoSQLHandleConfig.set_ssl_ca_certs to allow the user to configure SSL CA
+  certificates, and NoSQLHandleConfig.get_ssl_ca_certs to get the SSL CA
   certificates setting.
-* Cloud only. Added new regions: AP_MELBOURNE_1, AP_OSAKA_1, ME_JEDDAH_1,
-  EU_AMSTERDAM_1, CA_MONTREAL_1.
-* Cloud only. Added SignatureProvider.create_with_resource_principal to allow
-  authentication using an OCI resource principal.
+* Cloud only. Added new regions: AP_HYDERABAD_1, AP_MELBOURNE_1, AP_OSAKA_1,
+  CA_MONTREAL_1, EU_AMSTERDAM_1, ME_JEDDAH_1.
+* Cloud only. Added support for authenticating via Resource Principal. This can
+  be used in Oracle Cloud Functions to access NoSQL cloud service:
+  * Added a new method SignatureProvider.create_with_resource_principal.
+  * Added a new method SignatureProvider.get_resource_principal_claim to
+    retrieve resource principal metadata with ResourcePrincipalClaimKeys such as
+    compartment and tenancy OCID.
 * Added generic group by and SELECT DISTINCT. These features will only work with
   servers that also support generic group by.
 

docs/api/borneo.ResourcePrincipalClaimKeys.rst

@@ -0,0 +1,19 @@
+ResourcePrincipalClaimKeys
+==========================
+
+.. currentmodule:: borneo
+
+.. autoclass:: ResourcePrincipalClaimKeys
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~ResourcePrincipalClaimKeys.COMPARTMENT_ID_CLAIM_KEY
+      ~ResourcePrincipalClaimKeys.TENANT_ID_CLAIM_KEY
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: COMPARTMENT_ID_CLAIM_KEY
+   .. autoattribute:: TENANT_ID_CLAIM_KEY

docs/api/borneo.iam.SignatureProvider.rst

@@ -22,6 +22,7 @@ SignatureProvider
       ~SignatureProvider.create_with_resource_principal
       ~SignatureProvider.get_authorization_string
       ~SignatureProvider.get_logger
+      ~SignatureProvider.get_resource_principal_claim
       ~SignatureProvider.set_logger
 
    .. rubric:: Attributes Documentation
@@ -36,4 +37,5 @@ SignatureProvider
    .. automethod:: create_with_resource_principal
    .. automethod:: get_authorization_string
    .. automethod:: get_logger
+   .. automethod:: get_resource_principal_claim
    .. automethod:: set_logger

examples/utils.py

@@ -44,17 +44,13 @@ def generate_authorization_provider(tenant_id):
                 raise IllegalArgumentException(
                     'Must specify the credentials file path.')
             provider = SignatureProvider(config_file=credentials_file)
-        elif (principal == 'instance principal' or
-              principal == 'resource principals'):
+        elif principal == 'instance principal':
             if isinstance(endpoint, str):
                 region = Regions.from_region_id(endpoint)
             else:
                 region = endpoint
-            if region is None:
-                provider = SignatureProvider.create_with_instance_principal()
-            else:
-                provider = SignatureProvider.create_with_instance_principal(
-                    region=region)
+            provider = SignatureProvider.create_with_instance_principal(
+                region=region)
         elif principal == 'resource principals':
             provider = SignatureProvider.create_with_resource_principal()
         else:

src/borneo/__init__.py

@@ -9,8 +9,9 @@
 from . import kv
 from .auth import AuthorizationProvider
 from .common import (
-    Consistency, FieldRange, PutOption, State, SystemState, TableLimits,
-    TimeToLive, TimeUnit, UserInfo, Version, IndexInfo, PreparedStatement)
+    Consistency, FieldRange, PutOption, ResourcePrincipalClaimKeys, State,
+    SystemState, TableLimits, TimeToLive, TimeUnit, UserInfo, Version,
+    IndexInfo, PreparedStatement)
 from .config import (
     DefaultRetryHandler, NoSQLHandleConfig, Region, Regions, RetryHandler)
 from .driver import NoSQLHandle
@@ -76,6 +77,7 @@
            'RequestSizeLimitException',
            'RequestTimeoutException',
            'ResourceExistsException',
+           'ResourcePrincipalClaimKeys',
            'ResourceNotFoundException',
            'Result',
            'RetryHandler',

src/borneo/common.py

@@ -1191,6 +1191,30 @@ class PutOption(object):
     """Set PutOption.IF_VERSION to perform put if version operation."""
 
 
+class ResourcePrincipalClaimKeys(object):
+    """
+    Claim keys in the resource principal session token(RPST).
+
+    They can be used to retrieve resource principal metadata such as its
+    compartment and tenancy OCID.
+
+    """
+    COMPARTMENT_ID_CLAIM_KEY = 'res_compartment'
+    """
+    The claim name that the RPST holds for the resource compartment. This can be
+    passed to
+    :py:method:`borneo.iam.SignatureProvider.get_resource_principal_claim` to
+    retrieve the resource's compartment OCID.
+    """
+    TENANT_ID_CLAIM_KEY = 'res_tenant'
+    """
+    The claim name that the RPST holds for the resource tenancy. This can be
+    passed to
+    :py:method:`borneo.iam.SignatureProvider.get_resource_principal_claim` to
+    retrieve the resource's tenancy OCID.
+    """
+
+
 class SSLAdapter(adapters.HTTPAdapter):
     """
     Internal use only.

src/borneo/config.py

@@ -300,20 +300,22 @@ class Regions(object):
     """Region Location: Mumbai, India"""
     AP_SYDNEY_1 = Region('ap-sydney-1')
     """Region Location: Sydney, Australia"""
-    AP_MELBOURNE_1 = Region("ap-melbourne-1")
+    AP_MELBOURNE_1 = Region('ap-melbourne-1')
     """Region Location: Melbourne, Australia"""
-    AP_OSAKA_1 = Region("ap-osaka-1")
+    AP_OSAKA_1 = Region('ap-osaka-1')
     """Region Location: Osaka, Japan"""
+    AP_HYDERABAD_1 = Region('ap-hyderabad-1')
+    """Region Location: Hyderabad, India"""
 
     UK_LONDON_1 = Region('uk-london-1')
     """Region Location: London, United Kingdom"""
     EU_FRANKFURT_1 = Region('eu-frankfurt-1')
     """Region Location: Frankfurt, Germany"""
     EU_ZURICH_1 = Region('eu-zurich-1')
     """Region Location: Zurich, Switzerland"""
-    EU_AMSTERDAM_1 = Region("eu-amsterdam-1")
+    EU_AMSTERDAM_1 = Region('eu-amsterdam-1')
     """Region Location: Amsterdam, Netherlands"""
-    ME_JEDDAH_1 = Region("me-jeddah-1")
+    ME_JEDDAH_1 = Region('me-jeddah-1')
     """Region Location: Jeddah, Saudi Arabia"""
 
     US_ASHBURN_1 = Region('us-ashburn-1')
@@ -322,7 +324,7 @@ class Regions(object):
     """Region Location: Phoenix, AZ"""
     CA_TORONTO_1 = Region('ca-toronto-1')
     """Region Location: Toronto, Canada"""
-    CA_MONTREAL_1 = Region("ca-montreal-1")
+    CA_MONTREAL_1 = Region('ca-montreal-1')
     """Region Location: Montreal, Canada"""
 
     SA_SAOPAULO_1 = Region('sa-saopaulo-1')
@@ -356,6 +358,7 @@ class Regions(object):
     OC1_REGIONS[AP_SYDNEY_1.get_region_id()] = AP_SYDNEY_1
     OC1_REGIONS[AP_MELBOURNE_1.get_region_id()] = AP_MELBOURNE_1
     OC1_REGIONS[AP_OSAKA_1.get_region_id()] = AP_OSAKA_1
+    OC1_REGIONS[AP_HYDERABAD_1.get_region_id()] = AP_HYDERABAD_1
 
     # EMEA
     OC1_REGIONS[UK_LONDON_1.get_region_id()] = UK_LONDON_1

src/borneo/iam/iam.py

@@ -236,6 +236,23 @@ def get_region(self):
         # Internal use only.
         return self._region
 
+    def get_resource_principal_claim(self, key):
+        """
+        Resource principal session tokens carry JWT claims. Permit the retrieval
+        of the value from the token by given key.
+        See :py:class:`borneo.ResourcePrincipalClaimKeys`.
+
+        :param key: the name of a claim in the session token.
+        :type key: str
+        :returns: the claim value.
+        :rtype: str
+        """
+        if not isinstance(self._provider,
+                          oci.auth.signers.EphemeralResourcePrincipalSigner):
+            raise IllegalArgumentException(
+                'Only ephemeral resource principal support.')
+        return self._provider.get_claim(key)
+
     def set_logger(self, logger):
         CheckValue.check_logger(logger, 'logger')
         self._logger = logger
@@ -296,9 +313,9 @@ def create_with_instance_principal(iam_auth_uri=None, region=None,
             *Invalid IAM URI* error, it is optional.
         :type iam_auth_uri: str
         :param region: identifies the region will be accessed by the
-            NoSQLHandle.
+            NoSQLHandle, it is optional.
         :type region: Region
-        :param logger: the logger used by the SignatureProvider.
+        :param logger: the logger used by the SignatureProvider, it is optional.
         :type logger: Logger
         :returns: a SignatureProvider.
         :rtype: SignatureProvider
@@ -315,28 +332,33 @@ def create_with_instance_principal(iam_auth_uri=None, region=None,
                 signature_provider.set_logger(logger))
 
     @staticmethod
-    def create_with_resource_principal():
+    def create_with_resource_principal(logger=None):
         """
         Creates a SignatureProvider using a resource principal. This method may
-        be used when calling the Oracle NoSQL Database Cloud Service within an
-        Oracle Cloud Function. It authenticates with the resource principal and
-        uses a security token issued by IAM to do the actual request signing.
+        be used when calling the Oracle NoSQL Database Cloud Service from other
+        Oracle Cloud service resource such as Functions. It uses a resource
+        provider session token (RPST) that enables the resource such as function
+        to authenticate itself.
 
-        When using a resource principal the compartment (OCID) must be specified
-        on each request or defaulted by using
+        When using an resource principal the compartment id (OCID) must be
+        specified on each request or defaulted by using
         :py:meth:`borneo.NoSQLHandleConfig.set_default_compartment`. If the
-        compartment is not specified for an operation an exception will be
+        compartment id is not specified for an operation an exception will be
         thrown.
 
         See `Accessing Other Oracle Cloud Infrastructure Resources from Running
         Functions <https://docs.cloud.oracle.com/en-us/iaas/Content/Functions/
         Tasks/functionsaccessingociresources.htm>`_.
 
+        :param logger: the logger used by the SignatureProvider, it is optional.
+        :type logger: Logger
         :returns: a SignatureProvider.
         :rtype: SignatureProvider
         """
-        return SignatureProvider(
+        signature_provider = SignatureProvider(
             oci.auth.signers.get_resource_principals_signer())
+        return (signature_provider if logger is None else
+                signature_provider.set_logger(logger))
 
     def _get_signature_details(self):
         sig_details = self._signature_cache.get(SignatureProvider.CACHE_KEY)

test/parameters.py

@@ -48,7 +48,7 @@
 # Simulator running on its default port (8080) on the local machine, or a
 # on-prem proxy started by the customer. Unit tests can be run against both the
 # Cloud Simulator and on-prem proxy.
-endpoint = 'localhost:5000'
+endpoint = 'localhost:8080'
 # SSL CA certificates for on-prem proxy. Configure it to specify CA certificates
 # or set REQUESTS_CA_BUNDLE environment variable when running against a secure
 # store. For non-secure store, use the default None.
@@ -84,7 +84,7 @@ def iam_principal():
 
 
 def is_cloudsim():
-    return False
+    return True
 
 
 def is_dev_pod():
@@ -96,7 +96,7 @@ def is_minicloud():
 
 
 def is_onprem():
-    return True
+    return False
 
 
 def is_prod_pod():

test/testutils.py

@@ -155,13 +155,8 @@ def generate_authorization_provider(tenant_id):
                 region = Regions.from_region_id(endpoint)
             else:
                 region = endpoint
-            if region is None:
-                authorization_provider = (
-                    SignatureProvider.create_with_instance_principal())
-            else:
-                authorization_provider = (
-                    SignatureProvider.create_with_instance_principal(
-                        region=region))
+            authorization_provider = (
+                SignatureProvider.create_with_instance_principal(region=region))
         elif iam_principal() == 'resource principals':
             authorization_provider = (
                 SignatureProvider.create_with_resource_principal())
@@ -245,6 +240,7 @@ def get_logger():
 
 
 class InsecureAuthorizationProvider(AuthorizationProvider):
+
     def __init__(self, tenant_id):
         super(InsecureAuthorizationProvider, self).__init__()
         self._tenant_id = tenant_id
@@ -257,7 +253,8 @@ def get_authorization_string(self, request=None):
 
 
 class TestSignatureProvider(AuthorizationProvider):
-    def __init__(self, tenant_id='TestTenant', user_id='TestUser', ):
+
+    def __init__(self, tenant_id='TestTenant', user_id='TestUser'):
         super(TestSignatureProvider, self).__init__()
         self._tenant_id = tenant_id
         self._user_id = user_id