Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Setting up Kerberos authentication for PostgreSQL DB instances

You use Amazon Directory Service for Microsoft Active Directory (Amazon Managed Microsoft AD) to set up Kerberos authentication for a PostgreSQL DB instance. To set up Kerberos authentication, take the following steps.

Step 1: Create a directory using Amazon Managed Microsoft AD

Amazon Directory Service creates a fully managed Active Directory in the Amazon Cloud. When you create an Amazon Managed Microsoft AD directory, Amazon 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 make sure that your directory remains accessible even if a failure occurs.

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

When you launch Amazon Directory Service for Microsoft Active Directory, Amazon 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 Amazon.

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

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

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 in the directory listing. Make a note of the Directory ID value. You need this value when you create or modify your PostgreSQL DB instance.

Step 2: (Optional) Create a trust relationship between your on-premises Active Directory and Amazon Directory Service

If you don't plan to use your own on-premises Microsoft Active Directory, skip to Step 3: Create an IAM role for Amazon RDS to access the Amazon Directory Service.

To get Kerberos authentication using your on-premises Active Directory, you need to create a trusting domain relationship using a forest trust between your on-premises Microsoft Active Directory and the Amazon Managed Microsoft AD directory (created in Step 1: Create a directory using Amazon Managed Microsoft AD). The trust can be one-way, where the Amazon Managed Microsoft AD directory trusts the on-premises Microsoft Active Directory. The trust can also be two-way, where both Active Directories trust each other. For more information about setting up trusts using Amazon Directory Service, see When to create a trust relationship in the Amazon Directory Service Administration Guide.

Make sure that your on-premises Microsoft Active Directory domain name includes a DNS suffix routing that corresponds to the newly created trust relationship. The following screenshot shows an example.

Step 3: Create an IAM role for Amazon RDS to access the Amazon Directory Service

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

When you create a DB instance using the Amazon Web Services 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 Amazon managed policy AmazonRDSDirectoryServiceAccess to it.

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

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 4: 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 Amazon Directory Service directory, you must be connected to a Windows-based Amazon EC2 instance that's a member of the Amazon Directory Service directory. At the same time, you must be logged in as a user that has privileges to create users. For more information, see Create a user in the Amazon Directory Service Administration Guide.

Step 5: Enable cross-VPC traffic between the directory and the DB instance

If you plan to locate the directory and the DB instance in the same VPC, skip this step and move on to Step 6: Create or modify a PostgreSQL DB instance.

If you plan to locate the directory and the DB instance in different VPCs, configure cross-VPC traffic using VPC peering or Amazon Transit Gateway.

The following procedure enables traffic between VPCs using VPC peering. Follow the instructions in What is VPC peering? in the Amazon Virtual Private Cloud Peering Guide.

If a different Amazon account owns the directory, you must share the directory.

Step 6: Create or modify a PostgreSQL DB instance

Create or modify a PostgreSQL DB instance for use with your directory. You can use the console, CLI, or 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 PostgreSQL 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.

Step 7: Create PostgreSQL users for your Kerberos principals

At this point, your RDS for PostgreSQL DB instance is joined to the Amazon Managed Microsoft AD domain. The users that you created in the directory in Step 4: Create and configure users need to be set up as PostgreSQL database users and granted privileges to login to the database. You do that by signing in as the database user with rds_superuser privileges. For example, if you accepted the defaults when you created your RDS for PostgreSQL DB instance, you use postgres, as shown in the following steps.

After you finish creating all the PostgreSQL users for your Active Directory user identities, users can access the RDS for PostgreSQL DB instance by using their Kerberos credentials.

It's assumed that the database users who authenticate using Kerberos are doing so from client machines that are members of the Active Directory domain.

Database users that have been granted the rds_ad role can't also have the rds_iam role. This also applies to nested memberships. For more information, see IAM database authentication for MariaDB, MySQL, and PostgreSQL.

Step 8: Configure a PostgreSQL client

To configure a PostgreSQL client, take the following steps:

The following is sample krb5.conf content for Amazon 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

The following is sample krb5.conf content for an on-premises Microsoft Active Directory.

[libdefaults]
 default_realm = EXAMPLE.COM
[realms]
 EXAMPLE.COM = {
  kdc = example.com
  admin_server = example.com
 }
 ONPREM.COM = {
  kdc = onprem.com
  admin_server = onprem.com
 }
[domain_realm]
 .example.com = EXAMPLE.COM
 example.com = EXAMPLE.COM
 .onprem.com = ONPREM.COM
 onprem.com = ONPREM.COM  
 .rds.amazonaws.com = EXAMPLE.COM
 .amazonaws.com.cn = EXAMPLE.COM
 .amazon.com = EXAMPLE.COM