Package oracle.nosql.driver.iam

Class SignatureProvider

  • All Implemented Interfaces:
    AuthorizationProvider, Region.RegionProvider
    public class SignatureProvider
extends java.lang.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 two 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.

    The latter can be simpler to use when running on an OCI compute instance, but limits 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 several options to provide the required information:

    • Constructor Detail

      • SignatureProvider

        public SignatureProvider()
                  throws java.io.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.
        Throws:
        java.io.IOException - if error loading profile from OCI configuration file

      • SignatureProvider

        public SignatureProvider​(java.lang.String profileName)
                  throws java.io.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
        Parameters:
        profileName - user profile name
        Throws:
        java.io.IOException - if error loading profile from OCI configuration file

      • SignatureProvider

        public SignatureProvider​(java.lang.String configFile,
                         java.lang.String profileName)
                  throws java.io.IOException
        Creates a SignatureProvider using the specified config file and profile. See SDK Configuration File for details of the file's contents and format
        Parameters:
        configFile - path of configuration file
        profileName - user profile name
        Throws:
        java.io.IOException - if error loading profile from OCI configuration file

      • SignatureProvider

        public SignatureProvider​(java.lang.String tenantId,
                         java.lang.String userId,
                         java.lang.String fingerprint,
                         java.lang.String privateKey,
                         char[] passphrase)
        Creates a SignatureProvider using directly provided user authentication information. See Required Keys and OCIDs for details of the required parameters.
        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​(java.lang.String tenantId,
                         java.lang.String userId,
                         java.lang.String fingerprint,
                         java.io.File privateKeyFile,
                         char[] passphrase)
        Creates a SignatureProvider using directly provided user authentication information. See Required Keys and OCIDs for details of the required parameters.
        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​(java.lang.String tenantId,
                         java.lang.String userId,
                         java.lang.String fingerprint,
                         java.io.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.
        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​(java.lang.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​(java.lang.String iamAuthUri,
                                                            Region region,
                                                            java.util.logging.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​(java.lang.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 - this token 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​(java.lang.String iamAuthUri,
                                                                         Region region,
                                                                         java.lang.String delegationToken,
                                                                         java.util.logging.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 - this token 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

      • 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​(java.util.logging.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 java.lang.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​(java.lang.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

      • setLogger

        public void setLogger​(java.util.logging.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 java.util.logging.Logger getLogger()
        Returns the logger of this provider if set, null if not.
        Returns:
        logger

      • getResourcePrincipalClaim

        public java.lang.String getResourcePrincipalClaim​(java.lang.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.