Proposal: IAM AuthServer for Vitess

[dbmurphy]

Summary

This document outlines the implementation of AWS IAM-like authentication within Vitess using the iam_authserver package. The approach focuses on securely transmitting AWS Access Key and Secret Key pairs, ensuring these credentials are protected via TLS, and integrating them into Vitess’s existing authentication and authorization mechanisms.

Background

Standard one-way hashing mechanisms cannot retrieve these credentials for validation, so Vitess must use mysqlClearAuthMethod to handle cleartext credentials securely. Luckily, we have existing logic to ensure clearAuth when forcing TLS to ensure "clear" does not mean unencrypted over the wire.

While it would be preferred not to have to send the AWS access and secret keys over the wire and instead send a signed STS request like AWS MSK IAM Auth does but the MySQL protocol does not support password payloads that long as we must be protocol compliant.

Overview of the Implementation

The implementation enables the use of AWS IAM credentials for authentication in Vitess. Credentials are transmitted securely using the mysqlClearAuthMethod, and AWS STS AssumeRole is utilized to validate the credentials, ensuring the provided
username matches the AWS IAM role_name, with strict enforcement of TLS to ensure keys are not unencrypted.

Why TLS is Critical

TLS is mandatory for transmitting cleartext credentials. By configuring Vitess to use mysqlClearAuthMethod, we enforce that cleartext passwords are only transmitted over an encrypted connection, preventing credential leakage and securing the authentication process.

Credential Transmission and Format

AWS IAM credentials are transmitted in the format <access_key>|<secret_key>. This format ensures that the credentials can be securely transmitted within MySQL’s 255-character limit while avoiding the limitations of one-way hashing.

Only Supporting mysqlClearAuthMethod

The implementation exclusively supports the mysqlClearAuthMethod, which enforces AllowClearTextWithoutTLS() to ensure that cleartext credentials are only transmitted when TLS is active.

Why mysqlClearAuthMethod?:

Credential Extraction: The method allows for extracting Access and Secret Keys in their original form, which is necessary for performing an STS AssumeRole operation to validate the credentials.

TLS Enforcement: The method enforces TLS, ensuring the credentials are never exposed during transmission.
Operation with TLS:

When a client connects, Vitess automatically checks for TLS. If TLS is not enabled, mysqlClearAuthMethod triggers an error, rejecting the connection and preventing unencrypted credential transmission.

Authentication Flow

Initial Connection and TLS Enforcement:

Vitess’s existing handshake logic, using mysqlClearAuthMethod, ensures that the CLIENT_SSL capability is set, enforcing TLS without any need for changes in conn.go, server.go, or auth_server.go.

Credential Extraction:

Credentials are received in the <access_key>|<secret_key> format and extracted for processing.
STS AssumeRole Operation:

The extracted credentials are used to perform an STS AssumeRole operation, which validates the credentials and returns the IAM role name.

Role Name Validation:

The role name returned by STS is compared with the provided username. If they match, authentication is successful.
Authorization Using ACLs:

The IAM role name is used for ACL checks, ensuring permissions are correctly applied based on the authenticated IAM role.

Caching STS AssumeRole Information

To optimize performance and reduce the number of calls to the AWS STS API, the implementation will cache the results of the STS AssumeRole operation. This cache will be indexed using a one-way hash of the Access Key and Secret Key pair. The TTL for the cache will be equal to the TTL of the Access Key and Secret Key at the time of the first authentication. This ensures that the cached credentials are only used while still valid.

Cache Strategy:

Cache the role name and associated metadata for the remaining TTL of the STS credentials.
To ensure security and avoid exposing sensitive information, use a one-way hash of the Access Key and Secret Key pair as the cache key.

Integration with Vitess Auth Servers and ACLs

Auth Server Interface:

The IAMAuthServer is integrated as a custom authentication server, leveraging existing Vitess functionality without modifying the core handshake logic.

ACL Integration:

After authentication, the IAM role name is used for authorization checks to apply the correct permissions.

Considerations and Challenges

Secure Handling of AWS Credentials:

The implementation ensures that Access and Secret Key pairs are securely managed and rotated according to AWS best practices.

Compatibility with Existing Methods:

The design is compatible with other authentication methods in Vitess, ensuring they can coexist without interference.

Scalability:

The system is designed to scale effectively within Vitess’s sharded architecture.

Conclusion

This design provides a secure and efficient method for integrating AWS IAM-like authentication into Vitess. By leveraging mysqlClearAuthMethod and enforcing TLS, the system ensures the secure transmission of AWS credentials while integrating seamlessly with Vitess’s existing authentication and authorization frameworks. Caching STS AssumeRole results further optimize performance, reducing the load on the AWS API and ensuring efficient operation in a distributed environment. The TTL for cached STS results is dynamically set to match the remaining validity period of the credentials, ensuring that only fresh and valid data is used.