Package oracle.nosql.driver.iam

Class SignatureProvider

java.lang.Object
oracle.nosql.driver.iam.SignatureProvider
All Implemented Interfaces:
AuthorizationProvider, oracle.nosql.driver.Region.RegionProvider
public class SignatureProvider extends Object implements AuthorizationProvider, oracle.nosql.driver.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:

  • Constructor Details

    • 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.

    • SignatureProvider

      public SignatureProvider(oracle.nosql.driver.iam.AuthenticationProfileProvider provider)
      Constructor for SignatureProvider given an AuthenticationProfileProvider. This is for advanced use only; use of the create* methods is preferred. The SignatureProvider that generates and caches request signature using key id and private key supplied by AuthenticationProfileProvider.
      Parameters:
      provider - The provider to use

    • SignatureProvider

      public SignatureProvider(oracle.nosql.driver.iam.AuthenticationProfileProvider profileProvider, int durationSeconds, int refreshAheadMs)
      Constructor for SignatureProvider given an AuthenticationProfileProvider and refresh details. This is for advanced use only; use of the create* methods is preferred. The constructor that is able to set refresh time before signature expires.
      Parameters:
      profileProvider - The provider to use
      durationSeconds - amount of time to keep signature before refresh
      refreshAheadMs - how soon before expiry to start a new refresh

  • Method Details

    • 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 iamAuthUrl)
      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:
      iamAuthUrl - The URL is usually detected automatically, specify the URL if you need to overwrite the default, or the region of instance doesn't exists in registered regions listed in Region.
      Returns:
      SignatureProvider

    • createWithInstancePrincipal

      public static SignatureProvider createWithInstancePrincipal(String iamAuthUrl, 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:
      iamAuthUrl - The URL is usually detected automatically, specify the URL if you need to overwrite the default, or the region of instance doesn't exists in registered regions listed in Region.
      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 iamAuthUrl, 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:
      iamAuthUrl - The URL is usually detected automatically, specify the URL if you need to overwrite the default, or the region of instance doesn't exists in registered regions listed in Region.
      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 iamAuthUrl, 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:
      iamAuthUrl - The URL is usually detected automatically, specify the URL if you need to overwrite the default, or the region of instance doesn't exists in registered regions listed in Region.
      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

    • createWithSessionToken

      public static SignatureProvider createWithSessionToken()
      Creates a SignatureProvider using a temporary session token read from a token file. The path of token file is read from the default profile in configuration file at the default location, the value of field security_token_file. The configuration file used is ~/.oci/config. See SDK Configuration File for details of the file's contents and format.

      See Session Token-Based Authentication for more details of session-token-based authentication.

      You can use the OCI CLI to authenticate and create a token, see See Token-based Authentication for the CLI.

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

      Returns:
      SignatureProvider

    • createWithSessionToken

      public static SignatureProvider createWithSessionToken(String profile)
      Creates a SignatureProvider using a temporary session token read from a token file. The path of token file is read from the specified profile in configuration file at the default location, the value of field security_token_file. The configuration file used is ~/.oci/config. See SDK Configuration File for details of the file's contents and format.

      See Session Token-Based Authentication for more details of session-token-based authentication.

      You can use the OCI CLI to authenticate and create a token, see Token-based Authentication for the CLI.

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

      Parameters:
      profile - profile name used to load session token
      Returns:
      SignatureProvider

    • createWithSessionToken

      public static SignatureProvider createWithSessionToken(String configFilePath, String profile)
      Creates a SignatureProvider using a temporary session token read from a token file. The path of token file is read from the specified profile in configuration file at the specified location, the value of field security_token_file. The configuration file used is ~/.oci/config. See SDK Configuration File for details of the file's contents and format.

      See Session Token-Based Authentication for more details of session-token-based authentication.

      You can use the OCI CLI to authenticate and create a token, see Token-based Authentication for the CLI.

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

      Parameters:
      configFilePath - path of configuration file
      profile - profile name used to load session token
      Returns:
      SignatureProvider

    • createWithOkeWorkloadIdentity

      public static SignatureProvider createWithOkeWorkloadIdentity()
      Creates a SignatureProvider with Container Engine for Kubernetes (OKE) workload identity using the Kubernetes service account token at the default path /var/run/secrets/kubernetes.io/serviceaccount/token. This provider can only be used inside Kubernetes pods.

      See Granting Workloads Access to OCI Resources for more details of OKE workload identity.

      Returns:
      SignatureProvider

    • createWithOkeWorkloadIdentity

      public static SignatureProvider createWithOkeWorkloadIdentity(String serviceAccountToken, Logger logger)
      Creates a SignatureProvider with Container Engine for Kubernetes (OKE) workload identity using specified Kubernetes service account token string. If token string is null, the provider will use the service account token at the default path /var/run/secrets/kubernetes.io/serviceaccount/token. This provider can only be used inside Kubernetes pods.

      See Granting Workloads Access to OCI Resources for more details of OKE workload identity.

      Parameters:
      serviceAccountToken - Kubernetes service account token string
      logger - the logger used by the SignatureProvider
      Returns:
      SignatureProvider

    • createWithOkeWorkloadIdentity

      public static SignatureProvider createWithOkeWorkloadIdentity(File serviceAccountTokenFile, Logger logger)
      Creates a SignatureProvider with Container Engine for Kubernetes (OKE) workload identity using Kubernetes service account token in the specified token file. If token file is null, the provider will use the service account token at the default path /var/run/secrets/kubernetes.io/serviceaccount/token. This provider can only be used inside Kubernetes pods.

      See Granting Workloads Access to OCI Resources for more details of OKE workload identity.

      Parameters:
      serviceAccountTokenFile - Kubernetes service account token file
      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, byte[] content)
      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
      content - the request content bytes

    • flushCache

      public void flushCache()
      Description copied from interface: AuthorizationProvider
      Invalidate any cached authorization strings.
      Specified by:
      flushCache in interface AuthorizationProvider

    • close

      public void close()
      Description copied from interface: AuthorizationProvider
      Release resources provider is using.
      Specified by:
      close in interface AuthorizationProvider

    • getRegion

      public Region getRegion()
      Returns region
      Specified by:
      getRegion in interface oracle.nosql.driver.Region.RegionProvider
      Returns:
      the Region to use for NoSQLHandle

    • forCloud

      public boolean forCloud()
      Description copied from interface: AuthorizationProvider
      Indicates whether or not the instance is used for the cloud service
      Specified by:
      forCloud in interface AuthorizationProvider
      Returns:
      false by default

    • 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.