Review the list of limitations in managing PDBs.

• Oracle recommends using the Console or API-based tools (including the OCI CLI, SDKs, and Terraform) to create and manage PDBs. However, there would be periodic sync of the PDBs created through DBAASCLI and SQL*Plus.
• PDB management using the OCI Console and API is available only for Oracle Database versions 19c and later.
• PDBs are backed up at the CDB level, and each backup includes all the PDBs in the database. OCI Control Plane does not support the creation of backups for individual PDBs. However, bkup_api supports PDB backup operations. For more information, see Configuring and Customizing Backups with bkup_api.
  Examples:

  • List backups:

    /var/opt/oracle/bkup_api/bkup_api list --dbname psarch

  • Create initial PDB backup manually:

    /var/opt/oracle/bkup_api/bkup_api bkup_start --level1 --dbname psarch --pdb NEWPDBA

• Restore operations are performed at the CDB level. OCI Control Plane does not support restoring individual PDBs. However, bkup_api supports PDB restore operations.
  Examples:

  • Recover a PDB with least or no data loss possible:

    /var/opt/oracle/bkup_api/bkup_api recover_start --latest --dbname psarch --pdb NEWPDBA

  • Recover a PDB back to a point in time:

    /var/opt/oracle/bkup_api/bkup_api recover_start -t '17-AUG2021 21:15:00' --dbname psarch --pdb NEWPDBA

  • Recover until SCN:

    /var/opt/oracle/bkup_api/bkup_api recover_start -scn 138935800 -pdb=NEWPDBA -uuid=fec6579e077211ec8b0a00102ee75632 -bname=psarch

You can create a PDB from the OCI Console, or with the pluggable database APIs.

• Using the Console to Create a Pluggable Database
  To create a pluggable database with the console, use this procedure.
• Using the Console to Relocate a Pluggable Database
  To relocate a pluggable database with the console, use this procedure.
• Using the API to Create a Pluggable Database
  Use various API features to help create your pluggable databases on Oracle Exadata Database Service on Cloud@Customer.

To start, stop, clone, and delete a PDB, use these procedures.

• Using the Console to Start a Pluggable Database
  The PDB must be available and stopped to use this procedure.
• Using the Console to Stop a Pluggable Database
  The PDB must be available and running (started) to use this procedure.
• Using the Console to Delete a Pluggable Database
  The PDB must be available and stopped to use this procedure.
• Using the Console to Get Connection Strings for a Pluggable Database
  Learn how to get connection strings for the administrative service of a PDB. Oracle recommends connecting applications to an application service using the strings created for the application service.
• Clone a Pluggable Database (PDB)
  A clone is an independent and complete copy of the given database as it existed at the time of the cloning operation. You can create clones of your PDB within the same CDB or a different CDB and also refresh the cloned PDB.
• Restore a Pluggable Database (PDB)
  You can restore a PDB within the same CDB to last known good state and specified timestamp.
• Using the API to Manage Pluggable Databases
  Use various API features to help manage your pluggable databases on Oracle Exadata Database Service on Cloud@Customer.
• Using the API to Clone a Pluggable Database
  Clone a pluggable database (PDB) in the same database (CDB) as the source PDB or to a different database from the source PDB.

Follow the steps below to view the attributed costs based on CPU utilization for all pluggable databases within a VM Cluster.

You can enable an Oracle Database instance to use Oracle Cloud Infrastructure (IAM) authentication and authorization for users.

Oracle Cloud Infrastructure IAM integration with Oracle Exadata Database Service on Cloud@Customer supports the following:

• IAM Database Password Authentication
• Identity and Access Management (IAM) SSO Token Based Authentication

See Authenticating and Authorizing IAM Users for Oracle DBaaS Databases for complete details about the architecture for using IAM users on Oracle Exadata Database Service on Cloud@Customer.

You can enable an Oracle Database instance to allow user access with an Oracle Cloud Infrastructure IAM database password (using a password verifier).

An Oracle Cloud Infrastructure IAM database password allows an IAM user to log in to an Oracle Database instance as Oracle Database users typically log in with a username and password. The user enters their IAM user name and IAM database password. An IAM database password is a different password than the Oracle Cloud Infrastructure Console password. Using an IAM user with the password verifier, you can log in to Oracle Database with any supported database client.

For password verifier database access, you create the mappings for IAM users and OCI applications to the Oracle Database instance. The IAM user accounts themselves are managed in IAM. The user accounts and user groups can be in either the default domain or in a custom, non-default domain.

For more information about managing IAM database password, see Managing User Credentials.

You can enable an Oracle Database instance to use Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) SSO tokens.

For token verifier database access, you create the mappings for IAM users and OCI applications to the Oracle Database instance. The IAM user accounts themselves are managed in IAM. The user accounts and user groups can be in either the default domain or in a custom, non-default domain.

There are several ways a database client can obtain an IAM database token:

• A client application or tool can request the database token from IAM for the user and can pass the database token through the client API. Using the API to send the token overrides other settings in the database client. Using IAM tokens requires the latest Oracle Database client 19c (at least 19.16). Some earlier clients (19c and 21c) provide a limited set of capabilities for token access. Oracle Database client 21c does not fully support the IAM token access feature. For more information about the clients supported for this type of IAM database token usage, see Supported Client Drivers for IAM Connections.
• If the application or tool does not support requesting an IAM database token through the client API, the IAM user can first use the Oracle Cloud Infrastructure command line interface (CLI) to retrieve the IAM database token and save it in a file location. For example, to use SQL*Plus and other applications and tools using this connection method, you first obtain the database token using the Oracle Cloud Infrastructure (OCI) Command Line Interface (CLI). For more information, see db-token get. If the database client is configured for IAM database tokens, when a user logs in with the slash login form, the database driver uses the IAM database token that has been saved in the default or specified file location.
• A client application or tool can use an Oracle Cloud Infrastructure IAM instance principal or resource principal to get an IAM database token and use the IAM database token to authenticate itself to an Oracle Database instance.
• IAM users and OCI applications can request a database token from IAM with several methods, including using an API key. See Configuring a Client Connection for SQL*Plus That Uses an IAM Token for an example. See Authenticating and Authorizing IAM Users for Oracle DBaaS Databases for a description of other methods such as using a delegation token within an OCI cloud shell.

In previous releases, you could only use the IAM username and database password to get a password verifier from IAM. Getting a token with these credentials is more secure than getting a password verifier because a password verifier is considered sensitive. Using a token means that you do not need to pass or use the verifier. Applications cannot pass a token that was retrieved by the IAM user name and password through the database client API. Only the database client can retrieve this type of token. A database client can only retrieve a database token using the IAM user name and IAM database password.

Review the prerequisites for enabling IAM user access to Oracle Database.

If the database is enabled for another external authentication scheme, verify that you want to use IAM on the Oracle Database instance. There can only be one external authentication scheme enabled at any given time.

If you want to use IAM and another external authentication scheme is enabled, you must first disable the other external authentication scheme.

Configure a network connection to OCI to be able to make calls to OCI IAM for the database instances on Oracle Exadata Database Service on Cloud@Customer to accept IAM database access tokens (db-tokens), or get IAM database password verifiers.

1. Consult your ExaDB-C@C administrator to determine the OCI region assigned to your ExaDB-C@C installation.
2. Determine the OCI IAM endpoint for that OCI region. For more information, see Identity and Access Management Service API.
3. Find the port number for Identity Service for name resolution of Oracle operators. For more information, see Table 3-2 Ports to Open for Control Plane Connectivity in Network Requirements for Oracle Exadata Database Service on Cloud@Customer.

   For example, if your OCI region is Phoenix, then open port 443 to https://identity.us-phoenix-1.oci.oraclecloud.com.

4. Configure your network to open this connection.

When sending IAM tokens from the database client to the database server, a TLS connection must be established. The TLS wallet with the database certificate for the ExaDB-C@C service instance must be stored under the WALLET_ROOT location. Create a tls directory so it looks like: WALLET_ROOT/<PDB GUID>/tls.

Configure network proxy settings in your environment to allow the database to access OCI IAM. Replace the network proxy URL http://www-proxy.example.com:80/ and the database name given in the example with yours.

1. Log in to the host operating system.
2. Set the proxy environment variables.

   srvctl setenv database -db exampledbname -env "https_proxy=http://www-proxy.example.com:80/"
   srvctl setenv database -db exampledbname -env "http_proxy=http://www-proxy.example.com:80/"
   

3. Stop the database and verify that the variables have been set:

   $ srvctl stop database -db exampledbname

   $ srvctl getenv database -db exampledbname
   http_proxy=http://www-proxy.example.com:80/
   https_proxy=http://www-proxy.example.com:80/

4. Restart the database.

   $ srvctl start database -db exampledbname

Review the steps to enable IAM user access to Oracle Database.

1. Perform the prerequisites for IAM authorization and authentication on Oracle Database.

   See Prerequisites for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database for more information.

2. Enable Oracle Cloud Infrastructure (IAM) Authentication and Authorization using the ALTER SYSTEM command.

   ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE=OCI_IAM SCOPE=BOTH;

3. Verify the value of IDENTITY_PROVIDER_TYPE system parameter.

   SELECT NAME, VALUE FROM V$PARAMETER WHERE NAME='identity_provider_type';
   NAME                     VALUE
   ----------------------   -------
   identity_provider_type   OCI_IAM

Review the steps to change the external identity provider from (IAM) authentication and authorization to another and vice-versa.

1. Disable IAM integration using the ALTER SYSTEM command.

   ALTER SYSTEM RESET IDENTITY_PROVIDER_TYPE SCOPE=BOTH;

2. Verify the value of IDENTITY_PROVIDER_TYPE system parameter.

   SELECT NAME, VALUE FROM V$PARAMETER WHERE NAME='identity_provider_type';
   NAME                   VALUE   
   ---------------------- ------- 
   identity_provider_type None

3. Configure the other directory service integration.

Review the steps to re-enable IAM users to connect to Oracle Database using Oracle Cloud Infrastructure (IAM) Authentication and Authorization

1. Disable the integration with the other identity provider or directory service.
2. Enable IAM integration as described in Enable Identity and Access Management (IAM) Authentication on Oracle Database.

Describes the steps to disable IAM external authentication user access for Oracle Database.

1. Disable IAM integration using the ALTER SYSTEM command.

   ALTER SYSTEM RESET IDENTITY_PROVIDER_TYPE SCOPE=BOTH;

2. If you also want to remove IAM user access to the database, you may need to remove or modify the IAM group and the IAM policies you set up to allow access to the database.

Review the notes for using Oracle Database tools with IAM authentication enabled.

• Oracle APEX is not supported for IAM users with Oracle Database.
• Database Actions is not supported for IAM users with Oracle Database. See Provide Database Actions Access to Database Users for information on using regular database users with Oracle Database.
• Oracle Machine Learning Notebooks and other components are not supported for IAM Authorized users with Oracle Database. See Add Existing Database User Account to Oracle Machine Learning Components for information on using regular database users with Oracle Database.

Review the the steps to write policy statements for an IAM group to enable IAM user access to OCI resources, specifically the Oracle Database instances.

1. Create an IAM group for IAM users to access OCI databases. Add users to this group.

   For example, create the group sales_dbusers. For more information, see Managing Groups.

2. Write policy statements to enable access to Oracle Cloud Infrastructure resources.
   1. In the Oracle Cloud Infrastructure console, click Identity and Security, and then click Policies.
   2. To a write policy, click Create Policy, and then enter a Name and a Description.
   3. Use the Policy Builder to create a policy.
      For example, to create a policy to allow users in IAM group DBUsers to access any Oracle Database in their tenancy:

      Allow group DBUsers to use database-connections in tenancy

      For example to create a policy that limits members of DBUsers group to access Oracle Databases in the compartment testing_compartment only:

      allow group DBUsers to use database-connections in compartment testing_compartment

      For example, to create a policy that limits group access to a single database in a compartment:

      allow group DBUsers to use database-connections in compartment testing_compartment where target.database.id = 'ocid1.autonomousdatabase.oc1.iad.aaaabbbbcccc'

   4. Click Create.

Review the steps to authorize IAM users on an Oracle Database instance.

1. Log in as the ADMIN user to the database that is enabled to use IAM.

   The ADMIN user has the required CREATE USER and ALTER USER system privileges that you need for these steps.

2. Create a mapping between the Oracle Database user (schema) with CREATE USER or ALTER USER statements and include the IDENTIFIED GLOBALLY AS clause, specifying the IAM group name.
   Use the following syntax to map a global user to an IAM group:

   CREATE USER global_user IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=IAM_GROUP_NAME';

   For example, to map an IAM group named db_sales_group to a shared database global user named sales_group:

   CREATE USER sales_group IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=db_sales_group';

   This creates a shared global user mapping. The mapping, with the global user sales_group is effective for all users in the IAM group. Thus, anyone in the db_sales_group can log in to the database using their IAM credentials through the shared mapping of the sales_group global user.

   If you want to create additional global user mappings for other IAM groups or users, follow these steps for each IAM group or user.

   Note
   
   Database users that are not IDENTIFIED GLOBALLY can continue to login as before, even when the Oracle Database is enabled for IAM authentication.

Review the steps to map Oracle Database global roles to IAM groups.

1. Log in as the ADMIN user to the database that is enabled to use IAM.

   The ADMIN user has the required CREATE USER and ALTER USER system privileges that you need for these steps.

2. Set database authorization for Oracle Database roles with CREATE ROLE or ALTER ROLE statements and include the IDENTIFIED GLOBALLY AS clause, specifying the IAM group name.
   Use the following syntax to map a global role to an IAM group:

   CREATE ROLE global_role IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=IAM_GROUP_of_WHICH_the_IAM_USER_IS_a_MEMBER';

   For example, to map an IAM group named ExporterGroup to a shared database global role named export_role:

   CREATE ROLE export_role IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=ExporterGroup';

3. Use the GRANT statements to grant the required privileges or other roles to the global role.

   GRANT CREATE SESSION TO export_role;

   GRANT DWROLE TO export_role;

4. If you want an existing database role to be associated with an IAM group, then use the ALTER ROLE statement to alter the existing database role to map the role to an IAM group.
   Use the following syntax to alter an existing database role to map it to an IAM group:

   ALTER ROLE existing_database_role IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=IAM_Group_Name';

To add an IAM user and allow the IAM user to login to Oracle Database by supplying a username and password, you must create an IAM database password.

For more information, see Working with IAM Database Passwords.

IAM users can connect to the Oracle Database instance by using either an IAM database password verifier or an IAM token.

Using the IAM database password verifier is similar to the Oracle Database password authentication process. However, instead of the password verifier (encrypted hash of the password) being stored in the Oracle Database, the verifier is instead stored as part of the Oracle Cloud Infrastructure (OCI) IAM user profile.

The second connection method, the use of an IAM token for the database, is more modern. The use of token-based access is a better fit for Cloud resources such as Oracle Database. The token is based on the strength that the IAM endpoint can enforce. This can be multi-factor authentication, which is stronger than the use of passwords alone. Another benefit of using tokens is that the password verifier (which is considered sensitive) is never stored or available in memory. A TCPS (TLS) connection is required when using tokens for database access.

• Client Connections That Use an Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Database Password Verifier
  After you have configured the authorization needed for the IAM user, this user can log in using an existing client application, such as SQL*Plus or SQLcl without additional configuration.
• Client Connections That Use a Token Requested by a Client Application or Tool
  For IAM token access to the Oracle DBaaS, the client application or tool requests a database token from IAM for the IAM user.
• Client Connections That Use a Token Requested by an IAM User Name and Database Password
  You can create a client connection that uses a token requested by an IAM user name and database password.
• Configure a Secure External Password Store Wallet to Retrieve an Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Token
  You can enable an IAM user name and a secure external password store (SEPS) to request the IAM database token.

You can configure SQL*Plus to use an IAM database password.

1. As the IAM user, log in to the Oracle Database.

   CONNECT user_name@db_connect_string
   Enter password: password

   In this specification, user_name is the IAM user name. There is a limit of 128 bytes for the combined domain_name/user_name.

   The following example shows how IAM user peter_fitch can log in to an Oracle Database instance.

   sqlplus /nolog
   connect peter_fitch@db_connect_string
   Enter password: password

   Some special characters will require double quotation marks around user_name and password. For example:

   "peter_fitch@example.com"@db_connect_string
   "IAM database password"

You can configure a client connection for SQL*Plus that uses an IAM token.

1. Ensure you have an IAM user account.
2. Check with an IAM administrator and Oracle Database administrator to ensure you have a policy allowing you to access the database in the compartment or your tenancy and that you are mapped to a global schema in the database.
3. If your application or tool does not support direct IAM integration, then download, install, and configure the OCI CLI.

   See OCI Command Line Interface Quickstart.

4. Set up an API key as part of the OCI CLI configuration and select default values.
   1. Set up the API key access for the IAM user.
   2. Retrieve the db-token.
      For example:

      • Retrieving a db-token with an API-key using the Oracle Cloud Infrastructure (OCI) command-line interface:

        oci iam db-token get

      • Retrieving a db-token with a security (or session) token:

        oci iam db-token get --auth security_token

        If the security token has expired, a window will appear so the user can log in to OCI again. This generates the security token for the user. OCI CLI will use this refreshed token to get the db-token.

      • Retrieving a db-token with a delegation token: When you log in to the cloud shell, the delegation token is automatically generated and placed in the /etc directory. To get this token, execute the following command in the cloud shell:

        oci iam db-token get

      • Retrieving an instance token by using the OCI command-line interface:

        oci iam db-token get --auth instance_principal

      See Required Keys and OCIDs for more information.

5. Ensure that you are using the latest release updates for the Oracle Database client release 19c.

   This configuration only works with the Oracle Database client release 19c (Oracle Database release 21c offers limited IAM token features).

6. Ensure that TLS is configured for the database connection.
   1. Confirm that DN matching is enabled by looking for SSL_SERVER_DN_MATCH=ON in the sqlnet.ora file.
   2. Configure the database client to use the IAM token by adding TOKEN_AUTH=OCI_TOKEN to the sqlnet.ora file.

      Because you will be using the default locations for the database token file, you do not need to include the token location.

   The TOKEN_AUTH and TOKEN_LOCATION values in the tnsnames.ora connect strings take precedence over the sqlnet.ora settings for that connection.

   For example, for the connect string, assuming that the token is in the default location (~/.oci/db-token for Linux):

   (description= 
     (retry_count=20)(retry_delay=3)
     (address=(protocol=tcps)(port=1522)
     (host=example.us-phoenix-1.oraclecloud.com))
     (connect_data=(exa1scan.example.com:1521/PDB1.example.yourcloud.com))
     (security=(ssl_server_cert_dn="CN=example.uscom-east-1.oraclecloud.com, 
        OU=Oracle BMCS US, O=Example Corporation, 
        L=Redwood City, ST=California, C=US")
     (TOKEN_AUTH=OCI_TOKEN)))

   After the connect string is updated with the TOKEN_AUTH parameter, the IAM user can log in to the Oracle Database instance by running the following command to start SQL*Plus. You can include the connect descriptor itself or use the name of the descriptor from the tnsnames.ora file.

   connect /@exampledb_high

   (or)

   (description= 
     (retry_count=20)(retry_delay=3)
     (address=(protocol=tcps)(port=1522)
     (host=example.us-phoenix-1.oraclecloud.com))
     (connect_data=(exa1scan.example.com:1521/PDB1.example.yourcloud.com))
     (security=(ssl_server_cert_dn="CN=example.uscom-east-1.oraclecloud.com, 
        OU=Oracle BMCS US, O=Example Corporation, 
        L=Redwood City, ST=California, C=US")
     (TOKEN_AUTH=OCI_TOKEN)))

After the DBA user enables Oracle Cloud Infrastructure IAM on Oracle Database, an application can access the database through an Oracle Cloud Infrastructure IAM database token using an instance principal.

You create the mappings for IAM users and Oracle Cloud Infrastructure (OCI) applications to database users (schemas) in the Oracle DBaaS.

There is a difference with authorization between IAM database password authentication and using IAM token based authentication. IAM database password verifier authorization is only based on mappings of database schemas and global roles to IAM users and group. With IAM token based authentication, IAM policies are an additional authorization for IAM users to access their tenancy databases. An IAM user must be authorized through an IAM policy and be authorized through a mapping to a database global schema (exclusive or shared).

For both token and password verifier database access, you create the mappings for IAM users and OCI applications to the Oracle DBaaS instance. The IAM user accounts themselves are managed in IAM. The user accounts and user groups can be in either the default domain or in a custom, non-default domain.

When the IAM user accesses the Oracle DBaaS instance with a token, the database will perform an authorization check against IAM policies to ensure the user is allowed to access the database. If the IAM user is allowed to access the database by IAM policy, then the database will query IAM for the user groups. When using password verifier authentication, the database will query IAM for user groups once the IAM user successfully completes authentication. The database queries the IAM endpoint to find the groups of which the user is a member. If your deployment is using shared schemas, then one of the IAM groups will map to a shared database schema and the IAM user will be assigned to that database schema. The IAM user will have the roles and privileges that are granted to the database schema. Because multiple IAM users can be assigned to the same shared database schema, only the minimal set of roles and privileges should be granted to the shared schema. In some cases, no privileges and roles should be granted to the shared schema. Users will be assigned the appropriate set of roles and schemas through database global roles. Global roles are mapped to IAM groups. This way, different users can have different roles and privileges even if they are mapped to the same database shared schema. A newly hired user will be assigned to an IAM group mapped to a shared schema and then to one or more additional groups mapped to global roles to gain the additional roles and privileges required to complete their tasks. The combination of shared schemas and global roles allows for centralized authorization management with minimal changes to the database operationally. The database must be initially provisioned with the set of shared schemas and global roles mapped to the appropriate IAM groups, but then user authorization management can happen within IAM.

Ensure that the IAM user is only mapped to one schema, either through exclusive mapping to a database schema or as a member of one IAM group that is mapped to a shared database schema. If more than one schema is mapped for an IAM user, then the database will take exclusive mapping as precedence over any group mapping to a shared schema. If more than one group is mapped for a user, then the database will select the oldest mapping.

When using global roles to grant privileges and roles to the user, remember that the maximum number of enabled roles in a session is 150.

If you drop and recreate IAM users and groups using the same names, then the mappings from the database to IAM using the same names will continue to work. However, recreating an IAM user will require the IAM user to do one or more of the following: create the IAM database password, re-upload the API public key, update the OCI configuration file, and then re-examine the IAM policy for database authentication and authorization with IAM. If the IAM policy specifies a group that can use or manage the database-connections and autonomous-database-family resource types, then the user will need to be added to that group to allow IAM authentication and authorization.

Accessing the database with tokens requires the user to be authorized by IAM policy and by database mapping. Accessing the database with the IAM database password verifier requires authorization through database mapping. If no database schema mapping exists for the IAM user, the IAM user is prevented from accessing the database even if they have a valid token or password.

IAM users get their authorizations to perform various tasks based on the roles that they have been granted. The following scenarios are possible:

• IAM group mapped to a shared Oracle Database global user: With the shared database global user account, an IAM user is assigned to a shared database schema (user) through the mapping of an IAM group to the shared schema. The IAM users that are members of the group can connect to the database through this shared schema. Use of shared schemas allows for centralized management of user authorization in IAM.
• IAM group mapped to an Oracle Database global role: The privileges that have been granted to the shared Oracle Database global role become available to the users who have added to the IAM group.
• Local IAM user exclusively mapped to an Oracle Database global user: With an exclusive global user mapping, a dedicated database user is exclusively mapped to a local IAM user. Not as common as the shared database schema, this user is created for when the user requires their own schema objects. Oracle recommends that you grant database privileges to these users through global roles, which facilitates authorization management. These users can also have direct privilege and role grants to their exclusive schema.

  In IAM with Identity Domains, users and groups are supported in the default domain as well as custom non-default domains. When you specify users and groups in the default domain, then no domain prefix is required. When you specify users and groups in a non-default domain, then the domain must be prefixed.

Oracle Database global users that are mapped to IAM groups and IAM dynamic groups give IAM users and OCI applications a schema when they log in along with the privileges and roles granted to that schema.

1. Log in to the Oracle DBaaS instance as a user who has the CREATE USER or ALTER USER system privilege.
2. Run the CREATE USER or ALTER USER statement with the IDENTIFIED GLOBALLY AS clause specifying the IAM group name (which can be a dynamic group).
   For example, to create a new database global user account named shared_sales_schema and map it to an existing IAM group named WidgetSalesGroup:

   CREATE USER shared_sales_schema IDENTIFIED GLOBALLY AS
   'IAM_GROUP_NAME=WidgetSalesGroup';

   The following example shows how to accomplish this for a non-default domain:

   CREATE USER shared_sales_schema IDENTIFIED GLOBALLY AS
   'IAM_GROUP_NAME=sales_domain/WidgetSalesGroup';

Oracle Database global roles that are mapped to IAM groups and dynamic groups give member users and applications additional privileges and roles above what they have been granted through their login schemas.

1. Log in to the Oracle DBaaS instance as a user who has been granted the CREATE ROLE or ALTER ROLE system privilege
2. Run the CREATE ROLE or ALTER ROLE statement with the IDENTIFIED GLOBALLY AS clause specifying the name of the IAM group (which can be a dynamic group).
   For example, to create a new database global role named widget_mgr_role and map it to an existing IAM group named WidgetManagerGroup, using the default domain:

   CREATE ROLE widget_mgr_role IDENTIFIED GLOBALLY AS 
   'IAM_GROUP_NAME=WidgetManagerGroup';

   The following example shows how to create the role by specifying a non-default domain, sales_domain:

   CREATE ROLE widget_sales_role IDENTIFIED GLOBALLY AS 
   'IAM_GROUP_NAME=sales_domain/WidgetManagerGroup';

   All members of the WidgetManagerGroup in the sales_domain domain will be authorized with the database global role widget_sales_role when they log in to the database.

You can map an IAM user exclusively to an Oracle Database global user.

1. Log in to the Oracle DBaaS instance as a user who has been granted the CREATE USER or ALTER USER system privilege.
2. Run the CREATE USER or ALTER USER statement with the IDENTIFIED GLOBALLY AS clause specifying the IAM database user name.
   By default, the IAM database user name is the same as the IAM user name, including the domain name. You can also create a unique IAM database user name for ease of authentication to the database. In your OCI IAM user profile, you can create a unique IAM database user name for ease of authentication to the database. This can be set when you create and manage your IAM database password in your IAM profile. Adding or changing the IAM database user name will invalidate the IAM user to schema mapping, so the database schema will need to be remapped to the new IAM database user name.
   For example, to create a new database global user named peter_fitch and map this user to an existing IAM user named with an IAM database user name of peterfitch, using the default domain:

   CREATE USER peter_fitch IDENTIFIED GLOBALLY AS 
   'IAM_PRINCIPAL_NAME=peterfitch';

   The following example shows how to create the user by specifying a non-default domain, sales_domain:

   CREATE USER peter_fitch2 IDENTIFIED GLOBALLY AS
   'IAM_PRINCIPAL_NAME=sales_domain/peterfitch';

You can update an IAM user to a database global user mapping by using the ALTER USER statement.

1. Log in to the Oracle DBaas instance as a user who has been granted the ALTER USER system privilege.
2. Run the ALTER USER statement with the IDENTIFIED GLOBALLY AS clause.
   For example, suppose you want to change the existing schema shared_sales_schema to a different IAM group:

   ALTER USER shared_sales_schema IDENTIFIED GLOBALLY AS
   'IAM_GROUP_NAME=BiggerWidgetSalesGroup';

   The following example shows how to modify the schema by specifying a non-default domain, sales_domain:

   ALTER USER shared_sales_schema IDENTIFIED GLOBALLY AS 
   'IAM_GROUP_NAME=sales_domain/BiggerWidgetSalesGroup';

Instance principals and resource principals can be used by applications to retrieve database tokens to establish a connection to an Oracle DBaaS instance.

Only dynamic groups can be mapped when you use instance and resource principals. You cannot exclusively map instance and resource principals; you only can map them through a shared mapping and putting the instance or resource instance in an IAM dynamic group.

After you configure and authorize an IAM user for the Oracle DBaaS instance, you can verify the user logon information by executing a set of SQL queries on the Oracle database side.

1. Log in to the Oracle DBaaS instance as an IAM user that you have just configured and authorized.
   For example, to log in to the database instance inst1 as the database global user peterfitch, who is using the default domain in IAM:

   sqlplus /nolog
   CONNECT "peterfitch"@inst1
   Enter password: password

   This example shows how to log in if user peterfitch is in a non-default domain, sales_domain:

   sqlplus /nolog
   CONNECT "sales_domain/peterfitch"@inst1
   Enter password: password

2. Verify the mapped global user.
   The mapped global user is the database user account that has the IAM user authorization. User PETER_FITCH_SCHEMA is considered a global user with exclusive mapping for the IAM user peterfitch, while user WIDGET_SALES is considered a global user with shared mapping for IAM group widget_sales_group of which peterfitch is a member.

   SHOW USER;

   Output similar to the following appears, depending on if it is an exclusive mapping or a shared mapping:

   USER is "PETER_FITCH_SCHEMA"

   Or

   USER is "WIDGET_SALES"

3. Find the roles that have been granted to the centrally managed user.

   SELECT ROLE FROM SESSION_ROLES ORDER BY ROLE;

   Output similar to the following appears:

   ROLE
   ----------------------------------------------------------------------
   WIDGET_SALES_ROLE
   ...

4. Run the following queries to check the SYS_CONTEXT namespace values for the current schema being used in this database session, current user name, session user name, authentication method, authenticated identity, enterprise identity, identification type, and server type.
   • Verify the current schema that is being used in this database session. A database schema is an object container that identifies the objects it contains. The current schema is the default container for objects name resolution in this database session.

     SELECT SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA') FROM DUAL;

     Output similar to the following appears, depending on if it is an exclusive mapping or a shared mapping:

     SYS_CONTEXT('USERENV','CURRENT_SCHEMA')
     ----------------------------------------------------------------------
     PETER_FITCH_SCHEMA

     Or

     SYS_CONTEXT('USERENV','CURRENT_SCHEMA')
     ----------------------------------------------------------------------
     WIDGET_SALES

   • Verify the current user. In this case, the current user is the same as the current schema.

     SELECT SYS_CONTEXT('USERENV', 'CURRENT_USER') FROM DUAL;

     Output similar to the following appears, depending on if it is an exclusive mapping or a shared mapping:

     SYS_CONTEXT('USERENV','CURRENT_USER')
     ----------------------------------------------------------------------
     PETER_FITCH_SCHEMA

     Or

     SYS_CONTEXT('USERENV','CURRENT_USER')
     ----------------------------------------------------------------------
     WIDGET_SALES

   • Verify the session user.

     SELECT SYS_CONTEXT('USERENV', 'SESSION_USER') FROM DUAL;

     Output similar to the following appears, depending on if it is an exclusive mapping or a shared mapping:

     SYS_CONTEXT('USERENV','SESSION_USER')
     ----------------------------------------------------------------------
     PETER_FITCH_SCHEMA

     Or

     SYS_CONTEXT('USERENV','SESSION_USER')
     ----------------------------------------------------------------------
     WIDGET_SALES

   • Verify the authentication method.

     SELECT SYS_CONTEXT('USERENV', 'AUTHENTICATION_METHOD') FROM DUAL;

     Output similar to the following appears:

     SYS_CONTEXT('USERENV','AUTHENTICATION_METHOD')
     ----------------------------------------------------------------------
     PASSWORD_GLOBAL

     If the user is authenticating with a token, then the output is TOKEN_GLOBAL.

   • Verify the authenticated identity for the enterprise user. The IAM authenticated user identity is captured and audited when this user logs on to the database.

     SELECT SYS_CONTEXT('USERENV', 'AUTHENTICATED_IDENTITY') FROM DUAL;

     Output similar to the following appears:

     SYS_CONTEXT('USERENV','AUTHENTICATED_IDENTITY')
     ----------------------------------------------------------------------
     sales_domain/peterfitch

   • If a user nickname has been set for the enterprise user, then verify this nickname.

     SELECT SYS_CONTEXT('USERENV', 'USER_NICKNAME') FROM DUAL;

     Output similar to the following appears:

     SYS_CONTEXT('USERENV','USER_NICKNAME')
     ----------------------------------------------------------------------
     pfitch

   • Verify the centrally managed user's enterprise identity.

     SELECT SYS_CONTEXT('USERENV', 'ENTERPRISE_IDENTITY') FROM DUAL;

     Enterprise Identity will show the OCI Identity (OCID) of the IAM user or OCI application. Output similar to the following appears:

     SYS_CONTEXT('USERENV','ENTERPRISE_IDENTITY')
     ----------------------------------------------------------------------
     ocid1.user.region1..aaaaaaaaj7ot4g2sagkjtw3enbg4ied3x554zwyywurgrm2232j4crm5zha
     

   • Verify the identification type.

     SELECT SYS_CONTEXT('USERENV', 'IDENTIFICATION_TYPE') FROM DUAL

     Output similar to the following appears, depending on if it is an exclusive mapping or a shared mapping:

     SYS_CONTEXT('USERENV','IDENTIFICATION_TYPE')
     ----------------------------------------------------------------------
     GLOBAL EXCLUSIVE

     Or

     SYS_CONTEXT('USERENV','IDENTIFICATION_TYPE')
     ----------------------------------------------------------------------
     GLOBAL SHARED

   • Verify the server type.

     SELECT SYS_CONTEXT('USERENV', 'LDAP_SERVER_TYPE') FROM DUAL;

     Output similar to the following appears. In this case, the LDAP server type is IAM.

     SYS_CONTEXT('USERENV','LDAP_SERVER_TYPE')
     ----------------------------------------------------------------------
     OCI_IAM

Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) users can connect to Oracle Database by using proxy authentication.

Proxy authentication is typically used to authenticate the real user and then authorize them to use a database schema with the schema privileges and roles in order to manage an application. Alternatives such as sharing the application schema password are considered insecure and unable to audit which actual user performed an action.

A use case can be in an environment in which a named IAM user who is an application database administrator can authenticate by using their credentials and then proxy to a database schema user (for example, hrapp). This authentication enables the IAM administrator to use the hrapp privileges and roles as user hrapp in order to perform application maintenance, yet still use their IAM credentials for authentication. An application database administrator can sign in to the database and then proxy to an application schema to manage this schema.

You can configure proxy authentication for both password authentication and token authentication methods.

To configure proxy authentication for an IAM user, the IAM user must already have a mapping to a global schema (exclusive or shared mapping). A separate database schema for the IAM user to proxy to must also be available.

1. Log in to the Oracle Database instance as a user who has the ALTER USER system privileges.
2. Grant permission for the IAM user to proxy to the local database user account.
   An IAM user cannot be referenced in the command so the proxy must be created between the database global user (mapped to the IAM user) and the target database user. In the following example, hrapp is the database schema to proxy to, and peterfitch_schema is the database global user exclusively mapped to user peterfitch.

   ALTER USER hrapp GRANT CONNECT THROUGH peterfitch_schema;

   At this stage, the IAM user can log in to the database instance using the proxy.

   For example, to connect using a password verifier:

   CONNECT peterfitch[hrapp]@connect_string
   Enter password: password

3. To connect using a token:

   CONNECT [hrapp]/@connect_string

You can validate the IAM user proxy configuration for both password and token authentication methods.

1. Log in to the Oracle Database instance as a user who has the CREATE USER and ALTER USER system privileges.
2. Connect at the IAM user and execute the SHOW USER and SELECT SYS_CONTEXT commands.

   For example, suppose you want to check the proxy authentication of the IAM user peterfitch when they proxy to database user hrapp. You will need to connect to the database using the different types of authentication methods shown here, but the output of the commands that you execute will be the same for all types.

   • For password authentication:

     CONNECT peterfitch[hrapp]/password\!@connect_string
     SHOW USER;
     --The output should be USER is "HRAPP"
     SELECT SYS_CONTEXT('USERENV','AUTHENTICATION_METHOD') FROM DUAL;
     --The output should be "PASSWORD_GLOBAL"
     SELECT SYS_CONTEXT('USERENV','PROXY_USER') FROM DUAL;
     --The output should be "PETERFITCH_SCHEMA"
     SELECT SYS_CONTEXT('USERENV','CURRENT_USER') FROM DUAL;
     --The output should be "HRAPP"

   • For token authentication:

     CONNECT [hrapp]/@connect_string
     SHOW USER;
     --The output should be USER is "HRAPP"
     SELECT SYS_CONTEXT('USERENV','AUTHENTICATION_METHOD') FROM DUAL;
     --The output should be "TOKEN_GLOBAL"
     SELECT SYS_CONTEXT('USERENV','PROXY_USER') FROM DUAL;
     --The output should be "PETERFITCH_SCHEMA"
     SELECT SYS_CONTEXT('USERENV','CURRENT_USER') FROM DUAL;
     --The output should be "HRAPP"

The MS-EI integration with the Oracle Database on Oracle Exadata Database Service on Cloud@Customer requires:

1. The Oracle Database to be version 19.18 or higher.
2. Connectivity to the database on TLS port 2484. Non TLS connections are not supported.
3. Outbound network connectivity to MS-EI so that the database can request the MS-EI public key.
4. The Oracle Database to be registered with MS-EI.
5. Users and applications that need to request an MS-EI token must also be able to have network connectivity to MS-EI. You may need to configure a proxy setting for the connection.
6. For Exadata Cloud@Customer deployments, the HTTP Proxy settings in your environment must allow the database to use MS-EI.These settings are defined by your fleet administrator while creating the Exadata Cloud@Customer infrastructure as described in Using the Console to Provision Exadata Database Service on Cloud@Customer .
   Note
   
   The network configuration including the HTTP Proxy can only be edited until the Exadata Infrastructure is in Requires Activation state. Once it is activated, you cannot edit those settings.

   Setting up an HTTP Proxy for an already provisioned Exadata Infrastructure needs a Service Request (SR) in My Oracle Support. See Create a Service Request in My Oracle Support for details.

When sending MS-EI tokens from the database client to the database server, a TLS connection must be established. The TLS wallet with the database certificate for the ExaDB-C@C service instance must be stored under the WALLET_ROOT location. Create a tls directory so it looks like: WALLET_ROOT/<PDB GUID>/tls.

When configuring TLS between the database client and server there are several options to consider.

• Using a self-signed database server certificate vs a database server certificate signed by a commonly known certificate authority
• One-way TLS (TLS) vs Mutual or two-way TLS (mTLS)
• Client with or without a wallet

Self-Signed Certificate

Using a self-signed certificate is a common practice for internally facing IT resources since you can create these yourself and it's free. The resource (in our case, the database server) will have a self-signed certificate to authenticate itself to the database client. The self-signed certificate and root certificate will be stored in the database server wallet. For the database client to be able to recognize the database server certificate, a copy of the root certificate will also be needed on the client. This self-created root certificate can be stored in a client-side wallet or installed in the client system default certificate store (Windows and Linux only). When the session is established, the database client will check to see that the certificate sent over by the database server has been signed by the same root certificate.

A Well-Known Certificate Authority

Using a commonly known root certificate authority has some advantages in that the root certificate is most likely already stored in the client system default certificate store. There is no extra step for the client to store the root certificate if it is a common root certificate. The disadvantage is that this normally has a cost associated with it.

One-Way TLS

In the standard TLS session, only the server provides a certificate to the client to authenticate itself. The client doesn't need to have a separate client certificate to authenticate itself to the server (similar to how HTTPS sessions are established). While the database requires a wallet to store the server certificate, the only thing the client needs to have is the root certificate used to sign the server certificate.

Two-Way TLS (also called Mutual TLS, mTLS)

In mTLS, both the client and server have identity certificates that are presented to each other. In most cases, the same root certificate will have signed both of these certificates so the same root certificate can be used with the database server and client to authenticate the other certificate. mTLS is sometimes used to authenticate the user since the user identity is authenticated by the database server through the certificate. This is not necessary for passing IAM tokens but can be used when passing IAM tokens.

Client with a Wallet

A client wallet is mandatory when using mTLS to store the client certificate. However, the root certificate can be stored either in the same wallet or in the system default certificate store.

A Client without a Wallet

Clients can be configured without a wallet when using TLS under these conditions: 1) One-way TLS is being configured where the client does not have its own certificate and 2) the root certificate that signed the database server certificate is stored in the system default certificate store. The root certificate would most likely already be there if the server certificate is signed by a common certificate authority. If it's a self-signed certificate, then the root certificate would need to be installed in the system default certificate store to avoid using a client wallet.

For details on how to configure TLS between the database client and database server including the options described above, see:

• Configuring Transport Layer Security Authentication in the Oracle Database 19c Security Guide.
• Configuring Transport Layer Security Encryption in the Oracle Database 23ai Security Guide.

If you choose to use self-signed certificates and for additional wallet related tasks, see:

• Managing Public Key Infrastructure (PKI) Elements in the Oracle Database 19c Security Guide.
• Configuring TLS Connection With a Client Wallet in the Oracle Database 23ai Security Guide.