Using Kerberos authentication for Amazon RDS for Db2 - Amazon Relational Database Service
Region and version availabilityOverview of Kerberos authentication for DB instancesSetting up Kerberos authentication for DB instancesManaging a DB instance in a domainConnecting with Kerberos authentication

Using Kerberos authentication for Amazon RDS for Db2

You can use Kerberos authentication to authenticate users when they connect to your Amazon RDS for Db2 DB instance. Your DB instance works with AWS Directory Service for Microsoft Active Directory (AWS Managed Microsoft AD) to enable Kerberos authentication. When users authenticate with an RDS for Db2 DB instance joined to the trusting domain, authentication requests are forwarded to the directory that you create with AWS Directory Service. For more information, see What is AWS Directory Service? in the AWS Directory Service Administration Guide.

First, create an AWS Managed Microsoft AD directory to store user credentials. Then, add the domain and other information of your AWS Managed Microsoft AD directory to your RDS for Db2 DB instance. When users authenticate with the RDS for Db2 DB instance, authentication requests are forwarded to the AWS Managed Microsoft AD directory.

Keeping all of your credentials in the same directory can save you time and effort. With this approach, you have a centralized place for storing and managing credentials for multiple DB instances. Using a directory can also improve your overall security profile.

Region and version availability

Feature availability and support varies across specific versions of each database engine, and across AWS Regions. For more information about version and Region availability of RDS for Db2 with Kerberos authentication, see Supported Regions and DB engines for Kerberos authentication in Amazon RDS.

Note

Kerberos authentication isn't supported for DB instance classes that are deprecated for RDS for Db2 DB instances. For more information, see Amazon RDS for Db2 instance classes.

Overview of Kerberos authentication for RDS for Db2 DB instances

To set up Kerberos authentication for an RDS for Db2 DB instance, complete the following general steps, which are described in more detail later:

  1. Use AWS Managed Microsoft AD to create an AWS Managed Microsoft AD directory. You can use the AWS Management Console, the AWS Command Line Interface (AWS CLI), or AWS Directory Service to create the directory. For more information, see Create your AWS Managed Microsoft AD directory in the AWS Directory Service Administration Guide.

  2. Create an AWS Identity and Access Management (IAM) role that uses the managed IAM policy AmazonRDSDirectoryServiceAccess. The IAM role allows Amazon RDS to make calls to your directory.

    For the IAM role to allow access, the AWS Security Token Service (AWS STS) endpoint must be activated in the correct AWS Region for your AWS account. AWS STS endpoints are active by default in all AWS Regions, and you can use them without any further actions. For more information, see Activating and deactivating AWS STS in an AWS Region in the IAM User Guide.

  3. Create or modify an RDS for Db2 DB instance by using the AWS Management Console, the AWS CLI, or the RDS API with one of the following methods:

    You can locate the DB instance in the same Amazon Virtual Private Cloud (VPC) as the directory or in a different AWS account or VPC. When you create or modify the RDS for Db2 DB instance, do the following tasks:

    • Provide the domain identifier (d-* identifier) that was generated when you created your directory.

    • Provide the name of the IAM role that you created.

    • Verify that the DB instance security group can receive inbound traffic from the directory security group.

  4. Configure your Db2 client, and verify that traffic can flow between the client host and AWS Directory Service for the following ports:

    • TCP/UDP port 53 – DNS

    • TCP 88 – Kerberos authentication

    • TCP 389 – LDAP

    • TCP 464 – Kerberos authentication

Setting up Kerberos authentication for RDS for Db2 DB instances

You use AWS Directory Service for Microsoft Active Directory (AWS Managed Microsoft AD) to set up Kerberos authentication for an RDS for Db2 DB instance. To set up Kerberos authentication, follow these steps:

Step 1: Create a directory using AWS Managed Microsoft AD

AWS Directory Service creates a fully managed Active Directory in the AWS Cloud. When you create an AWS Managed Microsoft AD directory, AWS Directory Service creates two domain controllers and DNS servers for you. The directory servers are created in different subnets in a VPC. This redundancy helps ensure that your directory remains accessible even if a failure occurs.

When you create an AWS Managed Microsoft AD directory, AWS Directory Service performs the following tasks on your behalf:

  • Sets up an Active Directory within your VPC.

  • Creates a directory administrator account with the username Admin and the specified password. You use this account to manage your directory.

    Important

    Make sure to save this password. AWS Directory Service doesn't store this password, and it can't be retrieved or reset.

  • Creates a security group for the directory controllers. The security group must permit communication with the RDS for Db2 DB instance.

When you launch AWS Directory Service for Microsoft Active Directory, AWS creates an organizational unit (OU) that contains all of your directory's objects. This OU, which has the NetBIOS name that you entered when you created your directory, is located in the domain root. The domain root is owned and managed by AWS.

The Admin account that was created with your AWS Managed Microsoft AD directory has permissions for the most common administrative activities for your OU:

  • Create, update, or delete users.

  • Add resources to your domain such as file or print servers, and then assign permissions for those resources to users in your OU.

  • Create additional OUs and containers.

  • Delegate authority.

  • Restore deleted objects from the Active Directory Recycle Bin.

  • Run Active Directory and Domain Name Service (DNS) modules for Windows PowerShell on the AWS Directory Service.

The Admin account also has rights to perform the following domain-wide activities:

  • Manage DNS configurations (add, remove, or update records, zones, and forwarders).

  • View DNS event logs.

  • View security event logs.

To create a directory with AWS Managed Microsoft AD

  1. Sign in to the AWS Management Console and open the AWS Directory Service console at https://console.aws.amazon.com/directoryservicev2/.

  2. Choose Set up directory.

  3. Choose AWS Managed Microsoft AD. AWS Managed Microsoft AD is the only option currently supported for use with Amazon RDS.

  4. Choose Next.

  5. On the Enter directory information page, provide the following information:

    • Edition – Choose the edition that meets your requirements.

    • Directory DNS name – The fully qualified name for the directory, such as corp.example.com.

    • Directory NetBIOS name – An optional short name for the directory, such as CORP.

    • Directory description – An optional description for the directory.

    • Admin password – The password for the directory administrator. The directory creation process creates an administrator account with the username Admin and this password.

      The directory administrator password can't include the word "admin." The password is case-sensitive and must be 8–64 characters in length. It must also contain at least one character from three of the following four categories:

      • Lowercase letters (a–z)

      • Uppercase letters (A–Z)

      • Numbers (0–9)

      • Nonalphanumeric characters (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/)

      • Confirm password – Retype the administrator password.

        Important

        Make sure that you save this password. AWS Directory Service doesn't store this password, and it can't be retrieved or reset.

  6. Choose Next.

  7. On the Choose VPC and subnets page, provide the following information:

    • VPC – Choose the VPC for the directory. You can create the RDS for Db2 DB instance in this same VPC or in a different VPC.

    • Subnets – Choose the subnets for the directory servers. The two subnets must be in different Availability Zones.

  8. Choose Next.

  9. Review the directory information. If changes are needed, choose Previous and make the changes. When the information is correct, choose Create directory.

    The Review & create window during directory creation in the AWS Directory Service console.

It takes several minutes for the directory to be created. When it has been successfully created, the Status value changes to Active.

To see information about your directory, choose the directory ID under Directory ID. Make a note of the Directory ID value. You need this value when you create or modify your RDS for Db2 DB instance.

The Directory details section with Directory ID in the AWS Directory Service console.

Step 2: Create an IAM role for Amazon RDS to access AWS Directory Service

For Amazon RDS to call AWS Directory Service for you, your AWS account needs an IAM role that uses the managed IAM policy AmazonRDSDirectoryServiceAccess. This role allows Amazon RDS to make calls to AWS Directory Service.

When you create a DB instance using the AWS Management Console and your console user account has the iam:CreateRole permission, the console creates the needed IAM role automatically. In this case, the role name is rds-directoryservice-kerberos-access-role. Otherwise, you must create the IAM role manually. When you create this IAM role, choose Directory Service, and attach the AWS managed policy AmazonRDSDirectoryServiceAccess to it.

For more information about creating IAM roles for a service, see Creating a role to delegate permissions to an AWS service in the IAM User Guide.

Note

The IAM role used for Windows Authentication for RDS for Microsoft SQL Server can't be used for RDS for Db2.

As an alternative to using the AmazonRDSDirectoryServiceAccess managed policy, you can create policies with the required permissions. In this case, the IAM role must have the following IAM trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "directoryservice.rds.amazonaws.com",
          "rds.amazonaws.com"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

The role must also have the following IAM role policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ds:DescribeDirectories",
        "ds:AuthorizeApplication",
        "ds:UnauthorizeApplication",
        "ds:GetAuthorizedApplicationDetails"
      ],
    "Effect": "Allow",
    "Resource": "*"
    }
  ]
}

Step 3: Create and configure users

You can create users by using the Active Directory Users and Computers tool. This is one of the Active Directory Domain Services and Active Directory Lightweight Directory Services tools. For more information, see Add Users and Computers to the Active Directory domain in the Microsoft documentation. In this case, users are individuals or other entities, such as their computers, that are part of the domain and whose identities are being maintained in the directory.

To create users in an AWS Directory Service directory, you must be connected to a Windows-based Amazon EC2 instance that's a member of the AWS Directory Service directory. At the same time, you must be signed in as a user that has privileges to create users. For more information, see Create a user in the AWS Directory Service Administration Guide.

Step 4: Create an RDS for Db2 admin group in AWS Managed Microsoft AD

RDS for Db2 doesn't support Kerberos authentication for the master user or the two Amazon RDS reserved users rdsdb and rdsadmin. Instead, you need to create a new group called masterdba in AWS Managed Microsoft AD. For more information, see Create a Group Account in Active Directory in the Microsoft documentation. Any users that you add to this group will have master user privileges.

After you enable Kerberos authentication, the master user loses the masterdba role. As a result, the master user won't be able to access the instance local user group membership unless you disable Kerberos authentication. To continue to use the master user with password login, create a user on AWS Managed Microsoft AD with the same name as the master user. Then, add that user to the group masterdba.

Step 5: Create or modify an RDS for Db2 DB instance

Create or modify an RDS for Db2 DB instance for use with your directory. You can use the AWS Management Console, the AWS CLI, or the RDS API to associate a DB instance with a directory. You can do this in one of the following ways:

Kerberos authentication is only supported for RDS for Db2 DB instances in a VPC. The DB instance can be in the same VPC as the directory, or in a different VPC. The DB instance must use a security group that allows ingress and egress within the directory's VPC so the DB instance can communicate with the directory.

When you use the console to create, modify, or restore a DB instance, choose Password and Kerberos authentication in the Database authentication section. Then choose Browse Directory. Select the directory or choose Create directory to use the Directory Service.

The Databate authentication section with Password and Kerberos authentication selected in the Amazon RDS console.

When you use the AWS CLI, the following parameters are required for the DB instance to be able to use the directory that you created:

  • For the --domain parameter, use the domain identifier ("d-*" identifier) generated when you created the directory.

  • For the --domain-iam-role-name parameter, use the role you created that uses the managed IAM policy AmazonRDSDirectoryServiceAccess.

The following example modifies a DB instance to use a directory. Replace the following placeholders in the example with your own values:

  • db_instance_name – The name of your RDS for Db2 DB instance.

  • directory_id – The ID of the AWS Directory Service for Microsoft Active Directory directory that you created.

  • role_name – The name of the IAM role that you created.

aws rds modify-db-instance --db-instance-identifier db_instance_name --domain d-directory_id --domain-iam-role-name role_name
Important

If you modify a DB instance to enable Kerberos authentication, reboot the DB instance after making the change.

Step 6: Configure a Db2 client

To configure a Db2 client

  1. Create an /etc/krb5.conf file (or equivalent) to point to the domain.

    Note

    For Windows operating systems, create a C:\windows\krb5.ini file.

  2. Verify that traffic can flow between the client host and AWS Directory Service. Use a network utility such as Netcat for the following tasks:

    1. Verify traffic over DNS for port 53.

    2. Verify traffic over TCP/UDP for port 53 and for Kerberos, which includes ports 88 and 464 for AWS Directory Service.

  3. Verify that traffic can flow between the client host and the DB instance over the database port. You can use the command db2 to connect and access the database.

The following example is /etc/krb5.conf file content for AWS Managed Microsoft AD:

[libdefaults]
default_realm = EXAMPLE.COM
[realms]
EXAMPLE.COM = {
kdc = example.com
admin_server = example.com
}
[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM

Managing a DB instance in a domain

You can use the AWS Management Console, the AWS CLI, or the RDS API to manage your DB instance and its relationship with your Microsoft Active Directory. For example, you can associate an Active Directory to enable Kerberos authentication. You can also remove the association for an Active Directory to disable Kerberos authentication. You can also move a DB instance to be externally authenticated by one Microsoft Active Directory to another.

For example, using the modify-db-instance CLI command, you can perform the following actions:

  • Re-attempt enabling Kerberos authentication for a failed membership by specifying the current membership's directory ID for the --domain option.

  • Disable Kerberos authentication on a DB instance by specifying none for the --domain option.

  • Move a DB instance from one domain to another by specifying the domain identifier of the new domain for the --domain option.

Understanding domain membership

After you create or modify your DB instance, it becomes a member of the domain. You can view the status of the domain membership in the console or by running the describe-db-instances command. The status of the DB instance can be one of the following:

  • kerberos-enabled – The DB instance has Kerberos authentication enabled.

  • enabling-kerberos – AWS is in the process of enabling Kerberos authentication on this DB instance.

  • pending-enable-kerberos – Enabling Kerberos authentication is pending on this DB instance.

  • pending-maintenance-enable-kerberos – AWS will attempt to enable Kerberos authentication on the DB instance during the next scheduled maintenance window.

  • pending-disable-kerberos – Disabling Kerberos authentication is pending on this DB instance.

  • pending-maintenance-disable-kerberos – AWS will attempt to disable Kerberos authentication on the DB instance during the next scheduled maintenance window.

  • enable-kerberos-failed – A configuration problem prevented AWS from enabling Kerberos authentication on the DB instance. Correct the configuration problem before re-issuing the command to modify the DB instance.

  • disabling-kerberos – AWS is in the process of disabling Kerberos authentication on this DB instance.

A request to enable Kerberos authentication can fail because of a network connectivity issue or an incorrect IAM role. In some cases, the attempt to enable Kerberos authentication might fail when you create or modify a DB instance. If this happens, verify that you are using the correct IAM role, and then modify the DB instance to join the domain.

Connecting to RDS for Db2 with Kerberos authentication

To connect to RDS for Db2 with Kerberos authentication

  1. At a command prompt, run the following command. In the following example, replace username with your Microsoft Active Directory username.

    kinit username

  2. If the RDS for Db2 DB instance is using a publicly accessible VPC, add the IP address for your DB instance endpoint to your /etc/hosts file on the Amazon EC2 client. The following example obtains the IP address and then adds it to the /etc/hosts file.

    % dig +short Db2-endpoint.AWS-Region.rds.amazonaws.com  
;; Truncated, retrying in TCP mode.
ec2-34-210-197-118.AWS-Region.compute.amazonaws.com.
34.210.197.118 

% echo "34.210.197.118  Db2-endpoint.AWS-Region.rds.amazonaws.com" >> /etc/hosts

  3. Use the following command to log in to an RDS for Db2 DB instance that is associated with Active Directory. Replace database_name with the name of your RDS for Db2 database.

    db2 connect to database_name