Skip to main content

Federated Authentication Plugin

The Federated Authentication Plugin adds support for authenticating through a federated identity provider — Microsoft Active Directory Federation Services (AD FS) — and then connecting to the database with AWS IAM. The plugin signs in to AD FS, obtains a SAML assertion, exchanges it for temporary AWS credentials, and uses those credentials to generate an IAM authentication token for the connection.

Available since

Version 1.1.0

Only one authentication plugin at a time

Only one authentication plugin may be enabled per connection. Do not use federated_auth together with any of the other authentication plugins (iam, secrets_manager, okta) at the same time for the same connection. Configuring more than one raises a PluginConflictError at connection initialization.

What is federated identity​

Federated identity lets users authenticate once with an external identity provider (IdP) and use that single identity to reach services across organizations. The IdP authenticates the user and issues a signed security token — a SAML assertion — and any service provider that trusts the IdP accepts that assertion instead of managing its own credentials.

This plugin applies that flow to database access. It signs in to your IdP with the configured credentials, receives a SAML assertion, exchanges the assertion for temporary AWS credentials through AWS STS AssumeRoleWithSAML, and uses those credentials to generate an AWS IAM authentication token. That IAM token is what the plugin uses to connect, so AWS IAM database authentication must be enabled on the target database.

Prerequisites​

warning

This plugin requires the AWS SDK for RDS. Add it to your Gemfile:

gem 'aws-sdk-rds'

The plugin signs in to your identity provider over HTTPS using Ruby's standard library HTTP client, so no additional SAML or XML parsing gem is required. It obtains AWS credentials from the SAML assertion through AWS STS AssumeRoleWithSAML; it does not read aws_credentials_provider or the AWS SDK default credential provider chain.

Before using the plugin, enable IAM database authentication on your database, create an IAM SAML identity provider and an IAM role granting rds-db:connect, and create a database account mapped to IAM:

  • MySQL: CREATE USER iam_user IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
  • PostgreSQL: CREATE USER iam_user; GRANT rds_iam TO iam_user;

How to enable​

The plugin depends on AWS IAM database authentication: after it obtains a SAML assertion from your IdP, the assertion is exchanged for an AWS IAM authentication token, which is then used to connect to the database. Before enabling the plugin:

  1. Enable IAM database authentication on your RDS or Aurora database.
  2. Set up an IAM SAML identity provider and an IAM role whose policy grants rds-db:connect, then federate your IdP into that AWS account.

Then add the plugin code federated_auth to the wrapper_plugins parameter and set the parameters required for your environment.

require 'aws_advanced_ruby_driver_wrapper/postgresql'

conn = AwsAdvancedRubyDriverWrapper::WrapperPgConnection.new(
host: "my-cluster.cluster-xyz.us-east-1.rds.amazonaws.com",
wrapper_plugins: "federated_auth",
db_user: "iam_user",
idp_endpoint: "adfs.example.com",
idp_username: "someFederatedUsername@example.com",
idp_password: "someFederatedPassword",
iam_role_arn: "arn:aws:iam::123456789012:role/adfs_example_iam_role",
iam_idp_arn: "arn:aws:iam::123456789012:saml-provider/adfs_example",
iam_region: "us-east-1",
sslmode: "verify-full",
sslrootcert: "/path/to/global-bundle.pem"
)

Verify plugin compatibility within your Ruby configuration using the compatibility guide.

Configuration parameters​

ParameterTypeRequiredDefaultDescription
db_userStringYes—The database username the generated IAM authentication token is minted for — the IAM-mapped database account the connection is made as.

Example: iam_user
idp_endpointStringYes—The host name of the AD FS identity provider used to authenticate.

Example: adfs.example.com
idp_usernameStringNoconnection userThe username used to sign in to the identity provider. If not set, the plugin falls back to the connection user/username.

Example: someFederatedUsername@example.com
idp_passwordStringNoconnection passwordThe password used to sign in to the identity provider. If not set, the plugin falls back to the connection password.

Example: someFederatedPassword
idp_portIntegerNo443The port the AD FS host listens on, used to build the sign-on URL.

Example: 443
rp_identifierStringNourn:amazon:webservicesThe relying-party identifier sent to AD FS when requesting the SAML assertion.

Example: urn:amazon:webservices
iam_role_arnStringYes—The ARN of the IAM role assumed through the SAML assertion to obtain temporary AWS credentials.

Example: arn:aws:iam::123456789012:role/adfs_example_iam_role
iam_idp_arnStringYes—The ARN of the SAML identity provider registered in AWS IAM.

Example: arn:aws:iam::123456789012:saml-provider/adfs_example
iam_regionStringNoparsed from hostOverrides the AWS region used to generate the IAM token. By default it is parsed from the connection host.

Example: us-east-1
iam_hostStringNoderived from hostOverrides the host used to generate the IAM token. By default it is derived from the connection host.

Example: my-cluster.cluster-xyz.us-east-1.rds.amazonaws.com
iam_portIntegerNodialect defaultOverrides the port used to generate the IAM token. By default it is taken from the connection, or the dialect's default port.

Example: 5432
iam_expiration_secFloatNo870.0Number of seconds a generated IAM token is kept in the cache before a new one is generated. The token itself is valid for 15 minutes, and a cached token is never used within 60 seconds of that expiry, so values of 840.0 and above will all have their tokens refetched at the 840 mark. The token cache is shared by every connection in the process that uses the iam, federated_auth, or okta plugin, and its lifetime is set by the first such connection; later connections that set a different value use the first connection's value. A value greater than 870.0 or less than or equal to 0 is rejected. (sec)

Example: 600.0 (maximum 870.0)
ssl_insecureBooleanNofalseWhen true, disables TLS certificate verification on the HTTPS requests the plugin makes to the identity provider. Intended for development only.

Example: true
http_client_socket_timeout_secFloatNo60.0Read (socket) timeout for the HTTPS requests the plugin makes to the identity provider. (sec)

Example: 60.0
http_client_connect_timeout_secFloatNo60.0Connect timeout for the HTTPS requests the plugin makes to the identity provider. (sec)

Example: 60.0

Using this plugin with Global Databases​

When connecting to an Amazon Aurora Global Database, the IAM role assumed through the SAML assertion requires the additional rds:DescribeGlobalClusters permission so the plugin can resolve the writer region before generating the IAM token.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-db:connect",
"rds:DescribeGlobalClusters"
],
"Resource": "*"
}
]
}

When you connect through an Aurora Global Database endpoint, also enable the Initial Connection Strategy plugin (initial_connection). A global endpoint carries no region and points at whichever regional cluster is currently the primary, so it must be resolved to the writer instance before the IAM token is generated.

For a global writer cluster, set iam_region explicitly when you can. Without it, the plugin must perform one extra sign-in to your identity provider up front to obtain the credentials needed to look up the writer region.

Use TLS/SSL with federated authentication​

warning

Use a TLS/SSL 1.2+ connection. The plugin injects the generated IAM token as the connection password, and TLS ensures it is encrypted in transit.

PostgreSQL (pg): set sslmode: "verify-full" and point sslrootcert at the AWS global certificate bundle.

AwsAdvancedRubyDriverWrapper::WrapperPgConnection.new(
host: "my-cluster.cluster-xyz.us-east-1.rds.amazonaws.com",
wrapper_plugins: "federated_auth",
db_user: "iam_user",
idp_endpoint: "adfs.example.com",
idp_username: "someFederatedUsername@example.com",
idp_password: "someFederatedPassword",
iam_role_arn: "arn:aws:iam::123456789012:role/adfs_example_iam_role",
iam_idp_arn: "arn:aws:iam::123456789012:saml-provider/adfs_example",
iam_region: "us-east-1",
sslmode: "verify-full",
sslrootcert: "/path/to/global-bundle.pem"
)

MySQL (mysql2): set ssl_mode: "verify_identity", point sslca at the global certificate bundle, and set enable_cleartext_plugin: true. RDS/Aurora MySQL IAM authentication relies on the MySQL mysql_clear_password client plugin because the token must be sent to the server in cleartext; the wrapper does not set this for you.

AwsAdvancedRubyDriverWrapper::WrapperMysql2Client.new(
host: "my-cluster.cluster-xyz.us-east-1.rds.amazonaws.com",
wrapper_plugins: "federated_auth",
db_user: "iam_user",
idp_endpoint: "adfs.example.com",
idp_username: "someFederatedUsername@example.com",
idp_password: "someFederatedPassword",
iam_role_arn: "arn:aws:iam::123456789012:role/adfs_example_iam_role",
iam_idp_arn: "arn:aws:iam::123456789012:saml-provider/adfs_example",
iam_region: "us-east-1",
enable_cleartext_plugin: true,
sslca: "/path/to/global-bundle.pem",
ssl_mode: "verify_identity"
)

With the Trilogy driver, use AwsAdvancedRubyDriverWrapper::WrapperTrilogyClient. enable_cleartext_plugin: true is still required — without it Trilogy raises Trilogy::AuthPluginError — but two TLS keys differ: the CA certificate is ssl_ca rather than sslca, and on the direct client ssl_mode must be an integer constant (ssl_mode: Trilogy::SSL_VERIFY_IDENTITY), not a string. See Configuring TLS/SSL.

For the full picture, see Configuring TLS/SSL.