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.

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
- AWS Java SDK STS v2.7.x
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.

Note

Since AWS Java SDK RDS v2.x size is around 5.4Mb (22Mb including all RDS SDK dependencies), some users may experience difficulties using the plugin due to limited available disk size. In such cases, the AWS Java SDK RDS v2.x dependency may be replaced with just two dependencies which have a smaller footprint (around 300Kb in total):

software.amazon.awssdk:http-client-spi
software.amazon.awssdk:auth

It's recommended to use AWS Java SDK RDS v2.x when it's possible.

Bundled Uber JAR

Included in AWS JDBC Driver release, is an Uber JAR that bundles the AWS JDBC Driver 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-2.3.7.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.

Note

The bundled Uber JAR may trigger warnings of duplicate entries in the JAR Manifest File. This is because the bundle Uber JAR Manifest file also includes the JAR Manifest file of its dependencies, and as a result will trigger warnings.

How to use the Federated Authentication Plugin with the AWS JDBC Driver

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.

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.
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.
Add the plugin code federatedAuth to the wrapperPlugins value, or to the current driver profile.
Specify parameters that are required or specific to your case.