# Using Kerberos authentication for Aurora MySQL You can use Kerberos authentication to authenticate users when they connect to your Aurora MySQL DB cluster. To do so, configure your DB cluster to use AWS Directory Service for Microsoft Active Directory for Kerberos authentication. AWS Directory Service for Microsoft Active Directory is also called AWS Managed Microsoft AD. It's a feature available with Directory Service. To learn more, see [What is Directory Service?](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/what_is.html) in the *AWS Directory Service Administration Guide*. To start, create an AWS Managed Microsoft AD directory to store user credentials. Then, provide the Active Directory's domain and other information to your Aurora MySQL DB cluster. When users authenticate with the Aurora MySQL DB cluster, 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 location for storing and managing credentials for multiple DB clusters. Using a directory can also improve your overall security profile. In addition, you can access credentials from your own on-premises Microsoft Active Directory. To do so, create a trusting domain relationship so that the AWS Managed Microsoft AD directory trusts your on-premises Microsoft Active Directory. In this way, your users can access your Aurora MySQL DB clusters with the same Windows single sign-on (SSO) experience as when they access workloads in your on-premises network. A database can use Kerberos, AWS Identity and Access Management (IAM), or both Kerberos and IAM authentication. However, because Kerberos and IAM authentication provide different authentication methods, a specific user can log in to a database using only one or the other authentication method, but not both. For more information about IAM authentication, see [IAM database authentication ](UsingWithRDS.IAMDBAuth.md). **Contents** + [Overview of Kerberos authentication for Aurora MySQL DB clusters](#aurora-mysql-kerberos-setting-up-overview) + [Limitations of Kerberos authentication for Aurora MySQL](#aurora-mysql-kerberos.limitations) + [Setting up Kerberos authentication for Aurora MySQL DB clusters](aurora-mysql-kerberos-setting-up.md) + [Step 1: Create a directory using AWS Managed Microsoft AD](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-directory) + [Step 2: (Optional) Create a trust for an on-premises Active Directory](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-trust) + [Step 3: Create an IAM role for use by Amazon Aurora](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.CreateIAMRole) + [Step 4: Create and configure users](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-users) + [Step 5: Create or modify an Aurora MySQL DB cluster](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-modify) + [Step 6: Create Aurora MySQL users that use Kerberos authentication](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-logins) + [Modifying an existing Aurora MySQL login](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos.modify-login) + [Step 7: Configure a MySQL client](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.configure-client) + [Step 8: (Optional) Configure case-insensitive username comparison](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.case-insensitive) + [Connecting to Aurora MySQL with Kerberos authentication](aurora-mysql-kerberos-connecting.md) + [Using the Aurora MySQL Kerberos login to connect to the DB cluster](aurora-mysql-kerberos-connecting.md#aurora-mysql-kerberos-connecting.login) + [Kerberos authentication with Aurora global databases](aurora-mysql-kerberos-connecting.md#aurora-mysql-kerberos-connecting.global) + [Migrating from RDS for MySQL to Aurora MySQL](aurora-mysql-kerberos-connecting.md#aurora-mysql-kerberos-connecting.rds) + [Preventing ticket caching](aurora-mysql-kerberos-connecting.md#aurora-mysql-kerberos.destroy-tickets) + [Logging for Kerberos authentication](aurora-mysql-kerberos-connecting.md#aurora-mysql-kerberos.logging) + [Managing a DB cluster in a domain](aurora-mysql-kerberos-managing.md) + [Understanding domain membership](aurora-mysql-kerberos-managing.md#aurora-mysql-kerberos-managing.understanding) ## Overview of Kerberos authentication for Aurora MySQL DB clusters To set up Kerberos authentication for an Aurora MySQL DB cluster, complete the following general steps. These steps 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 CLI, or the Directory Service to create the directory. For detailed instructions, see [Create your AWS Managed Microsoft AD directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started_create_directory.html) in the *AWS Directory Service Administration Guide*. 1. Create an AWS Identity and Access Management (IAM) role that uses the managed IAM policy `AmazonRDSDirectoryServiceAccess`. The role allows Amazon Aurora to make calls to your directory. For the role to allow access, the AWS Security Token Service (AWS STS) endpoint must be activated in the 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 action. For more information, see [ Activating and deactivating AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate) in the *IAM User Guide*. 1. Create and configure users in the AWS Managed Microsoft AD directory using the Microsoft Active Directory tools. For more information about creating users in your Active Directory, see [Manage users and groups in AWS managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_manage_users_groups.html) in the *AWS Directory Service Administration Guide*. 1. Create or modify an Aurora MySQL DB cluster. If you use either the CLI or RDS API in the create request, specify a domain identifier with the `Domain` parameter. Use the `d-*` identifier that was generated when you created your directory and the name of the IAM role that you created. If you modify an existing Aurora MySQL DB cluster to use Kerberos authentication, set the domain and IAM role parameters for the DB cluster. Locate the DB cluster in the same VPC as the domain directory. 1. Use the Amazon RDS primary user credentials to connect to the Aurora MySQL DB cluster. Create the database user in Aurora MySQL by using the instructions in [Step 6: Create Aurora MySQL users that use Kerberos authentication](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-logins). Users that you create this way can log in to the Aurora MySQL DB cluster using Kerberos authentication. For more information, see [Connecting to Aurora MySQL with Kerberos authentication](aurora-mysql-kerberos-connecting.md). To use Kerberos authentication with an on-premises or self-hosted Microsoft Active Directory, create a *forest trust*. A forest trust is a trust relationship between two groups of domains. The trust can be one-way or two-way. For more information about setting up forest trusts using Directory Service, see [When to create a trust relationship](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_setup_trust.html) in the *AWS Directory Service Administration Guide*. ## Limitations of Kerberos authentication for Aurora MySQL The following limitations apply to Kerberos authentication for Aurora MySQL: + Kerberos authentication is supported for Aurora MySQL version 3.03 and higher. For information about AWS Region support, see [Kerberos authentication with Aurora MySQL](Concepts.Aurora_Fea_Regions_DB-eng.Feature.KerberosAuthentication.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.KerberosAuthentication.amy). + To use Kerberos authentication with Aurora MySQL, your MySQL client or connector must use version 8.0.26 or higher on Unix platforms, 8.0.27 or higher on Windows. Otherwise, the client-side `authentication_kerberos_client` plugin isn't available and you can't authenticate. + Only AWS Managed Microsoft AD is supported on Aurora MySQL. However, you can join Aurora MySQL DB clusters to shared Managed Microsoft AD domains owned by different accounts in the same AWS Region. You can also use your own on-premises Active Directory. For more information, see [Step 2: (Optional) Create a trust for an on-premises Active Directory](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-trust). + When using Kerberos to authenticate a user connecting to the Aurora MySQL cluster from MySQL clients or from drivers on the Windows operating system, by default the character case of the database username must match the case of the user in the Active Directory. For example, if the user in the Active Directory appears as `Admin`, the database username must be `Admin`. However, you can now use case-insensitive username comparison with the `authentication_kerberos` plugin. For more information, see [Step 8: (Optional) Configure case-insensitive username comparison](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.case-insensitive). + You must reboot the reader DB instances after turning on the feature to install the `authentication_kerberos` plugin. + Replicating to DB instances that don't support the `authentication_kerberos` plugin can lead to replication failure. + For Aurora global databases to use Kerberos authentication, you must configure it for every DB cluster in the global database. + The domain name must be less than 62 characters long. + Don't modify the DB cluster port after turning on Kerberos authentication. If you modify the port, then Kerberos authentication will no longer work. # Setting up Kerberos authentication for Aurora MySQL DB clusters Use AWS Managed Microsoft AD to set up Kerberos authentication for an Aurora MySQL DB cluster. To set up Kerberos authentication, take the following steps. **Topics** + [Step 1: Create a directory using AWS Managed Microsoft AD](#aurora-mysql-kerberos-setting-up.create-directory) + [Step 2: (Optional) Create a trust for an on-premises Active Directory](#aurora-mysql-kerberos-setting-up.create-trust) + [Step 3: Create an IAM role for use by Amazon Aurora](#aurora-mysql-kerberos-setting-up.CreateIAMRole) + [Step 4: Create and configure users](#aurora-mysql-kerberos-setting-up.create-users) + [Step 5: Create or modify an Aurora MySQL DB cluster](#aurora-mysql-kerberos-setting-up.create-modify) + [Step 6: Create Aurora MySQL users that use Kerberos authentication](#aurora-mysql-kerberos-setting-up.create-logins) + [Step 7: Configure a MySQL client](#aurora-mysql-kerberos-setting-up.configure-client) + [Step 8: (Optional) Configure case-insensitive username comparison](#aurora-mysql-kerberos-setting-up.case-insensitive) ## Step 1: Create a directory using AWS Managed Microsoft AD Directory Service creates a fully managed Active Directory in the AWS Cloud. When you create an AWS Managed Microsoft AD directory, Directory Service creates two domain controllers and Domain Name System (DNS) servers on your behalf. 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 AWS Managed Microsoft AD directory, Directory Service performs the following tasks on your behalf: + Sets up an Active Directory within the VPC. + Creates a directory administrator account with the username `Admin` and the specified password. You use this account to manage your directory. **Note** Be sure to save this password. Directory Service doesn't store it. You can reset it, but you can't retrieve it. + Creates a security group for the directory controllers. When you launch an AWS Managed Microsoft AD, AWS creates an Organizational Unit (OU) that contains all of your directory's objects. This OU has the NetBIOS name that you entered when you created your directory. It is located in the domain root, which 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, including: + 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 AD and DNS Windows PowerShell modules on the Active Directory Web 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 Directory Service console at [https://console.aws.amazon.com/directoryservicev2/](https://console.aws.amazon.com/directoryservicev2/). 1. In the navigation pane, choose **Directories** and choose **Set up Directory**. 1. Choose **AWS Managed Microsoft AD**. AWS Managed Microsoft AD is the only option that you can currently use with Amazon RDS. 1. Enter the following information: **Directory DNS name** The fully qualified name for the directory, such as **corp.example.com**. **Directory NetBIOS name** The short name for the directory, such as **CORP**. **Directory description** (Optional) A 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 and 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) + Non-alphanumeric characters (\$1\$1@\$1\$1%^&\$1\$1-\$1=`\$1\$1()\$1\$1[]:;"'<>,.?/) **Confirm password** The administrator password re-entered. 1. Choose **Next**. 1. Enter the following information in the **Networking** section and then choose **Next**: **VPC** The VPC for the directory. Create the Aurora MySQL DB cluster in this same VPC. **Subnets** Subnets for the directory servers. The two subnets must be in different Availability Zones. 1. Review the directory information and make any necessary changes. When the information is correct, choose **Create directory**. ![\[Directory details page during creation\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/WinAuth2.png) It takes several minutes to create the directory. When it has been successfully created, the **Status** value changes to **Active**. To see information about your directory, choose the directory name in the directory listing. Note the **Directory ID** value because you need this value when you create or modify your Aurora MySQL DB cluster. ![\[Directory ID in the Directory details page\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/WinAuth3.png) ## Step 2: (Optional) Create a trust for an on-premises Active Directory If you don't plan to use your own on-premises Microsoft Active Directory, skip to [Step 3: Create an IAM role for use by Amazon Aurora](#aurora-mysql-kerberos-setting-up.CreateIAMRole). To use Kerberos authentication with 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 AWS Managed Microsoft AD directory (created in [Step 1: Create a directory using AWS Managed Microsoft AD](#aurora-mysql-kerberos-setting-up.create-directory)). The trust can be one-way, where the AWS 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 Directory Service, see [When to create a trust relationship](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_setup_trust.html) in the *AWS Directory Service Administration Guide*. **Note** If you use an on-premises Microsoft Active Directory: Windows clients can't connect using Aurora custom endpoints. To learn more, see [Amazon Aurora endpoint connections](Aurora.Overview.Endpoints.md). For [global databases](aurora-global-database.md): Windows clients can connect using instance endpoints or cluster endpoints in the primary AWS Region of the global database only. Windows clients can't connect using cluster endpoints in secondary AWS Regions. 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. ![\[DNS routing corresponds to the created trust\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/kerberos-auth-trust.png) ## Step 3: Create an IAM role for use by Amazon Aurora For Amazon Aurora to call Directory Service for you, you need an AWS Identity and Access Management (IAM) role that uses the managed IAM policy `AmazonRDSDirectoryServiceAccess`. This role allows Aurora to make calls to the Directory Service. When you create a DB cluster using the AWS Management Console, and you have the `iam:CreateRole` permission, the console creates this 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*. Optionally, you can create policies with the required permissions instead of using the managed IAM policy `AmazonRDSDirectoryServiceAccess`. In this case, the IAM role must have the following IAM trust policy. ------ #### [ JSON ] **** ``` { "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. ------ #### [ JSON ] **** ``` { "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 with the Active Directory Users and Computers tool. This tool is part of the Active Directory Domain Services and Active Directory Lightweight Directory Services tools. Users represent individual people or entities that have access to your directory. To create users in an Directory Service directory, you use an on-premises or Amazon EC2 instance based on Microsoft Windows that is joined to your Directory Service directory. You must be logged in to the instance as a user that has privileges to create users. For more information, see [Manage users and groups in AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/creating_ad_users_and_groups.html) in the *AWS Directory Service Administration Guide*. ## Step 5: Create or modify an Aurora MySQL DB cluster Create or modify an Aurora MySQL DB cluster for use with your directory. You can use the console, AWS CLI, or RDS API to associate a DB cluster with a directory. You can do this task in one of the following ways: + Create a new Aurora MySQL DB cluster using the console, the [ create-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html) CLI command, or the [CreateDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html) RDS API operation. For instructions, see [Creating an Amazon Aurora DB cluster](Aurora.CreateInstance.md). + Modify an existing Aurora MySQL DB cluster using the console, the [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) CLI command, or the [ModifyDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) RDS API operation. For instructions, see [Modifying an Amazon Aurora DB cluster](Aurora.Modifying.md). + Restore an Aurora MySQL DB cluster from a DB snapshot using the console, the [restore-db-cluster-from-snapshot](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-cluster-from-snapshot.html) CLI command, or the [RestoreDBClusterFromSnapshot](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBClusterFromSnapshot.html) RDS API operation. For instructions, see [Restoring from a DB cluster snapshot](aurora-restore-snapshot.md). + Restore an Aurora MySQL DB cluster to a point-in-time using the console, the [ restore-db-cluster-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-cluster-to-point-in-time.html) CLI command, or the [RestoreDBClusterToPointInTime](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBClusterToPointInTime.html) RDS API operation. For instructions, see [Restoring a DB cluster to a specified time](aurora-pitr.md). Kerberos authentication is only supported for Aurora MySQL DB clusters in a VPC. The DB cluster can be in the same VPC as the directory, or in a different VPC. The DB cluster's VPC must have a VPC security group that allows outbound communication to your directory. ### Console When you use the console to create, modify, or restore a DB cluster, choose **Kerberos authentication** in the **Database authentication** section. Choose **Browse Directory** and then select the directory, or choose **Create a new directory**. ![\[Kerberos authentication setting when creating a DB cluster\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/kerberos-auth-create-cluster.png) ### AWS CLI When you use the AWS CLI or RDS API, associate a DB cluster with a directory. The following parameters are required for the DB cluster to use the domain directory you created: + For the `--domain` parameter, use the domain identifier ("d-\$1" 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`. For example, the following CLI command modifies a DB cluster to use a directory. For Linux, macOS, or Unix: ``` aws rds modify-db-cluster \ --db-cluster-identifier mydbcluster \ --domain d-ID \ --domain-iam-role-name role-name ``` For Windows: ``` aws rds modify-db-cluster ^ --db-cluster-identifier mydbcluster ^ --domain d-ID ^ --domain-iam-role-name role-name ``` **Important** If you modify a DB cluster to turn on Kerberos authentication, reboot the reader DB instances after making the change. ## Step 6: Create Aurora MySQL users that use Kerberos authentication The DB cluster is joined to the AWS Managed Microsoft AD domain. Thus, you can create Aurora MySQL users from the Active Directory users in your domain. Database permissions are managed through standard Aurora MySQL permissions that are granted to and revoked from these users. You can allow an Active Directory user to authenticate with Aurora MySQL. To do this, first use the Amazon RDS primary user credentials to connect to the Aurora MySQL DB cluster as with any other DB cluster. After you're logged in, create an externally authenticated user with Kerberos authentication in Aurora MySQL as shown here: ``` CREATE USER user_name@'host_name' IDENTIFIED WITH 'authentication_kerberos' BY 'realm_name'; ``` + Replace `user_name` with the username. Users (both humans and applications) from your domain can now connect to the DB cluster from a domain-joined client machine using Kerberos authentication. + Replace `host_name` with the hostname. You can use `%` as a wild card. You can also use specific IP addresses for the hostname. + Replace *realm\$1name* with the directory realm name of the domain. The realm name is usually the same as the DNS domain name in uppercase letters, such as `CORP.EXAMPLE.COM`. A realm is a group of systems that use the same Kerberos Key Distribution Center. The following example creates a database user with the name `Admin` that authenticates against the Active Directory with the realm name `MYSQL.LOCAL`. ``` CREATE USER Admin@'%' IDENTIFIED WITH 'authentication_kerberos' BY 'MYSQL.LOCAL'; ``` ### Modifying an existing Aurora MySQL login You can also modify an existing Aurora MySQL login to use Kerberos authentication by using the following syntax: ``` ALTER USER user_name IDENTIFIED WITH 'authentication_kerberos' BY 'realm_name'; ``` ## Step 7: Configure a MySQL client To configure a MySQL client, take the following steps: 1. Create a `krb5.conf` file (or equivalent) to point to the domain. 1. Verify that traffic can flow between the client host and Directory Service. Use a network utility such as Netcat, for the following: + Verify traffic over DNS for port 53. + Verify traffic over TCP/UDP for port 53 and for Kerberos, which includes ports 88 and 464 for Directory Service. 1. Verify that traffic can flow between the client host and the DB instance over the database port. For example, use `mysql` to connect and access the database. The following is sample `krb5.conf` 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 ``` 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.rproxy.govskope.us.cn = EXAMPLE.COM .amazon.com = EXAMPLE.COM ``` ## Step 8: (Optional) Configure case-insensitive username comparison By default, the character case of the MySQL database username must match that of the Active Directory login. However, you can now use case-insensitive username comparison with the `authentication_kerberos` plugin. To do so, you set the `authentication_kerberos_caseins_cmp` DB cluster parameter to `true`. **To use case-insensitive username comparison** 1. Create a custom DB cluster parameter group. Follow the procedures in [Creating a DB cluster parameter groupin Amazon Aurora](USER_WorkingWithParamGroups.CreatingCluster.md). 1. Edit the new parameter group to set the value of `authentication_kerberos_caseins_cmp` to `true`. Follow the procedures in [Modifying parameters in a DB cluster parameter groupin Amazon Aurora](USER_WorkingWithParamGroups.ModifyingCluster.md). 1. Associate the DB cluster parameter group with your Aurora MySQL DB cluster. Follow the procedures in [Associating a DB cluster parameter group with a DB cluster in Amazon Aurora](USER_WorkingWithParamGroups.AssociatingCluster.md). 1. Reboot the DB cluster. # Connecting to Aurora MySQL with Kerberos authentication To avoid errors, use a MySQL client with version 8.0.26 or higher on Unix platforms, 8.0.27 or higher on Windows. ## Using the Aurora MySQL Kerberos login to connect to the DB cluster To connect to Aurora MySQL with Kerberos authentication, you log in as a database user that you created using the instructions in [Step 6: Create Aurora MySQL users that use Kerberos authentication](aurora-mysql-kerberos-setting-up.md#aurora-mysql-kerberos-setting-up.create-logins). At a command prompt, connect to one of the endpoints associated with your Aurora MySQL DB cluster. When you're prompted for the password, enter the Kerberos password associated with that username. When you authenticate with Kerberos, a *ticket-granting ticket* (TGT) is generated if one doesn't already exist. The `authentication_kerberos` plugin uses the TGT to get a *service ticket*, which is then presented to the Aurora MySQL database server. You can use the MySQL client to connect to Aurora MySQL with Kerberos authentication using either Windows or Unix. ### Unix You can connect by using either one of the following methods: + Obtain the TGT manually. In this case, you don't need to supply the password to the MySQL client. + Supply the password for the Active Directory login directly to the MySQL client. The client-side plugin is supported on Unix platforms for MySQL client versions 8.0.26 and higher. **To connect by obtaining the TGT manually** 1. At the command line interface, use the following command to obtain the TGT. ``` kinit user_name ``` 1. Use the following `mysql` command to log in to the DB instance endpoint of your DB cluster. ``` mysql -h DB_instance_endpoint -P 3306 -u user_name -p ``` **Note** Authentication can fail if the keytab is rotated on the DB instance. In this case, obtain a new TGT by rerunning `kinit`. **To connect directly** 1. At the command line interface, use the following `mysql` command to log in to the DB instance endpoint of your DB cluster. ``` mysql -h DB_instance_endpoint -P 3306 -u user_name -p ``` 1. Enter the password for the Active Directory user. ### Windows On Windows, authentication is usually done at login time, so you don't need to obtain the TGT manually to connect to the Aurora MySQL DB cluster. The case of the database username must match the character case of the user in the Active Directory. For example, if the user in the Active Directory appears as `Admin`, the database username must be `Admin`. The client-side plugin is supported on Windows for MySQL client versions 8.0.27 and higher. **To connect directly** + At the command line interface, use the following `mysql` command to log in to the DB instance endpoint of your DB cluster. ``` mysql -h DB_instance_endpoint -P 3306 -u user_name ``` ## Kerberos authentication with Aurora global databases Kerberos authentication for Aurora MySQL is supported for Aurora global databases. To authenticate users on the secondary DB cluster using the Active Directory of the primary DB cluster, replicate the Active Directory to the secondary AWS Region. You turn on Kerberos authentication on the secondary cluster using the same domain ID as for the primary cluster. AWS Managed Microsoft AD replication is supported only with the Enterprise version of Active Directory. For more information, see [Multi-Region replication](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_configure_multi_region_replication.html) in the *AWS Directory Service Administration Guide*. ## Migrating from RDS for MySQL to Aurora MySQL After you migrate from RDS for MySQL with Kerberos authentication enabled to Aurora MySQL, modify users created with the `auth_pam` plugin to use the `authentication_kerberos` plugin. For example: ``` ALTER USER user_name IDENTIFIED WITH 'authentication_kerberos' BY 'realm_name'; ``` ## Preventing ticket caching If a valid TGT doesn't exist when the MySQL client application starts, the application can obtain and cache the TGT. If you want to prevent the TGT from being cached, set a configuration parameter in the `/etc/krb5.conf` file. **Note** This configuration only applies to client hosts running Unix, not Windows. **To prevent TGT caching** + Add an `[appdefaults]` section to `/etc/krb5.conf` as follows: ``` [appdefaults] mysql = { destroy_tickets = true } ``` ## Logging for Kerberos authentication The `AUTHENTICATION_KERBEROS_CLIENT_LOG` environment variable sets the logging level for Kerberos authentication. You can use the logs for client-side debugging. The permitted values are 1–5. Log messages are written to the standard error output. The following table describes each logging level. | Logging level | Description | | --- | --- | | 1 or not set | No logging | | 2 | Error messages | | 3 | Error and warning messages | | 4 | Error, warning, and information messages | | 5 | Error, warning, information, and debug messages | # Managing a DB cluster in a domain You can use the AWS CLI or the RDS API to manage your DB cluster and its relationship with your managed Active Directory. For example, you can associate an Active Directory for Kerberos authentication and disassociate an Active Directory to turn off Kerberos authentication. You can also move a DB cluster to be externally authenticated by one Active Directory to another. For example, using the Amazon RDS API, you can do the following: + To reattempt turning on Kerberos authentication for a failed membership, use the `ModifyDBInstance` API operation and specify the current membership's directory ID. + To update the IAM role name for membership, use the `ModifyDBInstance` API operation and specify the current membership's directory ID and the new IAM role. + To turn off Kerberos authentication on a DB cluster, use the `ModifyDBInstance` API operation and specify `none` as the domain parameter. + To move a DB cluster from one domain to another, use the `ModifyDBInstance` API operation and specify the domain identifier of the new domain as the domain parameter. + To list membership for each DB cluster, use the `DescribeDBInstances` API operation. ## Understanding domain membership After you create or modify your DB cluster, it becomes a member of the domain. You can view the status of the domain membership for the DB cluster by running the [describe-db-clusters](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-clusters.html) CLI command. The status of the DB cluster can be one of the following: + `kerberos-enabled` – The DB cluster has Kerberos authentication turned on. + `enabling-kerberos` – AWS is in the process of turning on Kerberos authentication on this DB cluster. + `pending-enable-kerberos` – Turning on Kerberos authentication is pending on this DB cluster. + `pending-maintenance-enable-kerberos` – AWS will attempt to turn on Kerberos authentication on the DB cluster during the next scheduled maintenance window. + `pending-disable-kerberos` – Turning off Kerberos authentication is pending on this DB cluster. + `pending-maintenance-disable-kerberos` – AWS will attempt to turn off Kerberos authentication on the DB cluster during the next scheduled maintenance window. + `enable-kerberos-failed` – A configuration problem has prevented AWS from turning on Kerberos authentication on the DB cluster. Check and fix your configuration before reissuing the DB cluster modify command. + `disabling-kerberos` – AWS is in the process of turning off Kerberos authentication on this DB cluster. A request to turn on Kerberos authentication can fail because of a network connectivity issue or an incorrect IAM role. For example, suppose that you create a DB cluster or modify an existing DB cluster and the attempt to turn on Kerberos authentication fails. In this case, reissue the modify command or modify the newly created DB cluster to join the domain.