8.3.2.1 Prerequisites for Using the OCI Object Storage JSON File

Perform these steps in the Oracle Cloud Infrastructure (OCI) console or using the OCI CLI or API, before beginning to use the OCI Object Storage.

• Create a bucket in the OCI Object Storage:

  Use the OCI Object Storage service to create a bucket within a compartment of your Object Storage namespace. You will later upload a Centralized Configuration Provider JSON file as an object to this bucket.

• Create a policy and assign it to database user:

  The OCI administrator must grant security access in a policy. Create an OCI Identity and Access Management (IAM) policy, and assign it to database user for accessing Object Storage resources in the compartment.

• (Optional) Create a vault for secrets and grant authorization permissions:

  You can store Oracle Database credentials and Oracle wallet data in OCI Vault or Azure Key Vault.

  • To store Oracle Database credentials:

    Create OCI Vault or Azure Key Vault with the database password stored as a secret in that vault.

  • To store Oracle wallet data:

    The SQLNET client applications running on multitenant cloud service environments can store wallets in remote stores. Because these applications may not have access to the wallets stored in a local system file, this feature is especially useful for Mutual Transport Layer Security (mTLS) connections that require file system access to keep the wallet.

    To store wallet data, you first convert an auto-login wallet file (cwallet.sso) to a Base64 format, and then create OCI Vault or Azure Key Vault with the Base64-formatted cwallet.sso value stored as a secret.

    1. Convert your cwallet.sso file to a Base64 format.

       A common way to convert cwallet.sso to Base64 is by using the following openssl command on Linux:

       cat cwallet.sso | base64 -w 0 > file_to_upload

       Here, file_to_upload specifies the cwallet.sso file that you want to convert.

    2. Create OCI Vault or Azure Key Vault by pasting contents of the Base64-formatted string of the cwallet.sso file, as secret contents without any new lines.

  You will later add a reference to these vaults in the JSON file. The OCI administrator must give authorization permissions to the database user for accessing the OCI Vault. Similarly, the Azure App Configuration store's administrator must give authorization permissions to the registered OAuth application for accessing the Azure Key Vault.

  For detailed information on how to perform these steps, see OCI Vault Documentation or Azure Key Vault Documentation.

• Understand the format of a Centralized Configuration Provider JSON file:

  You can organize connect descriptors in a Centralized Configuration Provider JSON file based on your application requirements, in one of the following JSON formats:

  • A single object with a connect_descriptor sub-object

  • Multiple objects (separated by a comma) with each object having its own connect_descriptor sub-object

  Optionally, you can add user and password sub-objects (to specify the database user name and database password), wallet_location sub-object (to specify the wallet directory), and oci sub-object (to specify Oracle Call Interface configuration parameters) in the same file.

  Database clients look for specific network service names in a JSON object for deriving the connect descriptor, database user name and password, wallet data, and other Oracle Call Interface attributes. A connect identifier retrieves these JSON objects from the OCI Object Storage endpoint and uses it to locate the stored attributes. These values are used for the database connection.

  The syntax for Centralized Configuration Provider JSON (CCJSON) is:

  Centralized Configuration Provider JSON -> CCJSON_elements
  
  CCJSON_elements       -> CCJSON_elment
                        -> CCJSON_element, CCJSON_element
  
  CCJSON_element        -> '{' members '}'
  
  members               -> member
                        -> member, member
  
  member                -> cd
                        -> member, cd_related
  
  cd                    -> "connect_descriptor" : "<connect_descriptor>"
  
  cd_related            -> "user" : "<database user name>"
                        -> "password" : '{' password_data '}'
                        -> "wallet_location" : '{' wallet_data '}'
                        -> "oci" : '{' oci_config_members '}'
                        -> nul
  
  password_data         -> '{' "type" : vault_type, 
                               "value" : vault_value, 
                               "authentication": authentication_value '}'
  
  wallet_data           -> '{' "type" : vault_type,  
                               "value" : vault_value, 
                               "authentication": authentication_value '}'
  
  vault_type            -> "ocivault"
                        -> "azurevault"
  
  vault_value           -> "<vault-specific identifier>"    
  
  authentication_value  -> '{' "azure_client_id" : "<client id>", 
                               "azure_client_secret" : "<secret>",
                               "azure_tenant_id" : "<tenant id>" '}'          
                        -> null
  
  oci_config_members    -> '{' oci_config_name : oci_config_value '}'
  
  oci_config_value      -> json_value
  
  oci_config_name       -> prefetch_rows
                        -> statement_cache_size
                        -> lob_prefetch_size 
                        -> session_pool
  
  session_pool          -> '{' "min" : value, "max" : value, 
                               "increment" : value, "max_lifetime_session" : value, 
                               "max_use_session" : value, "inactivity_timeout" : value '}'
  
  prefetch_rows         -> "prefetch_rows" : numeric_value
  
  statement_cache_size  -> "statement_cache_size" : numeric_value
  
  lob_prefetch_size     -> "lob_prefetch_size" : numeric_value
  
  numeric_value         -> "<number>"

  You will see how to create a JSON file with these values in the sections that follow.