* When returning this object, you have choices to return privateKey * or privateKeyFile and to return {@link !Buffer | Buffer} or * string for fields indicated as such. * * @see {@link IAMConfig} * @see {@link IAMCredentialsProvider} */ export interface IAMCredentials { /** * Tenancy OCID. */ tenantId: string; /** * User OCID. */ userId: string; /** * Public key fingerprint. */ fingerprint: string; /** * PEM-encoded private key data. If specified as {@link !Buffer | Buffer}, * you may clear the buffer contents afer {@link NoSQLClient} instance is * created for added security. Note that only one of {@link privateKey} * or {@link privateKeyFile} properties may be specified. */ privateKey?: string|Buffer; /** * Path to PEM private key file. Path may be absolute or relative to * current directory. May be string or UTF-8 encoded * {@link !Buffer | Buffer}. Note that only one of {@link privateKey} or * {@link privateKeyFile} properties may be specified. */ privateKeyFile?: string|Buffer; /** * Passphrase for the private key if it is encrypted. If specified as * {@link !Buffer | Buffer}, you may clear the buffer contents after * {@link NoSQLClient} instance is created for added security. */ passphrase?: Buffer|string; } /** * {@link IAMConfig} is required to authorize operations using Oracle Cloud * Infrastructure Identity and Access Management (IAM). It should be set as * {@link AuthConfig#iam}. *
* See {@link https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/overview.htm | 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: *
* 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 * {@link Config#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 {@link Config#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 * {@link NoSQLClient}. * The only exception to this is when using Resource Principal together with * {@link useResourcePrincipalCompartment} property, in which case the * resource compartment itself will be used. *
* To use specific user's identity, you must provide the following credentials: *
* See {@link https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm | 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: *
* You may provide these credentials in one of the following ways, in order of * increased security: *
*
* The driver will determine the method of authorization as follows: *
* 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 {@link 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 {@link NoSQLClient} instance * without providing configuration to {@link NoSQLClient} constructor. * See {@link NoSQLClient} for more information. *
* If using Resource Principal, you also need not specify either region or * endpoint in {@link 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 * {@link Config}. *
* Generated authorization signature is valid for a period of time and is
* cached for effeciency. The caching behavior may be customized with
* properties {@link IAMConfig#durationSeconds} and
* {@link IAMConfig#refreshAheadMs}. See their property descriptions for
* details.
*
* @see {@link AuthConfig}
* @see {@link IAMAuthorizationProvider}
* @see {@link IAMCredentials}
* @see {@link IAMCredentialsProvider}
* @see {@page connect-cloud.md}
*
* @example
* JSON {@link Config} object supplying user's credentials directly
* (sensitiveinfo not shown).
* ```json
* {
* "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 {@link Config} object supplying user's credentials through OCI
* configuration file.
* ```json
* {
* "region": "us-phoenix-1",
* "auth": {
* "iam": {
* "configFile": "~/myapp/.oci/config",
* "profileName": "John"
* }
* }
* }
* ```
*
* @example
* Javascript {@link Config} object supplying user's credentials via custom
* credentials provider.
* ```js
* {
* region: "us-phoenix-1",
* auth: {
* iam: {
* credentialsProvider: async () => {
* .......... //retrieve credentials somehow
* ..........
* return {
* tenantId: myTenantId,
* userId: myUserId,
* fingerprint: myFingerprint,
* privateKey: myPrivateKey,
* passphrase: myPassphrase
* };
* }
* }
* }
* }
* ```
*
* @example
* JSON {@link Config} object using Instance Principal.
* ```json
* {
* "region": "us-phoenix-1",
* "compartment": "ocid1.compartment.oc1.............................",
* "auth": {
* "iam": {
* "useInstancePrincipal": "true"
* }
* }
* }
* ```
*
* @example
* Javascript {@link Config} object when using Resource Principal
* ```js
* {
* compartment: "ocid1.compartment.oc1.............................",
* auth: {
* iam: {
* useResourcePrincipal: true
* }
* }
* }
* ```
*
* @example
* Javascript {@link Config} object when using Resource Principal with
* {@link useResourcePrincipalCompartment} property.
* ```js
* {
* auth: {
* iam: {
* useResourcePrincipal: true,
* useResourcePrincipalCompartment: true
* }
* }
* }
* ```
*
* @example
* Javascript {@link Config} object when using OKE workload identity.
* ```js
* {
* compartment: "ocid1.compartment.oc1.............................",
* auth: {
* iam: {
* useOKEWorkloadIdentity: true
* }
* }
* }
* ```
*
* @example
* JSON {@link Config} object when using OKE workload identity and supplying
* the location of service account token.
* ```js
* {
* "compartment": "ocid1.compartment.oc1.............................",
* "auth": {
* "iam": {
* "useOKEWorkloadIdentity": true,
* "serviceAccountTokenFile": "~/myapp/serviceaccount/token"
* }
* }
* }
* ```
*
* @example
* JSON {@link Config} object when using session token-based authentication.
* ```json
* {
* "region": "us-phoenix-1",
* "compartment": "ocid1.compartment.oc1.............................",
* "auth": {
* "iam": {
* "useSessionToken": true,
* "configFile": "~/myapp/.oci/config",
* "profileName": "John"
* }
* }
* }
* ```
*/
export interface IAMConfig extends Partial
* For information on Container Engine for Kubernetes, see
* {@link https://docs.oracle.com/en-us/iaas/Content/ContEng/Concepts/contengoverview.htm | Overview of Container Engine for Kubernetes}.
* Also see
* {@link https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm | Granting Workloads Access to OCI Resources}
* for more details on OKE workload identity.
*
* This property may not be combined with {@link useInstancePrincipal},
* {@link useResourcePrincipal}, {@link useSessionToken} or any properties
* used for specific user's identity.
*
* Using OKE workload identity requires service account token. By default,
* the provider will load service account token from the default file path
* /var/run/secrets/kubernetes.io/serviceaccount/token. You may
* override this and provide your own service account token by specifying
* one of 3 properties:
*
* Because this method uses OCI Configuration File, you may use the
* properties {@link configFile} and {@link profileName} to specify the
* path to the configuration file and the profile name within the
* configuration file. The same defaults apply.
*
* For session token-based authentication, the properties required in the
* OCI config file by the driver are tenancy for tenant OCID,
* security_token_file for security token file and
* key_file for private key file.
* You may also specify pass_phrase property for private key
* passphrase as well as region property (instead of specifying
* {@link Config#region} property in the {@link Config} as previously
* described).
*
* You can use the OCI CLI to authenticate and create a token, see
* {@link https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm" | Token-based Authentication for the CLI}.
*
*/
useSessionToken?: boolean;
/**
* OCI configuration file path. May be absolute or relative to current
* directory. May be string or UTF-8 encoded
* {@link !Buffer | Buffer}.
* @defaultValue Path "\~/.oci/config", where "\~" represents user's home
* directory on Unix systems and %USERPROFILE% directory on Windows
* (see USERPROFILE environment variable).
*/
configFile?: string|Buffer;
/**
* Profile name within the OCI configuration file, used only if
* credentials are obtained from the configuration file as described.
* @defaultValue If not set, the name "DEFAULT" is used.
*/
profileName?: string;
/**
* Custom credentials provider to use to obtain credentials in the form of
* {@link IAMCredentials}. You may also specify string for a module name
* or path that exports {@link IAMCredentialsProvider}.
* @see {@link IAMCredentialsProvider}
*/
credentialsProvider?: IAMCredentialsProvider |
IAMCredentialsProvider["loadCredentials"] | string;
/**
* Cache duration of the signature in seconds. Specifies how long cached
* signature may be used before new one has to be created. Maximum allowed
* duration is 5 minutes (300 seconds), which is also the default.
* @defaultValue 300 (5 minutes)
*/
durationSeconds?: number;
/**
* Tells the driver when to automatically refresh the signature before its
* expiration in the cache, measured in number of milliseconds before
* expiration. E.g. value 10000 means that the driver will attempt to
* refresh the signature 10 seconds before its expiration. Using refresh
* allows to avoid slowing down of database operations by creating the
* signature asynchronously. You can set this property to null
* to disable automatic refresh.
* @defaultValue 10000 (10 seconds)
*/
refreshAheadMs?: number|null;
/**
* Timeout in milliseconds used for requests to the authorization server.
* Currently this is only used with Instance Principal and OKE workload
* identity.
* @defaultValue 120000 (2 minutes)
*/
timeout?: number;
}
/**
* You may implement {@link IAMCredentialsProvider} interface to securely
* obtain credentials required for generation of OCI request signature, as
* described in {@link IAMConfig}. {@link IAMCredentialsProvider} is
* set as {@link IAMConfig#credentialsProvider} property of {@link IAMConfig}.
* Instead of a class implementing this interface, you may also set
* {@link IAMConfig#credentialsProvider} to function with the signature of
* {@link loadCredentials}.
* @see {@link IAMCredentials}
* @see {@link IAMConfig}
* @see {@page connect-cloud.md}
*/
export interface IAMCredentialsProvider {
/**
* Asynchronously load credentials required for generating OCI request
* signature.
* @async
* @returns {Promise} Promise resolved with {@link IAMCredentials} or
* rejected with an error. Properties of type {@link !Buffer | Buffer}
* such as {@link IAMCredentials#privateKey} or
* {@link IAMCredentials#passphrase} will be erased once the signature is
* generated.
*/
loadCredentials(): Promise
*
*/
useOKEWorkloadIdentity?: boolean;
/**
* Used only with OKE workload identity
* (see {@link useOKEWorkloadIdentity}). Use this property to provide
* service account token string. This property is exclusive with
* {@link serviceAccountTokenFile} and
* {@link serviceAccountTokenProvider}.
* @see {@link useOKEWorkloadIdentity}
*/
serviceAccountToken?: string;
/**
* Used only with OKE workload identity
* (see {@link useOKEWorkloadIdentity}). Use this property to provide
* a path to service account token file. Service account token will be
* reloaded from this file when refreshing OKE security token. This
* property is exclusive with {@link serviceAccountToken} and
* {@link serviceAccountTokenProvider}.
* @see {@link useOKEWorkloadIdentity}
*/
serviceAccountTokenFile?: string;
/**
* Used only with OKE workload identity
* (see {@link useOKEWorkloadIdentity}). This propertiy specifies
* {@link ServiceAccountTokenProvider} as a custom provider used to load
* the service account token. Service account token will be
* reloaded when refreshing OKE security token. This property is exclusive
* with {@link serviceAccountToken} and {@link serviceAccountTokenFile}.
* @see {@link useOKEWorkloadIdentity}
*/
serviceAccountTokenProvider?: ServiceAccountTokenProvider |
ServiceAccountTokenProvider["loadServiceAccountToken"];
/**
* If set to true,
* {@link https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm#sdk_authentication_methods_session_token | Session Token-Based Authentication}
* will be used. This method uses temporary session token read from a
* token file. The path of the token file is read from a profile in OCI
* configuration file as the value of field security_token_file.
* See
* {@link https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm | SDK Configuration File} for details of the file's contents and format. In
* addition, see the description of {@link IAMConfig} above.
*