# Package oracle.nosql.driver.iam

package oracle.nosql.driver.iam
This package contains the public API for managing security for the Oracle NoSQL Database Cloud using Oracle Cloud Infrastructure Identity and Access Management (IAM). It is specific to the Cloud Service.

All operations require a request signature that is used by the system to authorize the operation. Managing IAM identities and policies is outside of the scope of this documentation. The interfaces and classes in this package are used to generate a request signature for each operation.

`SignatureProvider` is the class that uses authentication information of user, instance or resource principal to generate a request signature for each operation.

The request signature produced by provider comprises the following headers:

1. (request-target)
2. host
3. date
4. opc-obo-token (optional)

Note that `opc-obo-token` header is included only if the provider is created with instance principal for delegation.

Example request signature:

    Signature version="1",keyId="keyId",algorithm="rsa-sha256", headers="(request-target) host date",signature="Base64(RSA-SHA256(signing_string))"

SignatureProvider caches the request signature to improve the driver-side performance. The default cache duration is 4 minutes. The cached signature is refreshed asynchronously by a refresh task that is scheduled to renew the cached signature 20 seconds ahead of the cache eviction.

When SignatureProvider is created with a user principal either using OCI configuration file or passing user authentication information directly, the request signature is calculated with user's private key. See Required Keys and OCIDs for details of the required parameters.

SignatureProvider can also be created with instance or resource principal. See Calling Services from Instances and Accessing Other Oracle Cloud Infrastructure Resources from Running Functions for details of the required configurations. When using instance or resource principal, the request signature is created with a security token issued by IAM. The security token is cached and refreshed by the provider transparently. When refreshing or fetching the cached signature, the security token is refreshed if token is close to its expiration time, by default 4 minutes ahead. If the lifetime of the security token is shorter than 4 minutes, the provider will always refresh at the token half-life.

- Related Packages
  Package
  Description
  oracle.nosql.driver
  Contains the public API for using the Oracle NoSQL Database as well as configuration and common parameter classes used in database operations.
  oracle.nosql.driver.kv
  This package contains classes that are specific to using the driver on-premises and not applicable to the Cloud Service.
  oracle.nosql.driver.ops
  Contains the input and response classes used for Oracle NoSQL Database operations.
  oracle.nosql.driver.values
  The classes in this package are used to represent and manipulate data in the Oracle NoSQL Database.
- Classes
  Class
  Description
  OCIConfigFileReader
  Cloud service only.
  OCIConfigFileReader.OCIConfigFile
  Cloud service only.
  SignatureProvider
  Cloud service only.
  SignatureProvider.ResourcePrincipalClaimKeys
  Claim keys in the resource principal session token(RPST).