Okta Authentication Plugin
The Okta Authentication Plugin adds support for authenticating through Okta as the federated identity provider and then connecting to the database with AWS IAM. The plugin signs in to Okta, obtains a SAML assertion for the configured AWS application, exchanges it for temporary AWS credentials, and uses those credentials to generate an IAM authentication token for the connection.
Version 1.1.0
Only one authentication plugin may be enabled per connection. Do not use okta together with any of the other authentication plugins (iam, secrets_manager, federated_auth) 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
This plugin requires the AWS SDK for RDS. Add it to your Gemfile:
gem 'aws-sdk-rds'
The plugin signs in to Okta 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,
configure Okta as an AWS identity provider,
create the matching 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:
- Enable IAM database authentication on your RDS or Aurora database.
- 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 okta 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: "okta",
db_user: "iam_user",
idp_endpoint: "my-org.okta.com",
idp_username: "someFederatedUsername@example.com",
idp_password: "someFederatedPassword",
app_id: "0oa1b2c3d4EXAMPLE",
iam_role_arn: "arn:aws:iam::123456789012:role/okta_example_iam_role",
iam_idp_arn: "arn:aws:iam::123456789012:saml-provider/okta_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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
db_user | String | Yes | — | 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_endpoint | String | Yes | — | The host name of your Okta organization used to authenticate. Example: my-org.okta.com |
idp_username | String | No | connection user | The 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_password | String | No | connection password | The password used to sign in to the identity provider. If not set, the plugin falls back to the connection password.Example: someFederatedPassword |
app_id | String | Yes | — | The identifier of the AWS application configured in Okta. Example: 0oa1b2c3d4EXAMPLE |
iam_role_arn | String | Yes | — | The ARN of the IAM role assumed through the SAML assertion to obtain temporary AWS credentials. Example: arn:aws:iam::123456789012:role/okta_example_iam_role |
iam_idp_arn | String | Yes | — | The ARN of the SAML identity provider registered in AWS IAM. Example: arn:aws:iam::123456789012:saml-provider/okta_example |
iam_region | String | No | parsed from host | Overrides the AWS region used to generate the IAM token. By default it is parsed from the connection host. Example: us-east-1 |
iam_host | String | No | derived from host | Overrides 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_port | Integer | No | dialect default | Overrides 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_sec | Float | No | 870.0 | Number 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_insecure | Boolean | No | false | When 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_sec | Float | No | 60.0 | Read (socket) timeout for the HTTPS requests the plugin makes to the identity provider. (sec) Example: 60.0 |
http_client_connect_timeout_sec | Float | No | 60.0 | Connect 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 Okta authentication
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: "okta",
db_user: "iam_user",
idp_endpoint: "my-org.okta.com",
idp_username: "someFederatedUsername@example.com",
idp_password: "someFederatedPassword",
app_id: "0oa1b2c3d4EXAMPLE",
iam_role_arn: "arn:aws:iam::123456789012:role/okta_example_iam_role",
iam_idp_arn: "arn:aws:iam::123456789012:saml-provider/okta_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: "okta",
db_user: "iam_user",
idp_endpoint: "my-org.okta.com",
idp_username: "someFederatedUsername@example.com",
idp_password: "someFederatedPassword",
app_id: "0oa1b2c3d4EXAMPLE",
iam_role_arn: "arn:aws:iam::123456789012:role/okta_example_iam_role",
iam_idp_arn: "arn:aws:iam::123456789012:saml-provider/okta_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.