SignatureProvider

class borneo.iam.SignatureProvider(provider=None, config_file=None, profile_name=None, tenant_id=None, user_id=None, fingerprint=None, private_key=None, pass_phrase=None, region=None, duration_seconds=240, refresh_ahead=10)

Bases: borneo.auth.AuthorizationProvider

Cloud service only.

An instance of borneo.AuthorizationProvider that generates and caches signature for each request as authorization string. A number of pieces of information are required for configuration. See Required Keys and OCIDs for information and instructions on how to create the required keys and OCIDs for configuration. The required information includes:

• A signing key, used to sign requests.
• A pass phrase for the key, if it is encrypted.
• The fingerprint of the key pair used for signing.
• The OCID of the tenancy.
• The OCID of a user in the tenancy.

All of this information is required to authenticate and authorize access to the service. See Acquire Credentials for the Oracle NoSQL Database Cloud Service for information on how to acquire this information.

There are three different ways to authorize an application:

1. Using a specific user’s identity.
2. Using an Instance Principal, which can be done when running on a compute instance in the Oracle Cloud Infrastructure (OCI). See create_with_instance_principal() and Calling Services from Instances.
3. Using a Resource Principal, which can be done when running within a Function within the Oracle Cloud Infrastructure (OCI). See create_with_resource_principal() and Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.

The latter 2 limit the ability to use a compartment name vs OCID when naming compartments and tables in Request classes and when naming tables in queries. A specific user identity is best for naming flexibility, allowing both compartment names and OCIDs.

When using a specific user’s identity there are 3 options for providing the required information:

1. Using a instance of oci.signer.Signer or oci.auth.signers.SecurityTokenSigner
2. Directly providing the credentials via parameters
3. Using a configuration file

Only one method of providing credentials can be used, and if they are mixed the priority from high to low is:

• Signer or SecurityTokenSigner(provider is used)
• Credentials as arguments (tenant_id, etc used)
• Configuration file (config_file is used)

Parameters:

• provider (Signer or SecurityTokenSigner) – an instance of oci.signer.Signer or oci.auth.signers.SecurityTokenSigner.
• config_file (str) – path of configuration file.
• profile_name (str) – user profile name. Only valid with config_file.
• tenant_id (str) – id of the tenancy
• user_id (str) – id of a specific user
• private_key (str) – path to private key or private key content
• fingerprint (str) – fingerprint for the private key
• pass_phrase (str) – pass_phrase for the private key if created
• region (Region) – identifies the region will be accessed by the NoSQLHandle
• duration_seconds (int) – the signature cache duration in seconds.
• refresh_ahead (int) – the refresh time before signature cache expiry in seconds.

Raises:

IllegalArgumentException – raises the exception if the parameters are not valid.

Attributes Summary

DEFAULT_REFRESH_AHEAD	Default refresh time before signature expiry, 10 seconds.
MAX_ENTRY_LIFE_TIME	Maximum lifetime of signature 240 seconds.

Methods Summary

close()	Closes the signature provider.
create_with_instance_principal([…])	Creates a SignatureProvider using an instance principal.
create_with_resource_principal([logger])	Creates a SignatureProvider using a resource principal.
get_authorization_string([request])	Returns an authorization string for the specified request.
get_logger()	Returns the logger of this provider if set, None if not.
get_resource_principal_claim(key)	Resource principal session tokens carry JWT claims.
set_logger(logger)	Sets a logger instance for this provider.

Attributes Documentation

DEFAULT_REFRESH_AHEAD = 10

Default refresh time before signature expiry, 10 seconds.

MAX_ENTRY_LIFE_TIME = 240

Maximum lifetime of signature 240 seconds.

Methods Documentation

close()

Closes the signature provider.

static create_with_instance_principal(iam_auth_uri=None, region=None, logger=None)

Creates a SignatureProvider using an instance principal. This method may be used when calling the Oracle NoSQL Database Cloud Service from an Oracle Cloud compute instance. It authenticates with the instance principal and uses a security token issued by IAM to do the actual request signing.

When using an instance principal the compartment id (OCID) must be specified on each request or defaulted by using borneo.NoSQLHandleConfig.set_default_compartment(). If the compartment is not specified for an operation an exception will be thrown.

See Calling Services from Instances

Parameters:

• iam_auth_uri (str) – the URI is usually detected automatically, specify the URI if you need to overwrite the default, or encounter the Invalid IAM URI error, it is optional.
• region (Region) – identifies the region will be accessed by the NoSQLHandle, it is optional.
• logger (Logger) – the logger used by the SignatureProvider, it is optional.

Returns:

a SignatureProvider.

Return type:

SignatureProvider

static 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 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 an resource principal the compartment id (OCID) must be specified on each request or defaulted by using borneo.NoSQLHandleConfig.set_default_compartment(). If the compartment id is not specified for an operation an exception will be thrown.

See Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.

Parameters:logger (Logger) – the logger used by the SignatureProvider, it is optional. Returns:a SignatureProvider. Return type:SignatureProvider

get_authorization_string(request=None)

Returns an authorization string for the specified request. The string is sent to the server in the request and is used for authorization. Authorization information can be request-dependent.

Parameters:request (Request) – the request to be issued. This is an instance of Request(). Returns:a string indicating that the application is authorized to perform the request. Return type:str

get_logger()

Returns the logger of this provider if set, None if not.

Returns:the logger. Return type:Logger or None

get_resource_principal_claim(key)

Resource principal session tokens carry JWT claims. Permit the retrieval of the value from the token by given key. See borneo.ResourcePrincipalClaimKeys.

Parameters:key (str) – the name of a claim in the session token. Returns:the claim value. Return type:str

set_logger(logger)

Sets a logger instance for this provider. If not set, the logger associated with the driver is used.

Parameters:logger (Logger) – the logger to use. Returns:self. Raises:IllegalArgumentException – raises the exception if logger is not an instance of Logger.