Configuring a Kerberos client and connecting to your DB instance

After you complete the steps in Setting up self-managed Active Directory, complete the following steps for each DB instance that you want to use with Kerberos authentication. You join the DB instance to your domain, create Oracle users for your Active Directory (AD) users, configure a Kerberos client, and then connect to the DB instance. If a client host is already configured for your domain, you don't need to repeat its Kerberos configuration in Step 3 for another DB instance. Make sure that the client host can reach the new DB instance over the database port.

• Step 1: Create or modify an Amazon RDS for Oracle DB instance

• Step 2: Create Kerberos authentication Oracle logins

• Step 3: Configure a Kerberos client

• Step 4: Connect to your DB instance

Step 1: Create or modify an Amazon RDS for Oracle DB instance

You can join an Amazon RDS for Oracle DB instance to your self-managed AD domain in the following ways:

• Create a new DB instance with the console, the create-db-instance AWS CLI command, or the CreateDBInstance RDS API operation. For instructions, see Creating an Amazon RDS DB instance.

• Modify an existing DB instance with the console, the modify-db-instance AWS CLI command, or the ModifyDBInstance RDS API operation. For instructions, see Modifying an Amazon RDS DB instance.

• Restore an Oracle DB instance from a DB snapshot using the console, the restore-db-instance-from-db-snapshot AWS CLI command, or the RestoreDBInstanceFromDBSnapshot RDS API operation. For instructions, see Restoring to a DB instance.

• Restore an Oracle DB instance to a point-in-time using the console, the restore-db-instance-to-point-in-time AWS CLI command, or the RestoreDBInstanceToPointInTime RDS API operation. For instructions, see Restoring a DB instance to a specified time for Amazon RDS.

• Create a read replica of an Oracle DB instance using the console, the create-db-instance-read-replica AWS CLI command, or the CreateDBInstanceReadReplica RDS API operation. A read replica doesn't inherit the domain membership of its source, so specify the four domain parameters on the operation. For instructions, see Creating a read replica.

The DB instance must be in a virtual private cloud (VPC) that can reach your domain controllers. When you create or modify the DB instance, make sure that its security groups allow the traffic described in Configure your network connectivity.

Using the console

1. In the Database authentication settings of the create, modify, restore, or create read replica page, choose Password and Kerberos authentication.

2. For Kerberos authentication type, choose Self-managed Microsoft Active Directory.

3. Enter the following values:

   • Fully qualified domain name (FQDN) – The FQDN of your domain, such as corp.example.com.

   • Organizational unit (OU) – The distinguished name of the OU that you created in Step 1 of Setting up self-managed Active Directory, such as OU=AWS-RDS-OU,DC=corp,DC=example,DC=com. It must have one or more OU components followed by one or more DC components, and component values can't contain shell metacharacters $, `, |, ; or control characters.

   • Authorization secret ARN – The Amazon Resource Name (ARN) of the secret that you created in Step 5 of Setting up self-managed Active Directory.

   • Primary DNS server IP and Secondary DNS server IP – The IPv4 addresses of the DNS servers for your domain.

4. Complete the rest of the page, and choose Create database, Modify DB instance, Restore DB instance, or Create read replica.

Using the AWS CLI

When you use the AWS CLI, the following parameters are required for the DB instance to join your self-managed AD domain:

• For --domain-fqdn, use the fully qualified domain name of your domain.

• For --domain-ou, use the distinguished name of the OU that you created in Step 1 of Setting up self-managed Active Directory. It must have one or more OU components followed by one or more DC components, and component values can't contain shell metacharacters $, `, |, ; or control characters.

• For --domain-auth-secret-arn, use the ARN of the secret that you created in Step 5 of Setting up self-managed Active Directory.

• For --domain-dns-ips, use the primary and secondary IPv4 addresses of the DNS servers for your domain. This parameter takes exactly two addresses. If you don't have a secondary DNS server, enter the primary address twice.

For example, the following command joins an existing DB instance to a self-managed AD domain.

For Linux, macOS, or Unix:

aws rds modify-db-instance \
    --db-instance-identifier my-oracle-instance \
    --domain-fqdn corp.example.com \
    --domain-ou "OU=AWS-RDS-OU,DC=corp,DC=example,DC=com" \
    --domain-auth-secret-arn "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-ad-secret-AbCdEf" \
    --domain-dns-ips "10.0.1.100" "10.0.1.101"

For Windows:

aws rds modify-db-instance ^
    --db-instance-identifier my-oracle-instance ^
    --domain-fqdn corp.example.com ^
    --domain-ou "OU=AWS-RDS-OU,DC=corp,DC=example,DC=com" ^
    --domain-auth-secret-arn "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-ad-secret-AbCdEf" ^
    --domain-dns-ips "10.0.1.100" "10.0.1.101"

To verify that the domain join succeeded, run the following command and confirm that Status is kerberos-enabled.

aws rds describe-db-instances \
    --db-instance-identifier my-oracle-instance \
    --query 'DBInstances[0].DomainMemberships'

If the status is enable-kerberos-failed, see Troubleshooting self-managed Active Directory for Amazon RDS for Oracle.

Step 2: Create Kerberos authentication Oracle logins

After the DB instance reaches kerberos-enabled, use the Amazon RDS master user credentials to connect to the Oracle DB instance as you do any other DB instance. The DB instance is joined to your self-managed AD domain, so you can provision Oracle logins and users from the Microsoft Active Directory users in your domain. To manage database permissions, you grant and revoke standard Oracle permissions to these logins.

To allow a Microsoft Active Directory user to authenticate with Oracle

1. Connect to the Oracle DB instance using your Amazon RDS master user credentials.

2. Create an externally authenticated user in Oracle database. In the following example, replace [e-mail] with the user name and domain name.

   CREATE USER "[e-mail]" IDENTIFIED EXTERNALLY;
   GRANT CREATE SESSION TO "[e-mail]";

3. Users (both humans and applications) from your domain can now connect to the Oracle DB instance from a domain-joined client machine using Kerberos authentication.

Note

A read replica is read-only, so you can't create database users on it. Create externally identified users on the primary DB instance. Amazon RDS replicates them to the read replica, and your AD users can then connect to the read replica with Kerberos authentication.

If a read replica is joined to a different domain than the primary DB instance, create the database user for the read replica's domain principal on the primary DB instance as well. Although that user can't authenticate on the primary DB instance, Amazon RDS replicates the user to the read replica, where the user can authenticate with Kerberos.

Step 3: Configure a Kerberos client

To configure an Oracle client, meet the following requirements:

• Create a configuration file named krb5.conf (Linux, macOS, or Unix) or krb5.ini (Windows) to point to the domain. Configure the Oracle client to use this configuration file.

• Verify that traffic can flow between the client host and your AD domain controllers over DNS port 53 over TCP/UDP, Kerberos ports 88 and 464 over TCP, and LDAP port 389 over TCP.

• Verify that traffic can flow between the client host and the DB instance over the database port.

The following is sample krb5.conf content:

[libdefaults]
 default_realm = CORP.EXAMPLE.COM

[realms]
 CORP.EXAMPLE.COM = {
  kdc = corp.example.com
  admin_server = corp.example.com
 }

[domain_realm]
 .corp.example.com = CORP.EXAMPLE.COM
 corp.example.com = CORP.EXAMPLE.COM

The following is sample sqlnet.ora content for a SQL*Plus configuration:

SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5PRE,KERBEROS5)
SQLNET.KERBEROS5_CONF=path_to_krb5.conf_file
SQLNET.KERBEROS5_CONF_MIT=TRUE

Note

Set SQLNET.KERBEROS5_CONF_MIT=TRUE in the client's sqlnet.ora file when your krb5.conf file uses the MIT Kerberos configuration format, as the preceding example does. This parameter lets the database recognize the Kerberos ticket that MIT kinit cached. Without it, authentication fails even though kinit obtained a valid ticket. For more information about this parameter, see Kerberos, SSL, and RADIUS Authentication Parameters and Configuring Kerberos Authentication in the Oracle Database documentation.

Tip

If you are using a native Windows cache, you can also set the SQLNET.KERBEROS5_CC_NAME parameter to OSMSFT:// or MSLSA in the sqlnet.ora file to use the credentials stored in the Microsoft Active Directory.

Step 4: Connect to your DB instance

To connect with SQL*Plus

1. At a command prompt, obtain a Kerberos ticket. Replace [e-mail] with the AD user and domain name, and enter the AD password at the prompt.

   kinit [e-mail]

2. Open SQL*Plus and connect using the DNS name and port number for the Oracle DB instance. For more information about connecting to an Oracle DB instance in SQL*Plus, see Connecting to your DB instance using SQL*Plus.