Interface IAMConfig

IAMConfig is required to authorize operations using Oracle Cloud Infrastructure Identity and Access Management (IAM). It should be set as iam.

See Overview of Oracle Cloud Infrastructure Identity and Access Management for information on IAM components and how they work together to provide security for Oracle Cloud services.

All operations require a request signature that is used by the system to authorize the operation. The request signature may be created in one of the following ways:

1. Using specific user's indentity. See information below on what credentials are required and how to obtain them, as well as the ways these credentials may be provided to the driver via IAMConfig.
2. Using Instance Principal. You may use Instance Principal when calling Oracle NoSQL Database Cloud Service from a compute instance in the Oracle Cloud Infrastructure (OCI). See Calling Services from an Instance for more information. Use Instance Principal by setting useInstancePrincipal property to true.
3. Using Resource Principal. You may use Resource Principal when calling Oracle NoSQL Database Cloud Service from other Oracle Cloud service resource such as Functions. See Accessing Other Oracle Cloud Infrastructure Resources from Running Functions for more information. Use Resouce Principal by setting useResourcePrincipal property to true.
4. Using Oracle Container Engine for Kubernetes (OKE) workload identity. You may use OKE workload identity when running an application inside Kubernetes cluster. For more information, see Overview of Container Engine for Kubernetes and Granting Workloads Access to OCI Resources.
5. Using session-token based authentication. This method uses temporary session token read from a token file. The path to the token file and other required credentials are stored in OCI configuration file. For more information see SDK Configuration File and Token-based Authentication for the CLI.

When using specific user's identity, if you don't specify compartment, a default compartment will be used, which is a a root compartment of the user's tenancy. You can also specify compartment, either as compartment property of initial configuration or as part of options for each request. You may specify either compartment OCID or compartment name. If using compartment name, you can also provide it as a prefix to the table name as in compartmentName.tableName.

When using Instance Principal, Resource Principal or OKE workload identity, there is no default compartment, so you must specify compartiment id (OCID), either as compartment property of the initial configuration or as part of options for each request. Note that you must use compartment id (OCID) and not compartment name. This also means that you may not prefix table name with compartment name when calling methods of NoSQLClient. The only exception to this is when using Resource Principal together with useResourcePrincipalCompartment property, in which case the resource compartment itself will be used.

To use specific user's identity, you must provide the following credentials:

• Tenancy OCID. This is Oracle Cloud ID (OCID) for your tenancy. See Resource Identifiers for information on OCIDs.
• User's OCID. This is Oracle Cloud ID (OCID) for the user in your tenancy. See Resource Identifiers for information on OCIDs.
• API Signing Key. This is public-private key pair used to sign the API requests, see Required Keys and OCIDs. In particular, private key is needed to generate the request signature.
• Public Key Fingerprint. This is an identifier of the public key of the API Signing Key pair.
• Passphrase for the private key of API Signing Key pair if the private key is encrypted.

See Required Keys and OCIDs for detailed description of the above credentials and the steps you need to perform to enable signing of API requests, which are:

• Generate the key pair described above.
• Upload public key.
• Obtain tenancy and user OCIDs and public key fingerprint.

You may provide these credentials in one of the following ways, in order of increased security:

• Directly as properties of IAMConfig. In this case, set properties tenantId, userId, privateKey or privateKeyFile, fingerprint and passphrase (if private key is encrypted)
• As part of an OCI configuration file. See SDK and CLI Configuration File for information on OCI configuration file and what entries are used for the required credentials. In this case, you may set properties configFile and/or profileName. If not set, appropriate default values will be used, see property descriptions.
• Specify your own credentials provider in the form of IAMCredentialsProvider. This allows you to store and retrieve credentials in a secure manner. In this case, specify credentialsProvider property.

Note that the private key must be in PEM format. You may provide a path to the PEM key file. Alternatively, except when using OCI configuration file, you may provide PEM encoded private key directly as Buffer or string. Note that the passphrase must be provided if the private key is encrypted.

The driver will determine the method of authorization as follows:

1. If useResourcePrincipal is set to true, then Resource Principal authentication will be used.
2. If useInstancePrincipal is set to true, then Instance Principal authentication will be used. You may also set federationEndpoint, although it is not requred and in most cases federation endpoint will be auto-detected.
3. If useOKEWorkloadIdentity is set to true, then Container Engine for Kubernetes (OKE) authentication will be used. Optionally, you may also provide service account token by setting one of 3 properties serviceAccountToken, serviceAccountTokenFile or serviceAccountTokenProvider.
4. If useSessionToken is set to true, then session token-based authentication will be used. Note that this method uses OCI config file, so settings to properties configFile and profileName also apply. See useSessionToken for more information.
5. If IAMConfig has any of user identity properties such as tenantId, userId, privateKey, fingerprint or passphrase, the driver assumes that you are using a specific user's identity and that the credentials are provided directly in IAMConfig. All required user's credentials, as described above, must be present as properties of IAMConfig, otherwise NoSQLArgumentError will result.
6. If IAMConfig has credentialsProvider property, the driver assumes that you are using a specific user's identity and the credentials are obtained through the credentials provider which must be in the form of IAMCredentialsProvider. In this case the credentials must not be set directly in IAMConfig.
7. If none of the above, the driver assumes that you are using a specific user's identity and the credentials are stored in OCI config file and will use configFile and profileName properties if present, otherwise it will assume their default values. In particular, if you specify serviceType as CLOUD and omit auth alltogether, the driver will use IAM authorization with default OCI config file and default profile name.

Note that if using an OCI configuration file, you may also specify region identifier in the same profile as your credentials. In this case, you need not specify either region or endpoint in Config. In particular, if you use the default OCI config file (~/.oci/config) and default profile name (DEFAULT) and do not need to customize any other configuration properties, you may create NoSQLClient instance without providing configuration to NoSQLClient constructor. See NoSQLClient for more information.

If using Resource Principal, you also need not specify either region or endpoint in Config, as Resource Principal's region will be used. In fact, when running in Functions service, you may only access NoSQL service in the same region as the running function, so when using Resource Principal, it is preferable not to specify either region or endpoint in Config.

Generated authorization signature is valid for a period of time and is cached for effeciency. The caching behavior may be customized with properties durationSeconds and refreshAheadMs. See their property descriptions for details.

See

• AuthConfig
• IAMAuthorizationProvider
• IAMCredentials
• IAMCredentialsProvider
• Connecting an Application to Oracle NoSQL Database Cloud Service

Example

JSON Config object supplying user's credentials directly (sensitiveinfo not shown).

{
    "region": "us-phoenix-1",
    "auth": {
        "iam": {
            "tenantId": "ocid1.tenancy.oc...................",
            "userId": "ocid1.user.oc.....................",
            "fingerprint": "aa:aa:aa:aa:.....",
            "privateKeyFile": "~/myapp/security/oci_api_key.pem",
            "passphrase": "..............."
        }
    }
}

Example

JSON Config object supplying user's credentials through OCI configuration file.

{
    "region": "us-phoenix-1",
    "auth": {
        "iam": {
            "configFile": "~/myapp/.oci/config",
            "profileName": "John"
        }
    }
}

Example

Javascript Config object supplying user's credentials via custom credentials provider.

{
    region: "us-phoenix-1",
    auth: {
        iam: {
            credentialsProvider: async () => {
                .......... //retrieve credentials somehow
                ..........
                return {
                    tenantId: myTenantId,
                    userId: myUserId,
                    fingerprint: myFingerprint,
                    privateKey: myPrivateKey,
                    passphrase: myPassphrase
                };
            }
        }
    }
}

Example

JSON Config object using Instance Principal.

{
    "region": "us-phoenix-1",
    "compartment": "ocid1.compartment.oc1.............................",
    "auth": {
        "iam": {
            "useInstancePrincipal": "true"
        }
    }
}

Example

Javascript Config object when using Resource Principal

{
    compartment: "ocid1.compartment.oc1.............................",
    auth: {
        iam: {
            useResourcePrincipal: true
        }
    }
}

Example

Javascript Config object when using Resource Principal with useResourcePrincipalCompartment property.

{
    auth: {
        iam: {
            useResourcePrincipal: true,
            useResourcePrincipalCompartment: true
        }
    }
}

Example

Javascript Config object when using OKE workload identity.

{
    compartment: "ocid1.compartment.oc1.............................",
    auth: {
        iam: {
            useOKEWorkloadIdentity: true
        }
    }
}

Example

JSON Config object when using OKE workload identity and supplying the location of service account token.

{
    "compartment": "ocid1.compartment.oc1.............................",
    "auth": {
        "iam": {
            "useOKEWorkloadIdentity": true,
            "serviceAccountTokenFile": "~/myapp/serviceaccount/token"
        }
    }
}

Example

JSON Config object when using session token-based authentication.

{
    "region": "us-phoenix-1",
    "compartment": "ocid1.compartment.oc1.............................",
    "auth": {
        "iam": {
            "useSessionToken": true,
            "configFile": "~/myapp/.oci/config",
            "profileName": "John"
        }
    }
}