# Securing MySQL DB instance connections You can implement robust security measures to protect MySQL DB instances from unauthorized access and potential threats. Security groups, SSL/TLS encryption, and IAM database authentication work together to create multiple layers of connection security for your MySQL DB instances. These security controls help you meet compliance requirements, prevent data breaches, and maintain secure communication channels between applications and databases. You can secure your MySQL DB instances by encrypting data in transit, restricting access to specific IP ranges, and managing user authentication through IAM roles rather than database passwords. Security for MySQL DB instances is managed at three levels: + AWS Identity and Access Management controls who can perform Amazon RDS management actions on DB instances. When you connect to AWS using IAM credentials, your IAM account must have IAM policies that grant the permissions required to perform Amazon RDS management operations. For more information, see [Identity and access management for Amazon RDS](UsingWithRDS.IAM.md). + When you create a DB instance, you use a VPC security group to control which devices and Amazon EC2 instances can open connections to the endpoint and port of the DB instance. These connections can be made using Secure Sockets Layer (SSL) and Transport Layer Security (TLS). In addition, firewall rules at your company can control whether devices running at your company can open connections to the DB instance. + To authenticate login and permissions for a MySQL DB instance, you can take either of the following approaches, or a combination of them: + You can take the same approach as with a stand-alone instance of MySQL. Commands such as `CREATE USER`, `RENAME USER`, `GRANT`, `REVOKE`, and `SET PASSWORD` work just as they do in on-premises databases, as does directly modifying database schema tables. However, directly modifying the database schema tables isn't a best practice, and starting from RDS for MySQL version 8.0.36, it isn't supported. For information, see [ Access control and account management](https://dev.mysql.com/doc/refman/8.0/en/access-control.html) in the MySQL documentation. + You can also use IAM database authentication. With IAM database authentication, you authenticate to your DB instance by using an IAM user or IAM role and an authentication token. An *authentication token* is a unique value that is generated using the Signature Version 4 signing process. By using IAM database authentication, you can use the same credentials to control access to your AWS resources and your databases. For more information, see [IAM database authentication for MariaDB, MySQL, and PostgreSQL](UsingWithRDS.IAMDBAuth.md). + Another option is Kerberos authentication for RDS for MySQL. The DB instance works with AWS Directory Service for Microsoft Active Directory (AWS Managed Microsoft AD) to enable Kerberos authentication. When users authenticate with a MySQL DB instance joined to the trusting domain, authentication requests are forwarded. Forwarded requests go to the domain directory that you create with Directory Service. For more information, see [Using Kerberos authentication for Amazon RDS for MySQL](mysql-kerberos.md). When you create an Amazon RDS DB instance, the master user has the following default privileges: | Engine version | System privilege | Database role | | --- | --- | --- | | RDS for MySQL version 8.4.3 and higher | `GRANT SELECT`, `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, `RELOAD`, `PROCESS`, `REFERENCES`,`INDEX`, `ALTER`, `SHOW DATABASES`, `CREATE TEMPORARY TABLES`, `LOCK TABLES`, `EXECUTE`, `REPLICATION SLAVE`, `REPLICATION CLIENT`, `CREATE VIEW`, `SHOW VIEW`, `CREATE ROUTINE`, `ALTER ROUTINE`, `CREATE USER`, `EVENT`, `TRIGGER`, `CREATE ROLE`, `DROP ROLE`, `APPLICATION_PASSWORD_ADMIN`, `FLUSH_OPTIMIZER_COSTS`, `FLUSH_PRIVILEGES`, `FLUSH_STATUS`, `FLUSH_TABLES`, `FLUSH_USER_RESOURCES`, `ROLE_ADMIN`, `SENSITIVE_VARIABLES_OBSERVER`, `SESSION_VARIABLES_ADMIN`, `SET_ANY_DEFINER`, `SHOW_ROUTINE`, `XA_RECOVER_ADMIN` | `rds_superuser_role` For more information about `rds_superuser_role`, see [Role-based privilege model for RDS for MySQL](Appendix.MySQL.CommonDBATasks.privilege-model.md). | | RDS for MySQL version 8.0.36 and higher | `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, `RELOAD`, `PROCESS`, `REFERENCES`, `INDEX`, `ALTER`, `SHOW DATABASES`, `CREATE TEMPORARY TABLES`, `LOCK TABLES`, `EXECUTE`, `REPLICATION SLAVE`, `REPLICATION CLIENT`, `CREATE VIEW`, `SHOW VIEW`, `CREATE ROUTINE`, `ALTER ROUTINE`, `CREATE USER`, `EVENT`, `TRIGGER`, `CREATE ROLE`, `DROP ROLE`, `APPLICATION_PASSWORD_ADMIN`, `ROLE_ADMIN`, `SET_USER_ID`, `XA_RECOVER_ADMIN` | `rds_superuser_role` For more information about `rds_superuser_role`, see [Role-based privilege model for RDS for MySQL](Appendix.MySQL.CommonDBATasks.privilege-model.md). | | RDS for MySQL versions lower than 8.0.36 | `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, `RELOAD`, `PROCESS`, `REFERENCES`, `INDEX`, `ALTER`, `SHOW DATABASES`, `CREATE TEMPORARY TABLES`, `LOCK TABLES`, `EXECUTE`, `REPLICATION CLIENT`, `CREATE VIEW`, `SHOW VIEW`, `CREATE ROUTINE`, `ALTER ROUTINE`, `CREATE USER`, `EVENT`, `TRIGGER`, `REPLICATION SLAVE` | None | **Note** Although it is possible to delete the master user on the DB instance, it is not recommended. To recreate the master user, use the [ModifyDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html) RDS API operation or run the [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) AWS CLI command and specify a new master user password with the appropriate parameter. If the master user does not exist in the instance, the master user is created with the specified password. To provide management services for each DB instance, the `rdsadmin` user is created when the DB instance is created. Attempting to drop, rename, change the password, or change privileges for the `rdsadmin` account will result in an error. To allow management of the DB instance, the standard `kill` and `kill_query` commands have been restricted. The Amazon RDS commands `rds_kill` and `rds_kill_query` are provided to allow you to end user sessions or queries on DB instances. # Password validation for RDS for MySQL MySQL provides the `validate_password` plugin for improved security. The plugin enforces password policies using parameters in the DB parameter group for your MySQL DB instance. The plugin is supported for DB instances running MySQL version 5.7, 8.0, and 8.4. For more information about the `validate_password` plugin, see [The Password Validation Plugin](https://dev.mysql.com/doc/refman/5.7/en/validate-password.html) in the MySQL documentation. **To enable the `validate_password` plugin for a MySQL DB instance** 1. Connect to your MySQL DB instance and run the following command. ``` INSTALL PLUGIN validate_password SONAME 'validate_password.so'; ``` 1. Configure the parameters for the plugin in the DB parameter group used by the DB instance. For more information about the parameters, see [Password Validation Plugin Options and Variables](https://dev.mysql.com/doc/refman/5.7/en/validate-password-options-variables.html) in the MySQL documentation. For more information about modifying DB instance parameters, see [Modifying parameters in a DB parameter group in Amazon RDS](USER_WorkingWithParamGroups.Modifying.md). 1. Restart the DB instance. After enabling the `validate_password` plugin, reset existing passwords to comply with your new validation policies. Your MySQL DB instance handles password validation for Amazon RDS. To change a password, you first submit a password update request through the AWS Management Console, `modify-db-instance` CLI command, or `ModifyDBInstance` API operation. RDS initially accepts your request, even if the password doesn't meet your policies. RDS then processes the request asynchronously. It updates the password in your MySQL DB instance only if the password meets your defined policies. If the password doesn't meet these policies, RDS keeps the existing password and logs an error event. ``` Unable to reset your password. Error information: Password failed to meet validation rules. ``` For more information about Amazon RDS events, see [Working with Amazon RDS event notification](USER_Events.md). # Encrypting client connections with SSL/TLS to MySQL DB instances on Amazon RDS Secure Sockets Layer (SSL) is an industry-standard protocol for securing network connections between client and server. After SSL version 3.0, the name was changed to Transport Layer Security (TLS). Amazon RDS supports SSL/TLS encryption for MySQL DB instances. Using SSL/TLS, you can encrypt a connection between your application client and your MySQL DB instance. SSL/TLS support is available in all AWS Regions for MySQL. With Amazon RDS, you can secure data in transit by encrypting client connections to MySQL DB instances with SSL/TLS, requiring SSL/TLS for all connections to a MySQL DB instance, and connecting from the MySQL command-line client with SSL/TLS (encrypted). The following sections provide guidance on configuring and utilizing SSL/TLS encryption for MySQL DB instances on Amazon RDS. **Topics** + [SSL/TLS support for MySQL DB instances on Amazon RDS](MySQL.Concepts.SSLSupport.md) + [Requiring SSL/TLS for specific user accounts to a MySQL DB instance on Amazon RDS](mysql-ssl-connections.require-ssl-users.md) + [Requiring SSL/TLS for all connections to a MySQL DB instance on Amazon RDS](mysql-ssl-connections.require-ssl.md) + [Connecting to your MySQL DB instance on Amazon RDS with SSL/TLS from the MySQL command-line client (encrypted)](USER_ConnectToInstanceSSL.CLI.md) # SSL/TLS support for MySQL DB instances on Amazon RDS Amazon RDS creates an SSL/TLS certificate and installs the certificate on the DB instance when Amazon RDS provisions the instance. These certificates are signed by a certificate authority. The SSL/TLS certificate includes the DB instance endpoint as the Common Name (CN) for the SSL/TLS certificate to guard against spoofing attacks. An SSL/TLS certificate created by Amazon RDS is the trusted root entity and should work in most cases, but might fail if your application doesn't accept certificate chains. If your application doesn't accept certificate chains, try using an intermediate certificate to connect to your AWS Region. For example, you must use an intermediate certificate to connect to the AWS GovCloud (US) Regions with SSL/TLS. For information about downloading certificates, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). For more information about using SSL/TLS with MySQL, see [Updating applications to connect to MySQL DB instances using new SSL/TLS certificates](ssl-certificate-rotation-mysql.md). For MySQL version 8.0 and lower, Amazon RDS for MySQL uses OpenSSL for secure connections. For MySQL version 8.4 and higher, Amazon RDS for MySQL uses AWS-LC. TLS support depends on the MySQL version. The following table shows the TLS support for MySQL versions. | MySQL version | TLS 1.0 | TLS 1.1 | TLS 1.2 | TLS 1.3 | | --- | --- | --- | --- | --- | | MySQL 8.4 | Not supported | Not supported | Supported | Supported | | MySQL 8.0 | Not supported | Not supported | Supported | Supported | | MySQL 5.7 | Supported | Supported | Supported | Not supported | # Requiring SSL/TLS for specific user accounts to a MySQL DB instance on Amazon RDS You can require SSL/TLS encryption for specified user account connections to your MySQL DB instances on Amazon RDS. Protecting sensitive information from unauthorized access or interception is crucial to enforce security policies where data confidentiality is a concern. To require SSL/TLS connections for specific users' accounts, use one of the following statements, depending on your MySQL version, to require SSL/TLS connections on the user account `encrypted_user`. To do so, use the following statement. ``` ALTER USER 'encrypted_user'@'%' REQUIRE SSL; ``` For more information on SSL/TLS connections with MySQL, see the [ Using encrypted connections](https://dev.mysql.com/doc/refman/8.0/en/encrypted-connections.html) in the MySQL documentation. # Requiring SSL/TLS for all connections to a MySQL DB instance on Amazon RDS Use the `require_secure_transport` parameter to require that all user connections to your MySQL DB instance use SSL/TLS. By default, the `require_secure_transport` parameter is set to `OFF`. You can set the `require_secure_transport` parameter to `ON` to require SSL/TLS for connections to your DB instance. You can set the `require_secure_transport` parameter value by updating the DB parameter group for your DB instance. You don't need to reboot your DB instance for the change to take effect. When the `require_secure_transport` parameter is set to `ON` for a DB instance, a database client can connect to it if it can establish an encrypted connection. Otherwise, an error message similar to the following is returned to the client: ``` MySQL Error 3159 (HY000): Connections using insecure transport are prohibited while --require_secure_transport=ON. ``` For information about setting parameters, see [Modifying parameters in a DB parameter group in Amazon RDS](USER_WorkingWithParamGroups.Modifying.md). For more information about the `require_secure_transport` parameter, see the [ MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_require_secure_transport). # Connecting to your MySQL DB instance on Amazon RDS with SSL/TLS from the MySQL command-line client (encrypted) The `mysql` client program parameters are slightly different depending on which version of MySQL or MariaDB you are using. To find out which version you have, run the `mysql` command with the `--version` option. In the following example, the output shows that the client program is from MariaDB. ``` $ mysql --version mysql Ver 15.1 Distrib 10.5.15-MariaDB, for osx10.15 (x86_64) using readline 5.1 ``` Most Linux distributions, such as Amazon Linux, CentOS, SUSE, and Debian have replaced MySQL with MariaDB, and the `mysql` version in them is from MariaDB. To connect to your DB instance using SSL/TLS, follow these steps: **To connect to a DB instance with SSL/TLS using the MySQL command-line client** 1. Download a root certificate that works for all AWS Regions. For information about downloading certificates, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). 1. Use a MySQL command-line client to connect to a DB instance with SSL/TLS encryption. For the `-h` parameter, substitute the DNS name (endpoint) for your DB instance. For the `--ssl-ca` parameter, substitute the SSL/TLS certificate file name. For the `-P` parameter, substitute the port for your DB instance. For the `-u` parameter, substitute the user name of a valid database user, such as the master user. Enter the master user password when prompted. The following example shows how to launch the client using the `--ssl-ca` parameter using the MySQL 5.7 client or later: ``` mysql -h mysql–instance1.123456789012.us-east-1.rds.amazonaws.com --ssl-ca=global-bundle.pem --ssl-mode=REQUIRED -P 3306 -u myadmin -p ``` To require that the SSL/TLS connection verifies the DB instance endpoint against the endpoint in the SSL/TLS certificate, enter the following command: ``` mysql -h mysql–instance1.123456789012.us-east-1.rds.amazonaws.com --ssl-ca=global-bundle.pem --ssl-mode=VERIFY_IDENTITY -P 3306 -u myadmin -p ``` The following example shows how to launch the client using the `--ssl-ca` parameter using the MariaDB client: ``` mysql -h mysql–instance1.123456789012.us-east-1.rds.amazonaws.com --ssl-ca=global-bundle.pem --ssl -P 3306 -u myadmin -p ``` 1. Enter the master user password when prompted. You will see output similar to the following. ``` Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 9738 Server version: 8.0.28 Source distribution Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> ``` # Updating applications to connect to MySQL DB instances using new SSL/TLS certificates As of January 13, 2023, Amazon RDS has published new Certificate Authority (CA) certificates for connecting to your RDS DB instances using Secure Socket Layer or Transport Layer Security (SSL/TLS). Following, you can find information about updating your applications to use the new certificates. This topic can help you to determine whether any client applications use SSL/TLS to connect to your DB instances. If they do, you can further check whether those applications require certificate verification to connect. **Note** Some applications are configured to connect to MySQL DB instances only if they can successfully verify the certificate on the server. For such applications, you must update your client application trust stores to include the new CA certificates. You can specify the following SSL modes: `disabled`, `preferred`, and `required`. When you use the `preferred` SSL mode and the CA certificate doesn't exist or isn't up to date, the connection falls back to not using SSL and connects without encryption. We recommend avoiding `preferred` mode. In `preferred` mode, if the connection encounters an invalid certificate, it stops using encryption and proceeds unencrypted. After you update your CA certificates in the client application trust stores, you can rotate the certificates on your DB instances. We strongly recommend testing these procedures in a development or staging environment before implementing them in your production environments. For more information about certificate rotation, see [Rotating your SSL/TLS certificate](UsingWithRDS.SSL-certificate-rotation.md). For more information about downloading certificates, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). For information about using SSL/TLS with MySQL DB instances, see [SSL/TLS support for MySQL DB instances on Amazon RDS](MySQL.Concepts.SSLSupport.md). **Topics** + [Determining whether any applications are connecting to your MySQL DB instance using SSL](#ssl-certificate-rotation-mysql.determining-server) + [Determining whether a client requires certificate verification to connect](#ssl-certificate-rotation-mysql.determining-client) + [Updating your application trust store](#ssl-certificate-rotation-mysql.updating-trust-store) + [Example Java code for establishing SSL connections](#ssl-certificate-rotation-mysql.java-example) ## Determining whether any applications are connecting to your MySQL DB instance using SSL If you are using Amazon RDS for MySQL version 5.7, 8.0, or 8.4 and the Performance Schema is enabled, run the following query to check if connections are using SSL/TLS. For information about enabling the Performance Schema, see [ Performance Schema quick start](https://dev.mysql.com/doc/refman/8.0/en/performance-schema-quick-start.html) in the MySQL documentation. ``` mysql> SELECT id, user, host, connection_type FROM performance_schema.threads pst INNER JOIN information_schema.processlist isp ON pst.processlist_id = isp.id; ``` In this sample output, you can see both your own session (`admin`) and an application logged in as `webapp1` are using SSL. ``` +----+-----------------+------------------+-----------------+ | id | user | host | connection_type | +----+-----------------+------------------+-----------------+ | 8 | admin | 10.0.4.249:42590 | SSL/TLS | | 4 | event_scheduler | localhost | NULL | | 10 | webapp1 | 159.28.1.1:42189 | SSL/TLS | +----+-----------------+------------------+-----------------+ 3 rows in set (0.00 sec) ``` ## Determining whether a client requires certificate verification to connect You can check whether JDBC clients and MySQL clients require certificate verification to connect. ### JDBC The following example with MySQL Connector/J 8.0 shows one way to check an application's JDBC connection properties to determine whether successful connections require a valid certificate. For more information on all of the JDBC connection options for MySQL, see [ Configuration properties](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html) in the MySQL documentation. When using the MySQL Connector/J 8.0, an SSL connection requires verification against the DB server certificate if your connection properties have `sslMode` set to `VERIFY_CA` or `VERIFY_IDENTITY`, as in the following example. ``` Properties properties = new Properties(); properties.setProperty("sslMode", "VERIFY_IDENTITY"); properties.put("user", DB_USER); properties.put("password", DB_PASSWORD); ``` **Note** If you use either the MySQL Java Connector v5.1.38 or later, or the MySQL Java Connector v8.0.9 or later to connect to your databases, even if you haven't explicitly configured your applications to use SSL/TLS when connecting to your databases, these client drivers default to using SSL/TLS. In addition, when using SSL/TLS, they perform partial certificate verification and fail to connect if the database server certificate is expired. ### MySQL The following examples with the MySQL Client show two ways to check a script's MySQL connection to determine whether successful connections require a valid certificate. For more information on all of the connection options with the MySQL Client, see [ Client-side configuration for encrypted connections](https://dev.mysql.com/doc/refman/8.0/en/using-encrypted-connections.html#using-encrypted-connections-client-side-configuration) in the MySQL documentation. When using the MySQL Client version 5.7 and higher, an SSL connection requires verification against the server CA certificate if for the `--ssl-mode` option you specify `VERIFY_CA` or `VERIFY_IDENTITY`, as in the following example. ``` mysql -h mysql-database.rds.amazonaws.com -uadmin -ppassword --ssl-ca=/tmp/ssl-cert.pem --ssl-mode=VERIFY_CA ``` ## Updating your application trust store For information about updating the trust store for MySQL applications, see [Installing SSL certificates](https://dev.mysql.com/doc/mysql-monitor/8.0/en/mem-ssl-installation.html) in the MySQL documentation. For information about downloading the root certificate, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). For sample scripts that import certificates, see [Sample script for importing certificates into your trust store](UsingWithRDS.SSL-certificate-rotation.md#UsingWithRDS.SSL-certificate-rotation-sample-script). **Note** When you update the trust store, you can retain older certificates in addition to adding the new certificates. If you are using the mysql JDBC driver in an application, set the following properties in the application. ``` System.setProperty("javax.net.ssl.trustStore", certs); System.setProperty("javax.net.ssl.trustStorePassword", "password"); ``` When you start the application, set the following properties. ``` java -Djavax.net.ssl.trustStore=/path_to_trust_store/MyTruststore.jks -Djavax.net.ssl.trustStorePassword=my_trust_store_password com.companyName.MyApplication ``` **Note** Specify a password other than the prompt shown here as a security best practice. ## Example Java code for establishing SSL connections The following code example shows how to set up the SSL connection that validates the server certificate using JDBC. ``` public class MySQLSSLTest { private static final String DB_USER = "username"; private static final String DB_PASSWORD = "password"; // This trust store has only the prod root ca. private static final String TRUST_STORE_FILE_PATH = "file-path-to-trust-store"; private static final String TRUST_STORE_PASS = "trust-store-password"; public static void test(String[] args) throws Exception { Class.forName("com.mysql.jdbc.Driver"); System.setProperty("javax.net.ssl.trustStore", TRUST_STORE_FILE_PATH); System.setProperty("javax.net.ssl.trustStorePassword", TRUST_STORE_PASS); Properties properties = new Properties(); properties.setProperty("sslMode", "VERIFY_IDENTITY"); properties.put("user", DB_USER); properties.put("password", DB_PASSWORD); Connection connection = null; Statement stmt = null; ResultSet rs = null; try { connection = DriverManager.getConnection("jdbc:mysql://mydatabase.123456789012.us-east-1.rds.amazonaws.com:3306",properties); stmt = connection.createStatement(); rs=stmt.executeQuery("SELECT 1 from dual"); } finally { if (rs != null) { try { rs.close(); } catch (SQLException e) { } } if (stmt != null) { try { stmt.close(); } catch (SQLException e) { } } if (connection != null) { try { connection.close(); } catch (SQLException e) { e.printStackTrace(); } } } return; } } ``` **Important** After you have determined that your database connections use SSL/TLS and have updated your application trust store, you can update your database to use the rds-ca-rsa2048-g1 certificates. For instructions, see step 3 in [Updating your CA certificate by modifying your DB instance or cluster](UsingWithRDS.SSL-certificate-rotation.md#UsingWithRDS.SSL-certificate-rotation-updating). Specify a password other than the prompt shown here as a security best practice. # Using Kerberos authentication for Amazon RDS for MySQL You can use Kerberos authentication to authenticate users when they connect to your MySQL DB instance. The DB instance works with AWS Directory Service for Microsoft Active Directory (AWS Managed Microsoft AD) to enable Kerberos authentication. When users authenticate with a MySQL DB instance joined to the trusting domain, authentication requests are forwarded. Forwarded requests go to the domain directory that you create with Directory Service. 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 on version and Region availability of Amazon RDS with Kerberos authentication, see [Supported Regions and DB engines for Kerberos authentication in Amazon RDS](Concepts.RDS_Fea_Regions_DB-eng.Feature.KerberosAuthentication.md). ## Overview of Setting up Kerberos authentication for MySQL DB instances To set up Kerberos authentication for a MySQL DB instance, complete the following general steps, 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 details about doing so, 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 RDS 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 actions. 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 a MySQL DB instance. 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 role that you created. If you modify an existing MySQL DB instance to use Kerberos authentication, set the domain and IAM role parameters for the DB instance. Locate the DB instance in the same VPC as the domain directory. 1. Use the Amazon RDS master user credentials to connect to the MySQL DB instance. Create the user in MySQL using the `CREATE USER` clause `IDENTIFIED WITH 'auth_pam'`. Users that you create this way can log in to the MySQL DB instance using Kerberos authentication. ## Setting up Kerberos authentication for MySQL DB instances You use AWS Managed Microsoft AD to set up Kerberos authentication for a MySQL DB instance. To set up Kerberos authentication, you take the following steps. ### 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 user name 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 typed when you created your directory and 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 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 user name 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 retyped. 1. Choose **Next**. 1. Enter the following information in the **Networking** section and then choose **Next**: **VPC** The VPC for the directory. Create the MySQL DB instance 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**. ![\[The Review & create window during directory creation in the Directory Service console.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/WinAuth2.png) 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 name in the directory listing. Note the **Directory ID** value because you need this value when you create or modify your MySQL DB instance. ![\[The Directory details section with Directory ID in the Directory Service console.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/WinAuth3.png) ### Step 2: Create the IAM role for use by Amazon RDS For Amazon RDS to call Directory Service for you, an IAM role that uses the managed IAM policy `AmazonRDSDirectoryServiceAccess` is required. This role allows Amazon RDS to make calls to the Directory Service. When a DB instance is created using the AWS Management Console and the console user has 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*. **Note** The IAM role used for Windows Authentication for RDS for SQL Server can't be used for RDS for MySQL. 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 3: 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 must be connected to an Amazon EC2 instance based on Microsoft Windows. This instance must be a member of the Directory Service directory and be logged in 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 4: Create or modify a MySQL DB instance Create or modify a MySQL 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: + Create a new MySQL DB instance using the console, the [ create-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html) CLI command, or the [CreateDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html) RDS API operation. For instructions, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md). + Modify an existing MySQL DB instance using the console, the [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) CLI command, or the [ModifyDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html) RDS API operation. For instructions, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md). + Restore a MySQL DB instance from a DB snapshot using the console, the [ restore-db-instance-from-db-snapshot](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-instance-from-db-snapshot.html) CLI command, or the [ RestoreDBInstanceFromDBSnapshot](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceFromDBSnapshot.html) RDS API operation. For instructions, see [Restoring to a DB instance](USER_RestoreFromSnapshot.md). + Restore a MySQL DB instance to a point-in-time using the console, the [ restore-db-instance-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-instance-to-point-in-time.html) CLI command, or the [ RestoreDBInstanceToPointInTime](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceToPointInTime.html) RDS API operation. For instructions, see [Restoring a DB instance to a specified time for Amazon RDS](USER_PIT.md). Kerberos authentication is only supported for MySQL 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 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. Choose **Browse Directory** and then select the directory, or choose **Create a new directory**. ![\[The Database authentication section with Password and Kerberos authentication selected in the Amazon RDS console.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/kerberos-authentication.png) When you use the AWS CLI or RDS API, associate a DB instance with a directory. The following parameters are required for the DB instance 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 instance to use a directory. For Linux, macOS, or Unix: ``` aws rds modify-db-instance \ --db-instance-identifier mydbinstance \ --domain d-ID \ --domain-iam-role-name role-name ``` For Windows: ``` aws rds modify-db-instance ^ --db-instance-identifier mydbinstance ^ --domain d-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 5: Create Kerberos authentication MySQL logins Use the Amazon RDS master user credentials to connect to the MySQL DB instance as you do any other DB instance. The DB instance is joined to the AWS Managed Microsoft AD domain. Thus, you can provision MySQL logins and users from the Active Directory users in your domain. Database permissions are managed through standard MySQL permissions that are granted to and revoked from these logins. You can allow an Active Directory user to authenticate with MySQL. To do this, first use the Amazon RDS master user credentials to connect to the MySQL DB instance as with any other DB instance. After you're logged in, create an externally authenticated user with PAM (Pluggable Authentication Modules) in MySQL by running the following command. Replace `testuser` with the user name. ``` CREATE USER 'testuser'@'%' IDENTIFIED WITH 'auth_pam'; ``` Users (both humans and applications) from your domain can now connect to the DB instance from a domain joined client machine using Kerberos authentication. **Important** We strongly recommended that clients use SSL/TLS connections when using PAM authentication. If they don't use SSL/TLS connections, the password might be sent as clear text in some cases. To require an SSL/TLS encrypted connection for your AD user, run the following command and replace `testuser` with the user name: ``` ALTER USER 'testuser'@'%' REQUIRE SSL; ``` For more information, see [SSL/TLS support for MySQL DB instances on Amazon RDS](MySQL.Concepts.SSLSupport.md). ## Managing a DB instance in a domain You can use the CLI or the RDS API to manage your DB instance 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 disable Kerberos authentication. You can also move a DB instance to be externally authenticated by one Active Directory to another. For example, using the Amazon RDS API, you can do the following: + To reattempt enabling 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 disable Kerberos authentication on a DB instance, use the `ModifyDBInstance` API operation and specify `none` as the domain parameter. + To move a DB instance 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 instance, use the `DescribeDBInstances` API operation. ### 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 for the DB instance by running the [describe-db-instances](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) CLI 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` – The enabling of 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` – The disabling of 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 has prevented AWS from enabling Kerberos authentication on the DB instance. Check and fix your configuration before reissuing the DB instance modify command. + `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. For example, suppose that you create a DB instance or modify an existing DB instance and the attempt to enable Kerberos authentication fails. If this happens, re-issue the modify command or modify the newly created DB instance to join the domain. ## Connecting to MySQL with Kerberos authentication To connect to MySQL with Kerberos authentication, you must log in using the Kerberos authentication type. To create a database user that you can connect to using Kerberos authentication, use an `IDENTIFIED WITH` clause on the `CREATE USER` statement. For instructions, see [Step 5: Create Kerberos authentication MySQL logins](#mysql-kerberos-setting-up.create-logins). To avoid errors, use the MariaDB `mysql` client. You can download MariaDB software at [https://downloads.mariadb.org/](https://downloads.mariadb.org/). At a command prompt, connect to one of the endpoints associated with your MySQL DB instance. Follow the general procedures in [Connecting to your MySQL DB instance](USER_ConnectToInstance.md). When you're prompted for the password, enter the Kerberos password associated with that user name. ## Restoring a MySQL DB instance and adding it to a domain You can restore a DB snapshot or complete a point-in-time restore for a MySQL DB instance and then add it to a domain. After the DB instance is restored, modify the DB instance using the process explained in [Step 4: Create or modify a MySQL DB instance](#mysql-kerberos-setting-up.create-modify) to add the DB instance to a domain. ## Kerberos authentication MySQL limitations The following limitations apply to Kerberos authentication for MySQL: + Only an AWS Managed Microsoft AD is supported. However, you can join RDS for MySQL DB instances to shared Managed Microsoft AD domains owned by different accounts in the same AWS Region. + You must reboot the DB instance after enabling the feature. + The domain name length can't be longer than 61 characters. + You can't enable Kerberos authentication and IAM authentication at the same time. Choose one authentication method or the other for your MySQL DB instance. + Don't modify the DB instance port after enabling the feature. + Don't use Kerberos authentication with read replicas. + If you have auto minor version upgrade turned on for a MySQL DB instance that is using Kerberos authentication, you must turn off Kerberos authentication and then turn it back on after an automatic upgrade. For more information about auto minor version upgrades, see [Automatic minor version upgrades for RDS for MySQL](USER_UpgradeDBInstance.MySQL.Minor.md). + To delete a DB instance with this feature enabled, first disable the feature. To do so, run the `modify-db-instance` CLI command for the DB instance and specify `none` for the `--domain` parameter. If you use the CLI or RDS API to delete a DB instance with this feature enabled, expect a delay. + RDS for MySQL doesn't support Kerberos authentication across a forest trust between your on-premise or self-hosted AD and the AWS Managed Microsoft AD.