Federated Authentication Plugin

The Federated Authentication Plugin adds support for authentication via Federated Identity and then database access via IAM. Currently, Microsoft Active Directory Federation Services (AD FS) and Okta are supported. To see information on how to configure and use Okta authentication, see Using the Okta Authentication Plugin.

Plugin Availability

The plugin is available since version 2.3.2.

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

• To preserve compatibility with customers using the community driver, this plugin requires the following runtime dependencies to be registered in the classpath:
  • AWS Java SDK RDS v2.7.x or later
  • AWS Java SDK STS v2.7.x or later
• 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 ADFS or IAM resources, therefore 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 Federated Authentication with Global Databases section as well.

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

Bundled Uber JAR

Included in AWS Advanced JDBC Wrapper release, is an Uber JAR that bundles the AWS Advanced JDBC Wrapper and all the package dependencies needed to use the Federated Authentication Plugin. It is suffixed with -bundle-federated-auth.

This JAR is a drop-in ready solution and is recommended for customers who do not have an automated package manager like Maven or Gradle. As this plugin has a number of transitive dependencies, the goal of this JAR is to eliminate the need to manually source all the dependencies and avoid potential issues with managing them. In that spirit, the dependencies in this JAR are shaded with the prefix shaded to avoid potential package conflicts with pre-existing packages in your environment.

It is important to note that the Uber JAR is bundled with the AWS Java RDS SDK and is larger (15 MB) than our aws-advanced-jdbc-wrapper-4.3.0.jar. So please take that into account when deciding if this solution is for you.

If you would like to download and install the bundled Uber JAR, follow these instructions.

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

Enabling the Federated Authentication Plugin

Note: AWS IAM database authentication is needed to use the Federated Authentication Plugin. This is because after the plugin acquires the authentication token (ex. SAML Assertion in the case of AD FS), the authentication token is then used to acquire an AWS IAM token. The AWS IAM token is then subsequently used to access the database.

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. Set up an IAM Identity Provider and IAM role. The IAM role should be using the IAM policy set up in step 1.
   • If needed, review the documentation about creating IAM identity providers. For AD FS, see the documentation about creating IAM SAML identity providers.
3. Add the plugin code federatedAuth to the wrapperPlugins value, or to the current driver profile.
4. Specify parameters that are required or specific to your case.

Federated 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
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
idpName	String	No	The name of the Identity Provider implementation used.	adfs	adfs
idpPort	String	No	The port that the host for the authentication service listens at.	443	1234
rpIdentifier	String	No	The relaying party identifier.	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 FederatedAuthenticationPlugin.	60000	60000
httpClientConnectTimeout	Integer	No	The connect timeout value in milliseconds for the HttpClient used by the FederatedAuthenticationPlugin.	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

FederatedAuthPluginExample.java

Using Federated Authentication with Global Databases

When using Federated 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
federatedAuth.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.
federatedAuth.tokenCache.size	Gauge	Number of entries currently held in the authentication token cache.

Fetching the SAML assertion from the identity provider is recorded as a trace segment (Fetch ADFS SAML Assertion) rather than a metric.

See Monitoring for the metrics submitted by other plugins.