Connect Identity and Access Management (IAM) Users to Oracle Exadata Database Service on Dedicated Infrastructure
You can configure Oracle Exadata Database Service on Dedicated Infrastructure to use Oracle Cloud Infrastructure Identity and Access Management (IAM) authentication and authorization to allow IAM users to access an Oracle Database with IAM credentials.
- Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication with Oracle Database
Learn to enable an Oracle Database instance on Oracle Exadata Database Service on Dedicated Infrastructure to allow user access with an Oracle Cloud Infrastructure IAM database password (using a password verifier), or SSO tokens. - Prerequisites for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Review the prerequisites for Identity and Access Management (IAM) authentication on an Oracle Database. - Enable, Disable, and Re-enable Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Learn to enable, disable, and re-enable Identity and Access Management (IAM) Authentication on Oracle Database. - Manage Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Groups and Policies, Users, Roles, and Database Passwords
- Configuring Client Connection
Configure various clients to use IAM authentication. - Configuring Authorization for IAM Users and Oracle Cloud Infrastructure Applications
An Oracle DBaaS database administrator can map IAM users and Oracle Cloud Infrastructure (OCI) applications to the Oracle Database global schemas and global roles.
Parent topic: How-to Guides
Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication with Oracle Database
Learn to enable an Oracle Database instance on Oracle Exadata Database Service on Dedicated Infrastructure to allow user access with an Oracle Cloud Infrastructure IAM database password (using a password verifier), or SSO tokens.
- About Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication with Oracle Database
IAM users can connect to the database instance by using either an IAM database password verifier or an IAM token. - Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Database Password Verifier Authentication
You can enable an Oracle Database instance to allow user access with an Oracle Cloud Infrastructure IAM database password (using a password verifier). - Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) SSO Token Based Authentication
For IAM token access to the database, the client application or tool requests a database token from IAM for the IAM user.
About Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication with Oracle Database
IAM users can connect to the database instance by using either an IAM database password verifier or an IAM token.
Using the IAM database password verifier is similar to the database password authentication process. However, instead of the password verifier (encrypted hash of the password) being stored in the database, the verifier is instead stored as part of the 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 Databases in the Exadata Cloud Infrastructure. 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.
Oracle Database supports the Oracle DBaaS integration for Oracle Cloud Infrastructure (OCI) IAM with identity domains as well as the legacy IAM, which does not include identity domains. Both default and non-default domain users and groups are supported when using IAM with Identity Domains.
Support for non-default custom domains are only available with Oracle Database Release 19c, Version 19.21 and higher (but not Oracle Database Release 21c).
Oracle Cloud Infrastructure IAM integration with Oracle Exadata Database Service on Dedicated Infrastructure supports the following:
- Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Database Password Verifier Authentication
- Oracle Cloud Infrastructure (OCI) 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 Dedicated Infrastructure.
Related Topics
Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Database Password Verifier Authentication
You can enable an Oracle Database instance to allow user access with an Oracle Cloud Infrastructure IAM database password (using a password verifier).
Any supported 12c and above database client can be used for IAM database password access to Oracle Database.
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 username and IAM database password. An IAM database password is a different password than the Oracle Cloud Infrastructure Console password. Using an IAM user with a 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.
Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) SSO Token Based Authentication
For IAM token access to the database, the client application or tool requests a database token from IAM for the IAM user.
The client application will pass the database token directly to the database client through the database client API.
If the application or tool has not been updated to request an IAM token, then
the IAM user can use OCI CLI to request and store the database token. You can request a
database access token (db-token
) using the following credentials:
- Security tokens (with IAM authentication), delegation tokens (in the
OCI cloud shell) and
API-keys
, which are credentials that represent the IAM user to enable the authentication - Instance principal tokens, which enable instances to be authorized actors (or principals) to perform actions on OCI resources after authentication
- Resource principal token, which is a credential that enables the application to authenticate itself to other OCI services
- Using an IAM user name and IAM database password (can only be requested by database client)
When the IAM users logs into the client with a slash /
login and the OCI_IAM
parameter is configured
(sqlnet.ora
, tnsnames.ora
, or as part of a connect
string), then the database client retrieves the database token from a file. If the IAM
user submits a user name and password, the connection will use the IAM database verifier
access described for client connections that use IAM database password verifiers. If the
parameter PASSWORD_AUTH=OCI_TOKEN
, then the database driver will
instead use the username and password to connect directly to IAM and request a database
token. The instructions in this guide show how to use the OCI CLI as a helper for the
database token. If the application or tool has been updated to work with IAM, then
follow the instructions for the application or tool. Some common use cases include the
following: SQL*Plus on-premises, SQLcl on-premises, SQL*Plus in Cloud Shell, or
applications that use SEP wallets.
- 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:
- JDBC-thin on all platforms
- See Support for IAM Token-Based Authentication and JDBC and UCP Downloads for more information.
- SQL*Plus and Oracle Instant Client OCI-C on Linux:
See Identity and Access Management (IAM) Token -Based Authentication for more information
- Oracle Data Provider for .NET (ODP.NET) Core: .NET clients (latest version of Linux or Windows). .NET software components are available as a free download from the following sites:
- Oracle Data access Components - .NET Downloads
- NuGet Gallery
- Visual Studio Code Market Place
- JDBC-thin on all platforms
- 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 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. For more information, see Mapping Instance and Resource Principals.
- 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.
If your database is in Restricted Mode, only DBAs with the
RESTRICTED SESSION
privilege can connect to the database.
If a user enters a username/password to login, then the database driver uses
the password verifier method to access the database. If the parameter
PASSWORD_AUTH=OCI_TOKEN
, then the database driver will instead user
the username and password to connect directly to IAM and request a database token.
Related Topics
- Support for IAM Token-Based Authentication
- JDBC and UCP Downloads
- Identity and Access Management (IAM) Token-Based Authentication
- db-token get
- Oracle Data access Components - .NET Downloads
- NuGet Gallery
- Visual Studio Code Marketplace
- Mapping Instance and Resource Principals
- Configuring a Client Connection for SQL*Plus That Uses an IAM Token
- Authenticating and Authorizing IAM Users for Oracle DBaaS Databases
Prerequisites for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Review the prerequisites for Identity and Access Management (IAM) authentication on an Oracle Database.
- Prerequisites for IAM Authentication on Oracle Database
Before using IAM authentication on databases in the Exadata Cloud Infrastructure, you must use the Networking service to add a service gateway, a route rule, and an egress security rule to the Virtual Cloud Network (VCN) and subnets where your database resources reside. - Disable External Authentication Scheme
Review the prerequisites for enabling IAM user access to Oracle Database. - Configure TLS to Use IAM Tokens
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-D service instance must be stored under theWALLET_ROOT
location. Create a tls directory so it looks like:WALLET_ROOT/<PDB GUID>/tls
.
Prerequisites for IAM Authentication on Oracle Database
Before using IAM authentication on databases in the Exadata Cloud Infrastructure, you must use the Networking service to add a service gateway, a route rule, and an egress security rule to the Virtual Cloud Network (VCN) and subnets where your database resources reside.
- Create a service gateway in the VCN where your database resources reside by following the instructions in Task 1: Create the service gateway in OCI documentation.
- After creating the service gateway, add a route rule and an egress security rule to
each subnet (in the VCN) where the database resources reside so that these resources
can use the gateway to use IAM authentication:
- Go to the Subnet Details page for the subnet.
- In the Subnet Information tab, click the name of the subnet's Route Table to display its Route Table Details page.
- In the table of existing Route Rules, check whether there is
already a rule with the following characteristics:
- Destination: All IAD Services In Oracle Services Network
- Target Type: Service Gateway
- Target: The name of the service gateway you just created in the VCN
If such a rule does not exist, click Add Route Rules and add a route rule with these characteristics.
- Return to the Subnet Details page for the subnet.
- In the subnet's Security Lists table, click the name of the subnet's security list to display its Security List Details page.
- In the side menu, under Resources, click Egress Rules.
- In the table of existing Egress Rules, check whether there is already a rule
with the following characteristics:
- Stateless: No
- Destination: All IAD Services In Oracle Services Network
- IP Protocol: TCP
- Source Port Range: All
- Destination Port Range: 443
- If such a rule does not exist, click Add Egress Rules and add an egress rule with these characteristics.
Disable External Authentication Scheme
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 TLS to Use IAM Tokens
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-D 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 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 Security Guide.
Enable, Disable, and Re-enable Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Learn to enable, disable, and re-enable Identity and Access Management (IAM) Authentication on Oracle Database.
- Enable Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Review the steps to enable or re-enable IAM user access to Oracle Database. - Disable Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Describes the steps to disable IAM external authentication user access for Oracle Database. - Using Oracle Database Tools with Identity and Access Management (IAM) Authentication
Review the notes for using Oracle Database tools with IAM authentication enabled.
Enable Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Review the steps to enable or re-enable IAM user access to Oracle Database.
Oracle Database supports the Oracle DBaaS integration for Oracle Cloud Infrastructure (OCI) IAM with identity domains as well as the legacy IAM, which does not include identity domains. Both default and non-default domain users and groups are supported when using IAM with Identity Domains.
- 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.
- Enable Oracle Cloud Infrastructure (IAM) Authentication and Authorization using the
ALTER SYSTEM
command.ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE=OCI_IAM SCOPE=BOTH;
- 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
Related Topics
Disable Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Authentication on Oracle Database
Describes the steps to disable IAM external authentication user access for Oracle Database.
To disable IAM user access on your Oracle Database instance:
- Disable IAM integration using the
ALTER SYSTEM
command.ALTER SYSTEM RESET IDENTITY_PROVIDER_TYPE SCOPE=BOTH;
- If you also want to remove the IAM policy to allow database access, you may need to review and either modify or remove the IAM groups and the policies you set up to allow access to the database by IAM users.
Using Oracle Database Tools with Identity and Access Management (IAM) Authentication
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.
Manage Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Groups and Policies, Users, Roles, and Database Passwords
- Create Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Groups and Policies for IAM Users
Review the steps to write policy statements for an IAM group to enable IAM user access to Oracle Cloud Infrastructure resources, specifically Oracle Database instances using IAM database tokens. - Authorize Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Users on Oracle Database
Review the steps to authorize IAM users on an Oracle Database instance. - To Exclusively Map a Local IAM User to an Oracle Database Global User
You can map a local IAM user exclusively to an Oracle Database global user. - Add Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Roles on Oracle Database
Optionally, create global roles to provide additional database roles and privileges to IAM users when multiple IAM users are mapped to the same shared global user. - Create Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Database Password for IAM Users
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.
Create Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Groups and Policies for IAM Users
Review the steps to write policy statements for an IAM group to enable IAM user access to Oracle Cloud Infrastructure resources, specifically Oracle Database instances using IAM database tokens.
A policy is a group of statements that specifies who can access particular resources, and how. Access can be granted for the entire tenancy, databases in a compartment, or individual databases. This means you write a policy statement that gives a specific group a specific type of access to a specific type of resource within a specific compartment.
Note: Defining a policy is required to use IAM tokens to access Oracle Database. A policy is not required when using IAM database password verifiers to access Oracle Database.
- Create an IAM group for IAM users that will access the database. Review
OCI IAM documentation for creating groups and adding IAM users to a group.
For example, create the group DBUsers. For more information, see Managing Groups.
- Write policy statements to enable access to Oracle Cloud Infrastructure
resources.
- In the Oracle Cloud Infrastructure console, click Identity and Security, and then click Policies.
- To write a policy, click Create Policy, and then enter a Name and a Description.
- 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
Where,
database-connections
is the OCI resource name to connect to the database.Use
is the minimum verb to allow access to the database. Bothuse
andmanage
can be used.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.database.oc1.iad.aaaabbbbcccc'
- Click Create.
For more information about policies, see Managing Policies.
- Policies can allow IAM users to access Oracle Database instances across the entire tenancy, in a compartment, or can limit access to a single Oracle Database instance.
- You must use dynamic groups for Instance Principals and Resource Principals. You can create Dynamic Groups and reference dynamic groups in the policies you create to access Oracle Cloud Infrastructure. See Accessing Cloud Resources by Configuring Policies and Roles and Managing Dynamic Groups for details.
Authorize Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Users on Oracle Database
Review the steps to authorize IAM users on an Oracle Database instance.
To authorize IAM users to allow access to Oracle Database, map database global users to
IAM groups or directly to IAM users with CREATE USER
or ALTER
USER
statements with IDENTIFIED GLOBALLY AS
clause.
The authorization of IAM users to an Oracle Database instance works by mapping IAM global users (schemas) to IAM users (exclusive mapping) or IAM groups (shared schema mapping).
To authorize IAM users on a database instance:
- Log in as a user with DBA privileges to the database that is enabled to use IAM. A
user with the DBA role will need the required
CREATE USER
andALTER USER
system privileges for these steps. - Create a mapping between the Oracle Database user (schema) with
CREATE USER
orALTER USER
statements and include theIDENTIFIED GLOBALLY AS
clause, specifying the IAM group name. Use the following syntax to map a global user to an IAM group:
For example, to map an IAM group named db_sales_group to a shared database global user named sales_group:CREATE USER global_user IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=IAM_GROUP_NAME';
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 thedb_sales_group
can log in to the database using their IAM credentials through the shared mapping of thesales_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 notIDENTIFIED GLOBALLY
can continue to login as before, even when the Oracle Database is enabled for IAM authentication.
To Exclusively Map a Local IAM User to an Oracle Database Global User
You can map a local IAM user exclusively to an Oracle Database global user.
- Log in as an user with DBA privileges to the database that is enabled to use IAM. A
user with the DBA role has will need the required
CREATE USER
andALTER USER
system privileges that you need for these steps. - Create a mapping between the Oracle Database user (schema) with
CREATE USER
orALTER USER
statements and include theIDENTIFIED GLOBALLY AS
clause, specifying the IAM local IAM user name. For example, to create a new database global user namedpeter_fitch
and map this user to an existing local IAM user namedpeterfitch
:CREATE USER peter_fitch IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=peterfitch'
You can use either instance principal or resource principal to retrieve database tokens to establish a connection from your application to an Oracle Database instance.
If you are using an instance principal or resource principal, you must map a dynamic group. Thus, 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
Add Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Roles on Oracle Database
Optionally, create global roles to provide additional database roles and privileges to IAM users when multiple IAM users are mapped to the same shared global user.
Creating global roles is optional, but useful when assigning users to a shared schema.
Use a global role to optionally differentiate users who use the same shared schema. For
example, a set of users can all have the same shared schema and the shared schema could
have the CREATE SESSION
privilege. Then global roles can be used to
provide differentiated privileges and roles assigned to different groups of users who
all use the same shared schema.
Granting additional roles to IAM users in Oracle Database works by mapping Oracle Database global roles to IAM groups.
- Log in as a user with DBA privileges to the database that is enabled to
use IAM. A user with the DBA privileges
CREATE ROLE
andALTER ROLE
system privileges is needed for these steps. - Set database authorization for Oracle Database roles with
CREATE ROLE
orALTER ROLE
statements and include theIDENTIFIED GLOBALLY AS
clause, specifying the IAM group name. Use the following syntax to map a global role to an IAM group:
For example, to map an IAM group named ExporterGroup to a shared database global role named export_role:CREATE ROLE global_role IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=IAM_GROUP_of_WHICH_the_IAM_USER_IS_a_MEMBER';
CREATE ROLE export_role IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=ExporterGroup';
- 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;
- 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';
Follow these steps for each IAM group to add additional global role mappings for other IAM groups.
Create Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) Database Password for IAM Users
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.
Related Topics
Configuring Client Connection
Configure various clients to use IAM authentication.
- Configure a Client Connection for SQL*Plus that Uses an IAM Database Password Verifier
You can configure SQL*Plus to use an IAM database password verifier. - Configure Client Connection for SQL*Plus that Uses an IAM Token
You can configure a client connection for SQL*Plus that uses an IAM token. - 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. - Use Instance Principal to Access Database with IAM Authentication
After the ADMIN user enables OCI IAM on the database, an application can access the database through an OCI IAM database token using an instance principal. - Configure Proxy Authentication
Proxy authentication allows an IAM user to proxy to a database schema for tasks such as application maintenance. - Use Database Link with IAM Authenticated Users
You can use a database link to connect from one database instance to another as an OCI IAM user.
Configure a Client Connection for SQL*Plus that Uses an IAM Database Password Verifier
You can configure SQL*Plus to use an IAM database password verifier.
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
.
peter_fitch
can log in to a
database instance.
sqlplus /nolog
connect peter_fitch@db_connect_string
Enter password: password
user_name
and
. For example:
"peter_fitch@example.com"@db_connect_string
"IAM database password"
Parent topic: Configuring Client Connection
Configure Client Connection for SQL*Plus that Uses an IAM Token
You can configure a client connection for SQL*Plus that uses an IAM token.
- Ensure you have an IAM user account.
- Check with an IAM administrator and the 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.
- 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.)
Set up an API key as part of the OCI CLI configuration and select default values.
- Set up the API key access for the IAM user.
- Retrieve the
db-token
. For example:- Retrieve a
db-token
with anAPI-key
using the OCI CLI:oci iam db-token get
- Retrieve
db-token
with a security (or session) token:oci iam db-token get --auth security_token
- Retrieve
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 OCI CLI:oci iam db-token get
- Using an instance principal to retrieve a
db-token
using OCI CLI:oci iam db-token get --auth instance_principal
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
.See Required Keys and OCIDs for more information.
- Retrieve a
- Ensure that you are using the latest release updates for the Oracle Database client
releases 19c.
This configuration only works with the Oracle Database client release 19c.
- Follow the existing process to download the wallet from the database and then follow
the directions for configuring it for use with SQL*Plus.
- Confirm that DN matching is enabled by looking for
SSL_SERVER_DN_MATCH=ON
insqlnet.ora
. - Configure the database client to use the IAM token by adding
TOKEN_AUTH=OCI_TOKEN
to thesqlnet.ora
file. Because you will be using the default locations for the database token file, you do not need to include the token location.
TOKEN_AUTH
andTOKEN_LOCATION
values in thetnsnames.ora
connect strings take precedence over thesqlnet.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=(service_name=aaabbbccc_exampledb_high.example.oraclecloud.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)))
- Confirm that DN matching is enabled by looking for
TOKEN_AUTH
parameter, the
IAM user can log in to the 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
connect /@(description=
(retry_count=20)(retry_delay=3)
(address=(protocol=tcps)(port=1522)
(host=example.us-phoenix-1.oraclecloud.com))
(connect_data=(service_name=aaabbbccc_exampledb_high.example.oraclecloud.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)))
The database client is already configured to get a db-token
because
TOKEN_AUTH
has already been set, either through the
sqlnet.ora
file or in a connect string. The database client gets
the db-token
and signs it using the private key and then sends the
token to the database. If an IAM user name and IAM database password are specified
instead of slash /
, then the database client will connect using the
password instead of using the db-token
.
Parent topic: Configuring Client Connection
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.
- IAM users can connect to the Oracle DBaaS instance by using an IAM
token that was retrieved using an IAM user name and IAM database password.
For more information, see About Client Connections That Use a Token Requested by an IAM User Name and Database Password
- To set these parameters, you modify either the
sqlnet.ora
file or thetnsnames.ora
file.For more information, see Parameters to Set for Client Connections That Use a Token Requested by an IAM User Name and Database Password
- You can configure the database client to retrieve the IAM database
token using the provided IAM user name and IAM database password.
For more information, see Configuring the Database Client to Retrieve a Token Using an IAM User Name and Database Password
- You can enable an IAM user name and a secure external password store
(SEPS) to request the IAM database token.
For more information, see Configuring a Secure External Password Store Wallet to Retrieve an IAM Token
Related Topics
- Client Connections That Use a Token Requested by an IAM User Name and Database Password
- About Client Connections That Use a Token Requested by an IAM User Name and Database Password
- Parameters to Set for Client Connections That Use a Token Requested by an IAM User Name and Database Password
- Configuring the Database Client to Retrieve a Token Using an IAM User Name and Database Password
- Configuring a Secure External Password Store Wallet to Retrieve an IAM Token
Parent topic: Configuring Client Connection
Use Instance Principal to Access Database with IAM Authentication
After the ADMIN user enables OCI IAM on the database, an application can access the database through an OCI IAM database token using an instance principal.
For more information, see Accessing the Oracle Cloud Infrastructure API Using Instance Principals.
For more Information, see Accessing the Database Using an Instance Principal or a Resource Principal.
Configure Proxy Authentication
Proxy authentication allows an IAM user to proxy to a database schema for tasks such as application maintenance.
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 the password authentication and token authentication methods.
Configuring Proxy Authentication for the IAM User
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.
After you ensure that you have this type of user, alter the database user to allow the IAM user to proxy to it.
- Log in to the database instance as a user who has the
ALTER USER
system privileges. - 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, andpeterfitch_schema
is the database global user exclusively mapped to userpeterfitch
.ALTER USER hrapp GRANT CONNECT THROUGH peterfitch_schema;
- To connect using a password verifier:
CONNECT peterfitch[hrapp]@connect_string Enter password: password
- To connect using a token:
CONNECT [hrapp]/@connect_string
Validating the IAM User Proxy Authentication
You can validate the IAM user proxy configuration for both password and token authentication methods.
- Connect as the IAM user and proxied to the database user. Run the
SHOW USER
andSELECT 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"
- For password authentication:
Parent topic: Configuring Client Connection
Use Database Link with IAM Authenticated Users
You can use a database link to connect from one database instance to another as an OCI IAM user.
You can use either connected user or fixed user database link to connect to a database as an OCI IAM user.
Current user database link is not supported for connecting to a database in Exadata Cloud Infrastructure as an OCI IAM user.
-
Connected User Database Link: For a connected user database link, an IAM user must be mapped to a schema in both the source and target databases connected by a database link. You can use a database password verifier or an IAM database token to use a connected user database link.
-
Fixed User Database Link: A fixed user database link can be created using a database user or an IAM user. When using an IAM user as a fixed user database link, the IAM user must have a schema mapping in the target database. The IAM user for a database link can be configured with a password verifier only.
Parent topic: Configuring Client Connection
Configuring Authorization for IAM Users and Oracle Cloud Infrastructure Applications
An Oracle DBaaS database administrator can map IAM users and Oracle Cloud Infrastructure (OCI) applications to the Oracle Database global schemas and global roles.
- About Configuring Authorization for IAM Users and Oracle Cloud Infrastructure Applications
You create the mappings for IAM users and Oracle Cloud Infrastructure (OCI) applications to database users (schemas) in the Oracle DBaaS. - Mapping an IAM Group to a Shared Oracle Database Global User
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. - Mapping an IAM Group to an Oracle Database Global Role
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. - Exclusively Mapping an IAM User to an Oracle Database Global User
You can map an IAM user exclusively to an Oracle Database global user. - Altering or Migrating an IAM User Mapping Definition
You can update an IAM user to a database global user mapping by using theALTER USER
statement. - Mapping Instance and Resource Principals
Instance principals and resource principals can be used by applications to retrieve database tokens to establish a connection to an Oracle DBaaS instance. - Verifying the IAM User Logon Information
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.
About Configuring Authorization for IAM Users and Oracle Cloud Infrastructure Applications
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.
Mapping an IAM Group to a Shared Oracle Database Global User
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.
Mapping an IAM Group to an Oracle Database Global Role
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.
Exclusively Mapping an IAM User to an Oracle Database Global User
You can map an IAM user exclusively to an Oracle Database global user.
Altering or Migrating an IAM User Mapping Definition
You can update an IAM user to a database global user mapping by using the ALTER USER
statement.
CREATE USER
statement clauses: IDENTIFIED BY
password, IDENTIFIED EXTERNALLY
, or IDENTIFIED GLOBALLY
. This is useful when migrating existing schemas to using IAM. If you delete and recreate an IAM user or an IAM group using the exact same name as the previous IAM user or group, then the existing mapping from the database that uses that IAM user or IAM group name will continue to work.
Mapping Instance and Resource Principals
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.