Okta Authentication Plugin

The Okta Authentication Plugin adds support for authentication via Federated Identity and then database access via IAM.

Plugin Availability

The plugin is available since version 2.3.6.

What is Federated Identity

Federated Identity allows users to use the same set of credentials to access multiple services or resources across different organizations. This works by having Identity Providers (IdP) that manage and authenticate user credentials, and Service Providers (SP) that are services or resources that can be internal, external, and/or belonging to various organizations. Multiple SPs can establish trust relationships with a single IdP.

When a user wants access to a resource, it authenticates with the IdP. From this a security token generated and is passed to the SP then grants access to said resource. In the case of AD FS, the user signs into the AD FS sign in page. This generates a SAML Assertion which acts as a security token. The user then passes the SAML Assertion to the SP when requesting access to resources. The SP verifies the SAML Assertion and grants access to the user.

Prerequisites

• This plugin requires the following runtime dependencies to be registered separately in the classpath:
  • AWS Java SDK RDS v2.7.x or later
  • AWS Java SDK STS v2.7.x or later
  • jsoup
  • Jackson Databind — the required version depends on your Java runtime. The driver ships as a multi-release JAR, and this plugin uses Jackson 3.x (tools.jackson.core:jackson-databind, tested against 3.2.1) on Java 17 or later, or Jackson 2.x (com.fasterxml.jackson.core:jackson-databind) on Java 8–16. Jackson 2.x and 3.x use different Maven coordinates and Java packages, so adding Jackson 3.x does not conflict with a Jackson 2.x already on your classpath (for example, from Spring Boot 3.x). On Java 17+ with only Jackson 2.x present, the plugin fails at initialization with NoClassDefFoundError for a tools.jackson.* class. See the Jackson 3 Migration Guide for background.
• Note: The above dependencies may have transitive dependencies that are also required (ex. AWS Java SDK RDS requires AWS Java SDK Core). If you are not using a package manager such as Maven or Gradle, please refer to Maven Central to determine these transitive dependencies.
• This plugin does not create or modify any Okta or IAM resources. Okta must be federated into to your AWS IAM account before using this plugin. You can follow Okta's integration guide. In addition, all permissions and policies must be correctly configured before using this plugin. If you plan on using Amazon Aurora Global Databases with this plugin, please see the Using Okta Authentication with Global Databases section as well.

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

How to use the Okta Authentication Plugin with the AWS Advanced JDBC Wrapper

Enabling the Okta Authentication Plugin

1. Enable AWS IAM database authentication on an existing database or create a new database with AWS IAM database authentication on the AWS RDS Console:
   • If needed, review the documentation about IAM authentication for MariaDB, MySQL, and PostgreSQL.
2. Configure Okta as the AWS identity provider.
   • If needed, review the documentation about Amazon Web Services Account Federation on Okta's documentation.
3. Add the plugin code okta to the wrapperPlugins value, or to the current driver profile.
4. Specify parameters that are required or specific to your case.

Okta Authentication Plugin Parameters

Parameter	Value	Required	Description	Default Value	Example Value
dbUser	String	Yes	The user name of the IAM user with access to your database. If you have previously used the IAM Authentication Plugin, this would be the same IAM user. For information on how to connect to your Aurora Database with IAM, see this documentation.	null	some_user_name
idpUsername	String	Yes	The user name for the idpEndpoint server. If this parameter is not specified, the plugin will fallback to using the user parameter.	null	jimbob@example.com
idpPassword	String	Yes	The password associated with the idpEndpoint username. If this parameter is not specified, the plugin will fallback to using the password parameter.	null	someRandomPassword
idpEndpoint	String	Yes	The hosting URL for the service that you are using to authenticate into AWS Aurora.	null	ec2amaz-ab3cdef.example.com
appId	String	Yes	The Amazon Web Services (AWS) app configured on Okta.	null	ec2amaz-ab3cdef.example.com
iamRoleArn	String	Yes	The ARN of the IAM Role that is to be assumed to access AWS Aurora.	null	arn:aws:iam::123456789012:role/adfs_example_iam_role
iamIdpArn	String	Yes	The ARN of the Identity Provider.	null	arn:aws:iam::123456789012:saml-provider/adfs_example
iamRegion	String	Yes	The IAM region where the IAM token is generated.	null	us-east-2
idpPort	String	No	The port that the host for the authentication service listens at.	urn:amazon:webservices	urn:amazon:webservices
iamHost	String	No	Overrides the host that is used to generate the IAM token.	null	database.cluster-hash.us-east-1.rds.amazonaws.com
iamDefaultPort	String	No	This property overrides the default port that is used to generate the IAM token. The default port is determined based on the underlying driver protocol. For now, there is support for jdbc:postgresql: and jdbc:mysql:. Target drivers with different protocols will require users to provide a default port.	null	1234
iamTokenExpiration	Integer	No	Overrides the default IAM token cache expiration in seconds	870	123
httpClientSocketTimeout	Integer	No	The socket timeout value in milliseconds for the HttpClient used by the OktaAuthPlugin.	60000	60000
httpClientConnectTimeout	Integer	No	The connect timeout value in milliseconds for the HttpClient used by the OktaAuthPlugin.	60000	60000
sslInsecure	Boolean	No	Indicates whether or not the SSL connection is secure or not. If not, it will allow SSL connections to be made without validating the server's certificates.	false	true

Sample code

OktaAuthPluginExample.java

Using Okta Authentication with Global Databases

When using Okta authentication with Amazon Aurora Global Databases, the IAM user or role requires the additional rds:DescribeGlobalClusters permission. This permission allows the driver to resolve the Global Database endpoint to the appropriate regional cluster for IAM token generation.

Example IAM policy:

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

Telemetry Metrics

When telemetry is enabled and a metrics backend is configured through telemetryMetricsBackend, this plugin submits the following metrics:

Metric name	Metric type	Description
oktaAuth.fetchToken.count	Counter	Number of IAM authentication tokens generated after a SAML assertion exchange. Incremented when no valid cached token is available, and again when a login failure with a cached token triggers a retry with a freshly generated token.
oktaAuth.tokenCache.size	Gauge	Number of entries currently held in the authentication token cache.

Fetching the SAML assertion from Okta is recorded as a trace segment (Fetch OKTA SAML Assertion) rather than a metric.

See Monitoring for the metrics submitted by other plugins.