Enable Kerberos Authentication with Amazon RDS for Db2

In this post, we illustrate the process of enabling Kerberos-based single sign-on (SSO) in hybrid enterprise environments where centralized identity and access management across self-managed and cloud resources is paramount for safeguarding security and optimizing operational efficiency. We illustrate the process of utilizing Amazon Relational Database Service (Amazon RDS) for Db2 Kerberos authentication capabilities in conjunction with AWS Directory Service and customer managed AD. This collaboration enables the implementation of granular, group-based authorization mechanisms, thereby using your pre-existing Active Directory infrastructure.

Organizations operating hybrid environments can now extend their self-managed Active Directory authentication to Amazon RDS for Db2 instances via a forest trust with AWS Managed Microsoft AD. While basic Kerberos authentication functions transparently in this configuration, implementing group-based access control necessitates specific configuration, particularly when collaborating with users from trusted AD domains. In this post, we show how to enable Amazon RDS for Db2 to allow authorizations of groups in a customer managed Microsoft AD through a Directiry Service domain.

Solution overview

There are several architectural patterns for integrating customer-managed Active Directory with Amazon RDS for Db2 joined to AWS Managed Microsoft AD. Here’s a common pattern:

AWS Environment:

Amazon RDS for Db2 and AWS Managed Microsoft AD are in the same virtual private cloud (VPC) within the same AWS Region.
AWS Managed Microsoft AD can be shared with multiple accounts in another VPC. Refer to Join your Amazon RDS for Db2 instances across accounts to a single shared domain for details.

Customer-Managed AD:

Can be located in AWS or another cloud service, or self-managed in an on-premises data center.
The self-managed customer managed AD is connected to the AWS Cloud through AWS Direct Connect.
Alternatively, a third-party VPN can connect AWS and on-premises data centers.
If in AWS, the customer-managed AD can be in a different Region, VPC, or account.
Customer Applications:
- Domain-joined with customer-managed AD.
- Can run in AWS (same or different account, VPC, or Region), another cloud service, or on premises.
- Connected through AWS Direct Connect or VPN if not in AWS.
- For minimum latency, applications should run in the same VPC and subnet as RDS for Db2.

The following diagram illustrates a prevalent architectural pattern using a customer managed AD with Amazon RDS for Db2, which is domain-joined to AWS Managed Microsoft Active Directory. In this configuration, client applications can be deployed in distinct AWS accounts or self-managed environments. Network connectivity between these components is established using either VPC peering (for connections within AWS) or AWS Direct Connect (for linking to self-managed systems). This architecture empowers you to utilize their existing Active Directory infrastructure for authentication while simultaneously benefiting from the managed database services provided by Amazon RDS for Db2. It offers flexibility in application deployment and network design, accommodating diverse hybrid cloud service scenarios.

Kerberos authentication for Amazon RDS for Db2

Amazon RDS for Db2 supports two Kerberos authentication setups:

Direct integration with AWS Managed Microsoft AD:
1. Applications get Kerberos tickets from AWS Managed AD
2. User and group info stored in AWS Managed AD
3. Applications present service tickets to RDS for Db2
4. RDS for Db2 directly accesses AWS Managed AD for authentication and authorization
Integration with customer-managed Microsoft AD:
1. Applications get Kerberos tickets from customer-managed AD
2. User and group info stored in customer-managed AD
3. One-way forest trust set up between AWS Managed AD and customer-managed AD
4. Applications present customer AD service tickets to RDS for Db2

Both methods allow centralized credential management for multiple DB instances, enhancing overall security. Note that only Kerberos authentication is supported in these configurations, not AD authentication. In the following sections, we demonstrate how to set up Kerberos authentication using your own AD in Amazon RDS for Db2.

Sample scripts

We provide sample scripts that you can download to help set up and test AD integration with Amazon RDS for Db2. For Windows environments, we have a PowerShell script. For Linux environments, we provide Python and shell scripts for group mapping, along with Java and shell scripts for Kerberos authentication testing.

Get-Db2GroupMappings.ps1: This PowerShell script for Windows environments fetches Active Directory group information and generates SQL commands for RDS for Db2 group mapping.
ad_group_mapper.py: A Python script designed to run on Linux systems, querying Active Directory for group details and creating SQL commands for RDS for Db2 group mapping.
ad_group_mapper.sh: A shell script wrapper for the Python ad_group_mapper.py, handling environment setup and execution on Linux systems.
Db2KerberosConnection.java: A Java program that tests Kerberos authentication with an RDS for Db2 instance, useful for validating Kerberos setup.
db2-kerberos-test.sh: A shell script that manages Kerberos tickets and executes the Java Kerberos test program, providing a complete test solution for Linux environments.
jaas.conf: A Java Authentication and Authorization Service (JAAS) configuration file specifying Kerberos settings for the Db2 JDBC driver.

Download sample scripts on Linux/Windows WSL:

curl -sL https://bit.ly/dbblog4756 | bash

You will see an output similar to the following:

[*] Downloaded ad_group_mapper.py successfully.
[*] Downloaded Get-Db2GroupMappings.ps1 successfully.
[*] Downloaded Get-Db2GroupMappings.md successfully.
[*] Downloaded Db2KerberosConnection.java successfully.
[*] Downloaded db2-kerberos-test.sh successfully.
[*] Downloaded jaas.conf successfully.
[*] Downloaded ad_group_mapper.sh successfully.

Download sample scripts on Windows:

curl -sL https://bit.ly/dbblog4756win -o download.cmd
.download.cmd

You will see an output similar to the following:

[*] Successfully downloaded Get-Db2GroupMappings.ps1
[*] Successfully downloaded Get-Db2GroupMappings.md
[*] Successfully downloaded Db2KerberosConnection.java
[*] Successfully downloaded db2-kerberos-test.cmd
[*] Successfully downloaded jaas.conf
[*] Successfully downloaded krb5.ini

The https://bit.ly/dbblog4756 points to: https://aws-blogs-artifacts-public.s3.us-east-1.amazonaws.com/artifacts/DBBLOG-4756/dbblog-4756.sh
The https://bit.ly/dbblog4756win points to https://aws-blogs-artifacts-public.s3.us-east-1.amazonaws.com/artifacts/DBBLOG-4756/dbblog-4756.cmd

Setting up Kerberos authentication through customer managed AD for Amazon RDS for Db2

Here’s how you can set up Kerberos authentication using your own AD in Amazon RDS for Db2.

Prerequisites

Before you begin, make sure you have:

A custom parameter group for RDS with the following properties configured:
- rds.ibm_customer_id: Set to a value obtained from IBM Passport Advantage
- rds.ibm_site_id: Set to a value obtained from IBM Passport Advantage
- To enable feature – “Integration with customer-managed Microsoft AD”, we must set the parameter rds.active_directory_configuration to AWS_MANAGED_AD_WITH_TRUST in a parameter group and then use that parameter group in creating an Amazon RDS for Db2 instance. This feature enables Group authorization from customer-managed AD for Amazon RDS for Db2. If you only use AWS Managed Microsoft AD, then keep this parameter to AWS_MANAGED_AD in your parameter group. The default value does not have any impact on an Amazon RDS for Db2 instance if a directory service is not attached.
An AWS Managed Microsoft AD instance set up in your AWS account.
Access to create an RDS for Db2 instance with the preceding custom parameter group and the ability to specify directory id for attaching it to the AWS Managed Microsoft AD.
Familiarity with the basic steps of creating an RDS instance for a Db2 database.

We expect that readers have already created Amazon RDS for Db2 instance and connected it to a AWS Managed Microsoft AD.

We expect that you have a Db2 client such as an Amazon EC2 which is in the same VPC and can connect to the Amazon RDS for Db2 instance. The same instance should have network access path to self-managed Microsoft AD for this group authorization feature to work.

Establish a one-way forest trust with the customer managed AD

These are the important steps and refer to Creating a trust relationship between your AWS Managed Microsoft AD and self-managed AD for details.

Ensure network connectivity (TCP/UDP ports) are open between both domains.
Share the trust password with customer managed AD team so that they use the same password setting up one way forest trust from their AD to AWS AD.
To set up One-way: Incoming forest trust from the self-managed AD to AWS Managed Microsoft AD, complete the following steps:
Make sure network connectivity (TCP/UDP ports) is open between both domains.
Confirm DNS resolution is in place. The self-managed AD should be able to resolve AWS Managed domain names. Set conditional forwarders if needed.
On a domain controller in the customer managed Microsoft AD, open Active Directory and Domains and Trusts (domain.msc).
Choose your domain (right-click) and choose Properties.
On the Trusts tab, choose New Trust.
Enter the AWS Managed AD domain name and choose Next.
Select External Trust and choose Next.
Choose One-way: Incoming and click Next.
Choose This domain only (because AWS is managed and does not support completing trust from this wizard) and choose Next.
Enter the same trust password that was used by AWS when creating the outgoing trust (you should provide this securely to your AD team), then choose Next.
Choose Forest-wide authentication (recommended if appropriate) or use Selective authentication for tighter control (requires manual permission setup), then choose Next.
Review the settings and choose Finish.
If prompted, validate the trust (optional but recommended if you have connectivity and DNS configured).
Confirm the name resolution between the domains.
Validate the trust with the netdom trust command or from the GUI.
If using Selective authentication, grant Allowed to authenticate permissions to AWS domain users/groups on required resources.
On the Directory Service console for the selected directory, confirm on the Networking & security that the status shows as Verified.

Define mapping for groups in Amazon RDS for Db2

To properly authorize groups from your customer-managed AD in the RDS for Db2 database, follow these steps:

Generate Group Mapping Script
Provide the customer-managed AD team with the Get-Db2GroupMappings.ps1 script. This script generates the syntax for the Db2 stored procedure rdsadmin.SET_SID_GROUP_MAPPING.

Script Usage Options:

Full domain and all groups:
```
.Get-Db2GroupMappings.ps1
```

Groups matching a specific pattern

.Get-Db2GroupMappings.ps1 -GroupNamePattern "testgroup*"

Groups in a specific Organizational Unit (OU):
```
.Get-Db2GroupMappings.ps1 -OU "Users,corp"
```

Combine OU and group pattern:

.Get-Db2GroupMappings.ps1 -OU "Users,corp" -GroupNamePattern "devteam*"

With credentials:

$cred = Get-Credential
.Get-Db2GroupMappings.ps1 -OU "Users,corp" -GroupNamePattern "test*" -Credential $cred

Retrieve Mapping Script
After running the script, the customer-managed AD team should provide you with the generated group_mappings.sql file.

Review and Execute Mappings
The generated group_mappings.sql file will contain statements similar to:

CALL rdsadmin.SET_SID_GROUP_MAPPING(?, 'S-1-5-21-3989957476-2923129746-883028498-3493', 'testgroup1');

To implement these mappings:

Review the SQL statements:
1. Verify that each SET_SID_GROUP_MAPPING call maps the correct SID to the appropriate group name
2. Ensure all required groups are included in the mappings
3. Check that group names match your Db2 authorization design
4. Use a Db2 client to connect to the RDSADMIN database in your RDS for Db2 instance:
```
db2 connect to RDSADMIN <master-user-name> using <master-user-password>
```
5. Run the group_mappings.sql script and log the output:
```
db2 -tvf group_mappings.sql | tee group-mapping.log
```
6. Review the group-mapping.log file for any errors or unexpected results
7. Verify the mappings using following SQL:
```
SELECT * FROM TABLE(SYSPROC.AUTH_LIST_GROUP_MAPPINGS()) AS T
```
8. If needed, remove incorrect mappings using following SQL:
```
CALL rdsadmin.REMOVE_SID_GROUP_MAPPING('S-1-5-21-3989957476-2923129746-883028498-3493')
```

Note: Always backup your mapping configurations and document changes for future reference. Follow your organization’s change management procedures when implementing these mappings.

Test Kerberos authentication through the customer managed AD to Amazon RDS for Db2

To test the Kerberos authentication through your customer-managed AD to Amazon RDS for Db2, you must set up a client machine (Windows or Linux). Keep the following in mind when setting up your Windows or Amazon Linux systems with the customer managed AD:

You must domain join your Windows or Amazon Linux systems with the customer managed AD.
1. For Windows: Follow the guide on domain joining a Windows machine to customer-managed Microsoft AD.
2. For Linux: Use the instructions for domain joining a Linux machine to customer-managed AD.
After your client machine is domain joined, create or modify the Kerberos configuration file:
1. On Linux: /etc/krb5.conf
2. On Windows: C:Windowskrb5.ini
For Java applications on Windows, create a separate krb5.ini file as Java doesn’t use the system default.
The following is a sample krb5.conf that you can reference. Change CORP.COMPANY.COM to the domain name of your customer managed Microsoft AD domain name (maintain uppercase).

[libdefaults]
  default_realm = CORP.COMPANY.COM
  default_ccache_name = /tmp/kerbcache
  allow_weak_crypto = false
  dns_lookup_realm = false
  dns_lookup_kdc = true
  ticket_lifetime = 24h
  renew_lifetime = 7d
  forwardable = true
  rdns = false
  udp_preference_limit = 0

[realms]
  CORP.COMPANY.COM = {
  kdc = corp.company.com
  admin_server = corp.company.com
}
[domain_realm]
  .corp.company.com = CORP.COMPANY.COM
  corp.company.com = CORP.COMPANY.COM
  .rds.amazonaws.com = CORP.COMPANY.COM
  rds.amazonaws.com = CORP.COMPANY.COM

Important Configuration Notes:

The last two entries under the domain_realm section (for rds.amazonaws.com) are required in a forest-trust environment because default RDS endpoint ends with rds.amazonaws.com.
For Java applications on Windows:
- You must set default_ccache_name to a file path on your Windows file system.
- Example: default_ccache_name = C:tempkerbcache
- This is necessary because Java doesn’t use Windows’ built-in Kerberos, but instead relies on Java Authentication and Authorization Service (JAAS).

The following steps illustrate how to test Kerberos authentication against customer managed AD for Amazon RDS for Db2 connections using the sample Java program mentioned in the Sample scripts section:

Set Up AD User and Group
1. Create group testgroup1 in customer-managed AD
2. Create user testuser1 and add to testgroup1
Configure Database Permissions
1. Install Db2 thick client. You can install it on AWS Cloud Shell, refer to Connect to Amazon RDS for Db2 using AWS CloudShell for instructions.
2. for CloudShell installation in the same VPC as RDS for Db2)
3. Connect to database as master user
4. db2 connect to <dbname> user <master-user-name> using <master-user-password>

Grant CONNECT authority to the group testgroup1.

db2 grant connect on database to group testgroup1

Prepare Development Environment
1. Make sure that you have java and javac installed
2. Verify java and javac are available in your PATH variable
Execute Test
1. Review sample Java program Db2KerberosConnection.java.
2. Notice that there are no user name and password defined for the connection property since the authentication is Kerberos ticket based.
3. A connection property securityMechanism of 11 is used to trigger Kerberos authentication.
4. Review the sample shell script db2-kerberos-test.sh which will run the Java program to test the Kerberos authentication to RDS for Db2 using groups from customer managed AD.
5. Modify db2-kerberos-test.sh script to define Amazon RDS for Db2 endpoint (host name), database name and the port.
6. Make the script executable and run it. You will see an output similar to the following:
```
./db2-kerberos-test.sh
```
  The following is the sample output.
```
Compile Java program
Enter user name: testuser1
Enter password:
Enter customer managed AD domain name: corp.company.com
Valid TGT for testuser1@corp.company.com (expires in     546 min)
Run java program
DB2 driver is loaded successfully
Connected to Db2 successfully using Kerberos!
Connection closed.
```
Verify Authentication Flow
The successful connection demonstrates a properly configured end-to-end authentication system. When the test completes successfully, it confirms that Single Sign-On (SSO) is working through Kerberos tickets, and group-based authorization is properly configured through the customer-managed AD. The authentication flow validates that all components are working together: the user credentials are verified against the customer-managed AD, which has a one-way forest trust relationship with AWS Managed Microsoft AD, which in turn is integrated with RDS for Db2. This chain of trust enables authentication without storing credentials in the application, while maintaining secure access control through AD group memberships. The successful test confirms that users can access the RDS for Db2 instance using their AD credentials, using the security of Kerberos protocol and the convenience of SSO.

Troubleshooting

If you encounter issues during the Kerberos authentication setup or testing, follow these steps:

Network Connectivity

Verify DNS resolution: nslookup <domain name> from the client machine
Review security group configurations:
1. Add directory service security group to RDS for Db2 security group (if directory is shared between accounts)
2. Verify required ports are open in the directory service security group
Test DNS resolution from customer-managed AD: nslookup <domain name>
If network issues persist, consult your security team about corporate firewall configurations (such as CheckPoint)

Trust Relationship

Verify trust status:
- Use AWS AD console or aws ds describe-trust command
Check Conditional Forwarders at AWS Managed AD and customer-managed AD level if needed

Shared Directory Setup

If AWS Managed Microsoft AD is shared with the RDS for Db2 account, review Join your Amazon RDS for Db2 instances across accounts to a single shared domain for more details

Java Connection Issues

Enable debugging:

Set debug=true in jaas.conf
Add JVM parameters:
-Djavax.security.auth.debug=true
-Dsun.security.krb5.debug=true
Add these parameters to the shell script running the Java program

Database Permissions

If encountering Db2 SQL1060N error despite correct group grants:

Verify Group SID mapping:
```
CALL rdsadmin.list_sid_group_mapping()
```
Compare results with Group SID in customer-managed AD

To remove incorrect mappings:

CALL rdsadmin.remove_sid_group_mapping('<incorrect_SID>')

Logging and Monitoring

Review Db2 diagnostic logs
Check AWS CloudTrail for AD-related events
Monitor RDS events for authentication-related issues

Kerberos Configuration

validate krb5.conf or krb5.ini configuration
Verify Kerberos ticket validity using command: klist

AD Group Membership

Confirm user is in the correct AD group
Verify group mapping in RDS for Db2

Clean up

After completing your testing, it’s important to properly clean up all AWS resources to avoid incurring unnecessary charges. Begin by removing the RDS for Db2 instance through the RDS console, making sure to take a final snapshot if needed for future reference. Next, delete the AWS Managed Microsoft AD from the Directory Service console, which will automatically remove associated directory configurations.

Conclusion

In this post, we’ve explored how to implement Kerberos-based single sign-on (SSO) for Amazon RDS for Db2 using a customer-managed Microsoft Active Directory (AD) in tandem with AWS Managed Microsoft AD. This solution bridges self-managed identity management with cloud-based database services, offering a seamless and secure authentication experience.

We’ve walked through the process of establishing a one-way forest trust between AWS Managed AD and customer-managed AD, enabling applications to authenticate using Kerberos tickets from the customer-managed AD. A key focus was on enabling group-based authorizations in RDS for Db2 for groups defined in the customer-managed AD, accomplished by configuring the rds.active_directory_configuration parameter.

The solution we’ve presented is flexible, supporting various architectural patterns including self-managed or cloud-based customer-managed AD, connected via AWS Direct Connect or VPN. This approach ensures robust authentication while maintaining centralized credential management, a crucial aspect for many enterprises transitioning to the cloud.

By implementing this solution, you can enhance your database security posture, simplify user access management, and create a more streamlined experience for your users. As you embark on your journey to implement Kerberos SSO with RDS for Db2, remember that AWS Support and our Amazon RDS for Db2 documentation are available to assist you along the way.

We hope this post serves as a valuable resource in your cloud database management toolkit. Happy building!