Package oracle.nosql.driver.iam

## Class SignatureProvider

- java.lang.Object
- - oracle.nosql.driver.iam.SignatureProvider

- All Implemented Interfaces:
    `AuthorizationProvider`, `Region.RegionProvider`

      public class SignatureProvider
      extends Object
      implements AuthorizationProvider, Region.RegionProvider

  Cloud service only.

  An instance of `AuthorizationProvider` that generates and caches signature for each request as authorization string. A number of pieces of information are required for configuration. See SDK Configuration File and Required Keys and OCIDs for additional information as well as instructions on how to create 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.

  There are three mechanisms for providing authorization information:

  1. Using a user's identity and optional profile. This authenticates and authorizes the application based on a specific user identity.
  2. Using an Instance Principal, which can be done when running on a compute instance in the Oracle Cloud Infrastructure (OCI). See `createWithInstancePrincipal()` and Calling Services from Instances.
  3. Using a Resource Principal, which is usually done when running in an OCI Function. See `createWithResourcePrincipal()` and Accessing Other Oracle Cloud Infrastructure Resources from Running Functions

  When using the first one, a User Principal, a default compartment is used and that is the root compartment of the user's tenancy. If a specific compartment is used (recommended) it can be specified as a default or per-request. In addition when using a User Principal compartments can be named by compartment name vs OCID when naming compartments and tables in `Request` classes and when naming tables in queries.

  When using an Instance Principal or Resource Principal a compartment must be specified as there is no default for these principal types. In addition these principal types limit the ability to use a compartment name vs OCID when naming compartments and tables in `Request` classes and when naming tables in queries.

  When using a specific user's identity there are several options to provide the required information:

  - Using a configuration file. See SDK Configuration File for details on the file contents. By default the file is stored in ~/.oci/config, but you may supply a path to another location. The configuration file may include multiple profiles. The constructors that use a configuration include
    - `SignatureProvider()`
    - `SignatureProvider(String)`
    - `SignatureProvider(String, String)`
  - Using information passed programmatically. The constructors that use this mechanism include
    - `SignatureProvider(String, String, String, String, char[])`
    - `SignatureProvider(String, String, String, File, char[])`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SignatureProvider.ResourcePrincipalClaimKeys` | Claim keys in the resource principal session token(RPST).

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SignatureProvider()` | Creates a SignatureProvider using a default configuration file and profile.
    `SignatureProvider​(String profileName)` | Creates a SignatureProvider using the specified profile.
    `SignatureProvider​(String configFile, String profileName)` | Creates a SignatureProvider using the specified config file and profile.
    `SignatureProvider​(String tenantId, String userId, String fingerprint, File privateKeyFile, char[] passphrase)` | Creates a SignatureProvider using directly provided user authentication information.
    `SignatureProvider​(String tenantId, String userId, String fingerprint, File privateKeyFile, char[] passphrase, Region region)` | Creates a SignatureProvider using directly provided user authentication information.
    `SignatureProvider​(String tenantId, String userId, String fingerprint, String privateKey, char[] passphrase)` | Creates a SignatureProvider using directly provided user authentication information.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Release resources provider is using.
    `static SignatureProvider` | `createWithInstancePrincipal()` | Creates a SignatureProvider using an instance principal.
    `static SignatureProvider` | `createWithInstancePrincipal​(String iamAuthUri)` | Creates a SignatureProvider using an instance principal.
    `static SignatureProvider` | `createWithInstancePrincipal​(String iamAuthUri, Region region, Logger logger)` | Creates a SignatureProvider using an instance principal.
    `static SignatureProvider` | `createWithInstancePrincipal​(Region region)` | Creates a SignatureProvider using an instance principal.
    `static SignatureProvider` | `createWithInstancePrincipalForDelegation​(File delegationTokenFile)` | Creates a SignatureProvider using an instance principal with a delegation token.
    `static SignatureProvider` | `createWithInstancePrincipalForDelegation​(String delegationToken)` | Creates a SignatureProvider using an instance principal with a delegation token.
    `static SignatureProvider` | `createWithInstancePrincipalForDelegation​(String iamAuthUri, Region region, File delegationTokenFile, Logger logger)` | Creates a SignatureProvider using an instance principal with a delegation token.
    `static SignatureProvider` | `createWithInstancePrincipalForDelegation​(String iamAuthUri, Region region, String delegationToken, Logger logger)` | Creates a SignatureProvider using an instance principal with a delegation token.
    `static SignatureProvider` | `createWithResourcePrincipal()` | Creates a SignatureProvider using a resource principal.
    `static SignatureProvider` | `createWithResourcePrincipal​(Logger logger)` | Creates a SignatureProvider using a resource principal.
    `String` | `getAuthorizationString​(Request request)` | Returns an authorization string for specified request.
    `Logger` | `getLogger()` | Returns the logger of this provider if set, null if not.
    `Region` | `getRegion()` |
    `String` | `getResourcePrincipalClaim​(String key)` | Resource principal session tokens carry JWT claims.
    `void` | `setLogger​(Logger logger)` | Sets a Logger instance for this provider.
    `void` | `setRequiredHeaders​(String authString, Request request, io.netty.handler.codec.http.HttpHeaders headers)` | Set HTTP headers required by the provider.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface oracle.nosql.driver.AuthorizationProvider

      `validateAuthString`

- - ### Constructor Detail

    - #### SignatureProvider

          public SignatureProvider()
                            throws IOException

      Creates a SignatureProvider using a default configuration file and profile. The configuration file used is `~/.oci/config`. See SDK Configuration File for details of the file's contents and format.

      When using this constructor the user has a default compartment for all tables. It is the root compartment of the user's tenancy.

      Throws:
        `IOException` - if error loading profile from OCI configuration file

    - #### SignatureProvider

          public SignatureProvider​(String profileName)
                            throws IOException

      Creates a SignatureProvider using the specified profile. The configuration file used is `~/.oci/config`. See SDK Configuration File for details of the file's contents and format.

      When using this constructor the user has a default compartment for all tables. It is the root compartment of the user's tenancy.

      Parameters:
        `profileName` - user profile name
      Throws:
        `IOException` - if error loading profile from OCI configuration file

    - #### SignatureProvider

          public SignatureProvider​(String configFile,
                                   String profileName)
                            throws IOException

      Creates a SignatureProvider using the specified config file and profile. See SDK Configuration File for details of the file's contents and format.

      When using this constructor the user has a default compartment for all tables. It is the root compartment of the user's tenancy.

      Parameters:
        `configFile` - path of configuration file
        `profileName` - user profile name
      Throws:
        `IOException` - if error loading profile from OCI configuration file

    - #### SignatureProvider

          public SignatureProvider​(String tenantId,
                                   String userId,
                                   String fingerprint,
                                   String privateKey,
                                   char[] passphrase)

      Creates a SignatureProvider using directly provided user authentication information. See Required Keys and OCIDs for details of the required parameters.

      When using this constructor the user has a default compartment for all tables. It is the root compartment of the user's tenancy.

      Parameters:
        `tenantId` - tenant id
        `userId` - user id
        `fingerprint` - fingerprint of the key being used
        `privateKey` - the string of private key used to sign request
        `passphrase` - optional passphrase for the (encrypted) private key

    - #### SignatureProvider

          public SignatureProvider​(String tenantId,
                                   String userId,
                                   String fingerprint,
                                   File privateKeyFile,
                                   char[] passphrase)

      Creates a SignatureProvider using directly provided user authentication information. See Required Keys and OCIDs for details of the required parameters.

      When using this constructor the user has a default compartment for all tables. It is the root compartment of the user's tenancy.

      Parameters:
        `tenantId` - tenant id
        `userId` - user id
        `fingerprint` - fingerprint of the key being used
        `privateKeyFile` - the file of the private key used to sign request
        `passphrase` - optional passphrase for the (encrypted) private key

    - #### SignatureProvider

          public SignatureProvider​(String tenantId,
                                   String userId,
                                   String fingerprint,
                                   File privateKeyFile,
                                   char[] passphrase,
                                   Region region)

      Creates a SignatureProvider using directly provided user authentication information. See Required Keys and OCIDs for details of the required parameters.

      When using this constructor the user has a default compartment for all tables. It is the root compartment of the user's tenancy.

      Parameters:
        `tenantId` - tenant id
        `userId` - user id
        `fingerprint` - fingerprint of the key being used
        `privateKeyFile` - the file of the private key used to sign request
        `passphrase` - optional passphrase for the (encrypted) private key
        `region` - identifies the region will be accessed by the NoSQLHandle.

  - ### Method Detail

    - #### createWithInstancePrincipal

          public static SignatureProvider createWithInstancePrincipal()

      Creates a SignatureProvider using an instance principal. This constructor 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 `NoSQLHandleConfig.setDefaultCompartment(java.lang.String)`. If the compartment id is not specified for an operation an exception will be thrown.

      See Calling Services from Instances.

      Returns:
        SignatureProvider

    - #### createWithInstancePrincipal

          public static SignatureProvider createWithInstancePrincipal​(Region region)

      Creates a SignatureProvider using an instance principal. This constructor 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 `NoSQLHandleConfig.setDefaultCompartment(java.lang.String)`. If the compartment id is not specified for an operation an exception will be thrown.

      See Calling Services from Instances.

      Parameters:
        `region` - identifies the region will be accessed by the NoSQLHandle.
      Returns:
        SignatureProvider

    - #### createWithInstancePrincipal

          public static SignatureProvider createWithInstancePrincipal​(String iamAuthUri)

      Creates a SignatureProvider using an instance principal. This constructor 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 `NoSQLHandleConfig.setDefaultCompartment(java.lang.String)`. If the compartment id is not specified for an operation an exception will be thrown.

      See Calling Services from Instances.

      Parameters:
        `iamAuthUri` - The URI is usually detected automatically, specify the URI if you need to overwrite the default, or encounter the `Invalid IAM URI` error.
      Returns:
        SignatureProvider

    - #### createWithInstancePrincipal

          public static SignatureProvider createWithInstancePrincipal​(String iamAuthUri,
                                                                      Region region,
                                                                      Logger logger)

      Creates a SignatureProvider using an instance principal. This constructor 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 `NoSQLHandleConfig.setDefaultCompartment(java.lang.String)`. If the compartment id is not specified for an operation an exception will be thrown.

      See Calling Services from Instances.

      Parameters:
        `iamAuthUri` - The URI is usually detected automatically, specify the URI if you need to overwrite the default, or encounter the `Invalid IAM URI` error.
        `region` - the region to use, it may be null
        `logger` - the logger used by the SignatureProvider.
      Returns:
        SignatureProvider

    - #### createWithInstancePrincipalForDelegation

          public static SignatureProvider createWithInstancePrincipalForDelegation​(String delegationToken)

      Creates a SignatureProvider using an instance principal with a delegation token. This constructor 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. The delegation token allows the instance to assume the privileges of the user for which the token was created.

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

      See Calling Services from Instances.

      Parameters:
        `delegationToken` - the string of delegation token that allows an instance to assume the privileges of a specific user and act on-behalf-of that user
      Returns:
        SignatureProvider

    - #### createWithInstancePrincipalForDelegation

          public static SignatureProvider createWithInstancePrincipalForDelegation​(String iamAuthUri,
                                                                                   Region region,
                                                                                   String delegationToken,
                                                                                   Logger logger)

      Creates a SignatureProvider using an instance principal with a delegation token. This constructor 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. The delegation token allows the instance to assume the privileges of the user for which the token was created.

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

      See Calling Services from Instances.

      Parameters:
        `iamAuthUri` - The URI is usually detected automatically, specify the URI if you need to overwrite the default, or encounter the `Invalid IAM URI` error.
        `region` - the region to use, it may be null
        `delegationToken` - the string of delegation token that allows an instance to assume the privileges of a specific user and act on-behalf-of that user
        `logger` - the logger used by the SignatureProvider.
      Returns:
        SignatureProvider

    - #### createWithInstancePrincipalForDelegation

          public static SignatureProvider createWithInstancePrincipalForDelegation​(File delegationTokenFile)

      Creates a SignatureProvider using an instance principal with a delegation token. This constructor 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. The delegation token allows the instance to assume the privileges of the user for which the token was created.

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

      See Calling Services from Instances.

      Parameters:
        `delegationTokenFile` - the file of delegation token that allows an instance to assume the privileges of a specific user and act on-behalf-of that user. Note that the file must only contains full string of the token.
      Returns:
        SignatureProvider

    - #### createWithInstancePrincipalForDelegation

          public static SignatureProvider createWithInstancePrincipalForDelegation​(String iamAuthUri,
                                                                                   Region region,
                                                                                   File delegationTokenFile,
                                                                                   Logger logger)

      Creates a SignatureProvider using an instance principal with a delegation token. This constructor 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. The delegation token allows the instance to assume the privileges of the user for which the token was created.

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

      See Calling Services from Instances.

      Parameters:
        `iamAuthUri` - The URI is usually detected automatically, specify the URI if you need to overwrite the default, or encounter the `Invalid IAM URI` error.
        `region` - the region to use, it may be null
        `delegationTokenFile` - the file of delegation token that allows an instance to assume the privileges of a specific user and act on-behalf-of that user. Note that the file must only contains full string of the token.
        `logger` - the logger used by the SignatureProvider.
      Returns:
        SignatureProvider

    - #### createWithResourcePrincipal

          public static SignatureProvider createWithResourcePrincipal()

      Creates a SignatureProvider using a resource principal. This constructor 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 `NoSQLHandleConfig.setDefaultCompartment(java.lang.String)`. 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.

      Returns:
        SignatureProvider

    - #### createWithResourcePrincipal

          public static SignatureProvider createWithResourcePrincipal​(Logger logger)

      Creates a SignatureProvider using a resource principal. This constructor 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 the function to authenticate itself.

      When using an resource principal the compartment id (OCID) must be specified on each request or defaulted by using `NoSQLHandleConfig.setDefaultCompartment(java.lang.String)`. 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` - the logger used by the SignatureProvider
      Returns:
        SignatureProvider

    - #### getAuthorizationString

          public String getAuthorizationString​(Request request)

      Description copied from interface: `AuthorizationProvider`
      Returns an authorization string for specified request. This is sent to the server in the request for authorization. Authorization information can be request-dependent.
      Specified by:
        `getAuthorizationString` in interface `AuthorizationProvider`
      Parameters:
        `request` - the request being processed
      Returns:
        a string indicating that the application is authorized to perform the request

    - #### setRequiredHeaders

          public void setRequiredHeaders​(String authString,
                                         Request request,
                                         io.netty.handler.codec.http.HttpHeaders headers)

      Description copied from interface: `AuthorizationProvider`
      Set HTTP headers required by the provider.
      Specified by:
        `setRequiredHeaders` in interface `AuthorizationProvider`
      Parameters:
        `authString` - the authorization string for the request
        `request` - the request being processed
        `headers` - the HTTP headers

    - #### close

          public void close()

      Description copied from interface: `AuthorizationProvider`
      Release resources provider is using.
      Specified by:
        `close` in interface `AuthorizationProvider`

    - #### getRegion

          public Region getRegion()

      Specified by:
        `getRegion` in interface `Region.RegionProvider`
      Returns:
        the Region to use for NoSQLHandle

    - #### setLogger

          public void setLogger​(Logger logger)

      Sets a Logger instance for this provider. If not set, the logger associated with the driver is used.
      Parameters:
        `logger` - the logger

    - #### getLogger

          public Logger getLogger()

      Returns the logger of this provider if set, null if not.
      Returns:
        logger

    - #### getResourcePrincipalClaim

          public String getResourcePrincipalClaim​(String key)

      Resource principal session tokens carry JWT claims. Permit the retrieval of the value from the token by given key. See `SignatureProvider.ResourcePrincipalClaimKeys`
      Parameters:
        `key` - the name of a claim in the session token
      Returns:
        the claim value.