Show / Hide Table of Contents

Oracle.NoSQL.SDK

Class IAMAuthorizationProvider

Authorization provider for the Oracle NoSQL Database Cloud Service.

Inheritance

Object

IAMAuthorizationProvider

Implements

IAuthorizationProvider

IDisposable

Namespace: Oracle.NoSQL.SDK

Assembly: Oracle.NoSQL.SDK.dll

Syntax

public class IAMAuthorizationProvider : Object, IAuthorizationProvider

Remarks

This provider class is used to authorize operations using Oracle Cloud Infrastructure Identity and Access Management (IAM). The instance of this class should be set as AuthorizationProvider in the initial configuration.

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 using one of the following:

Specific user's identity.
See the information below on what credentials are required and how to obtain them, as well how these credentials may be provided to IAMAuthorizationProvider.
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. The driver authenticates with the instance principal and obtains a security token issued by IAM to create the request signature. Use Instance Principal by setting UseInstancePrincipal to true or calling CreateWithInstancePrincipal(String) or CreateWithInstancePrincipalForDelegation.
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. The driver obtains a resource provider session token (RPST) that enables the resource such as function to authenticate itself. The RPST is used to create the request signature. Use Resource Principal by setting UseResourcePrincipal to true or calling CreateWithResourcePrincipal().
Oracle Container Engine for Kubernetes (OKE) workload identity.
You may use OKE workload identity when running an application inside Kubernetes cluster. For information on Container Engine for Kubernetes, see Overview of Container Engine for Kubernetes . Also see Granting Workloads Access to OCI Resources for more details on OKE workload identity. Use OKE workload identity by setting UseOKEWorkloadIdentity to true or calling CreateWithOKEWorkloadIdentity or CreateWithOKEWorkloadIdentityAndTokenFile(String). See UseOKEWorkloadIdentity for more information.
Session Token.
Session Token-Based Authentication 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 SDK Configuration File for details of the file's contents and format.
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 and region properties. The same considerations apply as described below when using OCI config file with specific user's identity.
You can use the OCI CLI to authenticate and create a session token (together with the profile in OCI config file that uses that session token), see Token-based Authentication for the CLI . Use Session Token by setting UseSessionToken to true or calling one of CreateWithSessionToken methods.

Note that when using Instance Principal, Resource Principal or OKE workload identity, you must specify the compartment id (OCID), either as Compartment or in the operation options. You must use compartment id (OCID) and not the compartment name. This also means that you may not prefix the table name with the compartment name when passing the table name to the NoSQLClient APIs or in queries. These restrictions do not apply when using the specific user identity, which is best for naming flexibility, allowing both compartment names and OCIDs.

The driver caches the request signature for a configurable duration CacheDuration with a maximum of 5 minutes. In addition, the driver can optionally renew the request signature in the background ahead of its expiration. The automatic renewal is controlled by RefreshAhead property.

The information that follows describes the steps to use the specific user identity and does not apply to using instance principal or resource principal.

To use the 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 for details. In particular, the 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.

To enable signing of API requests, perform the following steps:

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

Required Keys and OCIDs describes these steps in detail.

You may set the credentials using one of the following, in order of increasing security:

As IAMCredentials object set as Credentials or using IAMAuthorizationProvider(IAMCredentials) constructor. You must set the properties TenantId, UserId, Fingerprint and one of PrivateKey, PrivateKeyPEM or PrivateKeyFile. In addition, you must set Passphrase if the private key is encrypted.
As part of the OCI configuration file. See SDK and CLI Configuration File for information on the OCI configuration file format. Set properties ConfigFile and ProfileName or use IAMAuthorizationProvider(String, String) constructor. Because both of these properties have default values, the default instance of IAMAuthorizationProvider is configured to use credentials from the default OCI configuration file with the default profile name. In fact, the driver will create this default instance if you don't set AuthorizationProvider. Note that the driver will load the credentials from the OCI configuration file only once.
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 NoSQLConfig. 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 any arguments to the NoSQLClient constructor. See NoSQLClient(NoSQLConfig) for more information.
Specify your own credentials provider delegate as CredentialsProvider or use IAMAuthorizationProvider(Func<CancellationToken, Task<IAMCredentials>>) constructor. This is the most secure option because you can choose where the credentials are stored and how they are accessed. The credentials provider delegate will be called every time the credentials are needed (when the request signature is renewed).

The private key, if provided in a file or as a string, must be in PEM format. It can be either in PKCS#8 format (starts with -----BEGIN PRIVATE KEY----- or -----BEGIN ENCRYPTED PRIVATE KEY-----) or PKCS#1 format (starts with -----BEGIN RSA PRIVATE KEY-----). PKCS#8 format is preferred. There is a limitation for encrypted private keys in PKCS#1 format in that it must use AES encryption (with key sizes of 128, 192 or 256 bits). Otherwise, if you have an encrypted private key in PKCS#1 format, you can convert it to PKCS#8 using openssl:
openssl pkcs8 -topk8 -inform PEM -outform PEM -in encrypted_pkcs1_key.pem -out encrypted_pkcs8_key.pem

The examples show the ways to instantiate IAMAuthorizationProvider for different authorization scenarios outlined above.

Examples

Instantiating IAMAuthorizationProvider with specified credentials.

    var config = new NoSQLConfig
    {
    Region = Region.AP_SYDNEY_1,
    AuthorizationProvider = new IAMAuthorizationProvider(
        new IAMCredentials
        {
            TenantId = "ocid1.tenancy.oc...................",
            UserId = "ocid1.user.oc........................",
            Fingerprint = "aa:aa:aa:aa:....................",
            PrivateKeyFile = "~/my_app/security/oci_api_key.pem",
            Passphrase = "................................."
        }
    };

Specifying IAMAuthorizationProvider with specified credentials in JSON configuration file (note that storing the passphrase in the configuration file is not secure, use this for development/testing only).

{
    "Region": "ap-sydney-1",
    "AuthorizationProvider": {
        "AuthorizationType": "IAM",
        "Credentials": {
            "TenantId": "ocid1.tenancy.oc...................",
            "UserId": "ocid1.user.oc........................",
            "Fingerprint": "aa:aa:aa:aa:....................",
            "PrivateKeyFile": "~/my_app/security/oci_api_key.pem",
            "Passphrase": "................................."
        }
    }
}

Instantiating IAMAuthorizationProvider using the credentials in the OCI configuration file

    var config = new NoSQLConfig
    {
        Region = Region.AP_TOKYO_1,
        AuthorizationProvider = new IAMAuthorizationProvider(
            "~/my_app/.oci/config", "Jane")
    };

Specifying IAMAuthorizationProvider in JSON configuration file using the credentials in OCI configuration file.

{
    "Region": "ap-tokyo-1",
    "AuthorizationProvider": {
        "AuthorizationType": "IAM",
        "ConfigFile": "~/my_app/.oci/config",
        "ProfileName": "Jane"
    }
}

Instantiating IAMAuthorizationProvider using credentials supplied by the credentials provider delegate.

    ...
    public static async Task<IAMCredentials> LoadCredentialsAsync(
        CancellationToken cancellationToken)
    {
        // Load the credentials from a secure location.
        return new IAMCredentials
        {
            TenantId = "...",
            UserId = "...",
            ...
        };
    }
    ...
    var config = new NoSQLConfig
    {
        Region = Region.US_SANJOSE_1,
        AuthorizationProvider = new IAMAuthorizationProvider(
            LoadCredentialsAsync)
    };

Instantiating IAMAuthorizationProvider using instance principal.

    var config = new NoSQLConfig
    {
        Region = Region.SA_SAOPAULO_1,
        AuthorizationProvider =
            IAMAuthorizationProvider.CreateWithInstancePrincipal()
    };

Specifying IAMAuthorizationProvider using instance principal in JSON configuration file.

{
    "Region": "sa-saopaulo-1",
    "AuthorizationProvider": {
        "AuthorizationType": "IAM",
        "UseInstancePrincipal": true
}

Instantiating IAMAuthorizationProvider using instance principal with delegation token.

    // Obtain delegation token somehow.
    var delegationToken = GetDelegationToken();
    var config = new NoSQLConfig
    {
        Region = Region.SA_SAOPAULO_1,
        AuthorizationProvider =
            IAMAuthorizationProvider
                .CreateWithInstancePrincipalForDelegation(
                    delegationToken);
    };

Specifying IAMAuthorizationProvider using instance principal with delegation token in JSON configuration file (the delegation token is stored in a separate file "delegation_token_file").

{
    "Region": "sa-saopaulo-1",
    "AuthorizationProvider": {
        "AuthorizationType": "IAM",
        "UseInstancePrincipal": true,
        "DelegationTokenFile": "path/to/delegation_token_file"
    }
}

Instantiating IAMAuthorizationProvider using resource principal.

    var config = new NoSQLConfig
    {
        Region = Region.SA_SAOPAULO_1,
        AuthorizationProvider =
            IAMAuthorizationProvider.CreateWithResourcePrincipal()
    };

Specifying IAMAuthorizationProvider using resource principal in JSON configuration file.

{
    "Region": "sa-saopaulo-1",
    "AuthorizationProvider": {
        "AuthorizationType": "IAM",
        "UseResourcePrincipal": true
    }
}

Instantiating IAMAuthorizationProvider using OKE workload identity.

    var config = new NoSQLConfig
    {
        Region = Region.AP_MUMBAI_1,
        AuthorizationProvider =	IAMAuthorizationProvider
            .CreateWithOKEWorkloadIdentity()
    };

Specifying IAMAuthorizationProvider using OKE workload identity in JSON configuration file.

    {
        "Region": "sa-saopaulo-1",
        "AuthorizationProvider": {
            "AuthorizationType": "IAM",
            "UseOKEWorkloadIdentity": true
        }
    }

Instantiating IAMAuthorizationProvider using OKE workload identity and provided service account token.

    // Obtain service account token somehow.
    var serviceAccountToken = GetServiceAccountToken();
    var config = new NoSQLConfig
    {
        Region = Region.AP_MUMBAI_1,
        AuthorizationProvider =	IAMAuthorizationProvider
            .CreateWithOKEWorkloadIdentity(serviceAccountToken)
    };

Specifying IAMAuthorizationProvider using OKE workload identity with provided service account token in JSON configuration file (service account token is stored in a separate file "service_account_token_file").

    {
        "Region": "sa-saopaulo-1",
        "AuthorizationProvider": {
            "AuthorizationType": "IAM",
            "UseOKEWorkloadIdentity": true,
            "ServiceAccountTokenFile": "path/to/service_account_token_file"
        }
    }

Instantiating IAMAuthorizationProvider using session token.

    var config = new NoSQLConfig
    {
        Region = Region.AP_SYDNEY_1,
        AuthorizationProvider =
            IAMAuthorizationProvider.CreateWithSessionToken(
                "~/my_app/.oci/config", "Jane")
    };

Specifying IAMAuthorizationProvider using session token in JSON configuration file.

{
    "Region": "ap-sydney-1",
    "AuthorizationProvider": {
        "AuthorizationType": "IAM",
        "UseSessionToken": true,
        "ConfigFile": "~/my_app/.oci/config",
        "ProfileName": "Jane"
    }
}

Constructors

Name	Description
IAMAuthorizationProvider()	Initializes a new instance of IAMAuthorizationProvider with default configuration.
IAMAuthorizationProvider(IAMCredentials)	Initializes a new instance of IAMAuthorizationProvider with the specified credentials.
IAMAuthorizationProvider(Func<CancellationToken, Task<IAMCredentials>>)	Initializes a new instance of IAMAuthorizationProvider using specified credentials provider delegate.
IAMAuthorizationProvider(String)	Initializes a new instance of IAMAuthorizationProvider using the default OCI configuration file and the specified profile name.
IAMAuthorizationProvider(String, String)	Initializes a new instance of IAMAuthorizationProvider using specified OCI configuration file and profile name.

Properties

Name	Description
CacheDuration	Gets or sets the duration of the request signature in the cache.
ConfigFile	Gets or sets the path of the OCI configuration file.
Credentials	Gets or sets the credentials for the specific user identity.
CredentialsProvider	Gets or sets the credentials provider delegate.
DelegationTokenFile	Gets or sets the delegation token file path.
DelegationTokenProvider	Gets or sets the delegation token provider delegate.
FederationEndpoint	Gets or sets the federation endpoint for use with instance principal.
ProfileName	Gets or sets the profile name in the OCI configuration file.
RefreshAhead	Gets or sets the value indicating when to automatically refresh the request signature before its expiration.
RequestTimeout	Gets or sets the timeout for requests made to the authorization service.
ServiceAccountTokenFile	Gets or sets the service account token file path.
UseInstancePrincipal	Gets or sets the value that determines whether to use an instance principal.
UseOKEWorkloadIdentity	Gets or sets a value that determines whether to use authorization for Oracle Container Engine for Kubernetes (OKE) workload identity. This authorization can only be used inside Kubernetes pods.
UseResourcePrincipal	Gets or sets the value that determines whether to use a resource principal.
UseSessionToken	Gets or sets the value that determines whether to use a session token.

Methods

Name	Description
ApplyAuthorizationAsync(Request, HttpRequestMessage, CancellationToken)	Obtains and adds the required HTTP headers for authorization with IAM.
ConfigureAuthorization(NoSQLConfig)	Validates and configures the authorization provider.
CreateWithInstancePrincipal(String)	Creates a new instance of IAMAuthorizationProvider using the instance principal.
CreateWithInstancePrincipalForDelegation(Func<CancellationToken, Task<String>>, String)	Creates a new instance of IAMAuthorizationProvider using an instance principal with a delegation token using the specified delegation token provider delegate.
CreateWithInstancePrincipalForDelegation(String, String)	Creates a new instance of IAMAuthorizationProvider using an instance principal with a delegation token.
CreateWithInstancePrincipalForDelegationFromFile(String, String)	Creates a new instance of IAMAuthorizationProvider using an instance principal with a delegation token using the specified delegation file.
CreateWithOKEWorkloadIdentity(Func<CancellationToken, Task<String>>)	Creates a new instance of IAMAuthorizationProvider using OKE workload identity and specified service account token provider delegate.
CreateWithOKEWorkloadIdentity(String)	Creates a new instance of IAMAuthorizationProvider using OKE workload identity.
CreateWithOKEWorkloadIdentityAndTokenFile(String)	Creates a new instance of IAMAuthorizationProvider using OKE workload identity and specified service account token file.
CreateWithResourcePrincipal()	Creates a new instance of IAMAuthorizationProvider using the resource principal.
CreateWithSessionToken()	Creates a new instance of IAMAuthorizationProvider using session token-based authentication with the default OCI configuration file and the default profile name.
CreateWithSessionToken(String)	Creates a new instance of IAMAuthorizationProvider using session token-based authentication with the default OCI configuration file and the specified profile name.
CreateWithSessionToken(String, String)	Creates a new instance of IAMAuthorizationProvider using session token-based authentication with the specified OCI configuration file and profile name.
Dispose()	Releases resources used by this IAMAuthorizationProvider instance.
Dispose(Boolean)	Releases the unmanaged resources used by this instance and optionally releases the managed resources.