Skip to content

Commit bfe32aa

Browse files
aaronchung-bitquillkarenc-bq
aaronchung-bitquill
and
karenc-bq
authored
docs: FederatedAuthPlugin (#787)
Co-authored-by: Karen <[email protected]>
1 parent 364f33a commit bfe32aa

File tree

2 files changed

+50
-2
lines changed

2 files changed

+50
-2
lines changed

‎docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Federated Authentication Plugin
2+
3+
The Federated Authentication Plugin adds support for authentication via Federated Identity and then database access via IAM.
4+
Currently, only Microsoft Active Directory Federation Services (AD FS) is supported.
5+
6+
## What is Federated Identity
7+
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.
8+
9+
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.
10+
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.
11+
12+
## Prerequisites
13+
> [!WARNING]
14+
> To preserve compatibility with customers using the community driver, this plugin requires the [AWS Java SDK RDS v2.7.x](https://central.sonatype.com/artifact/software.amazon.awssdk/rds) and the [AWS Java SDK STS v2.7.x](https://central.sonatype.com/artifact/software.amazon.awssdk/sts) to be included separately in the classpath. The AWS Java SDK RDS and AWS Java SDK STS are runtime dependencies and must be resolved.
15+
16+
## How to use the Federated Authentication Plugin with the AWS JDBC Driver
17+
18+
### Enabling the Federated Authentication Plugin
19+
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.
20+
21+
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:
22+
- If needed, review the documentation about [IAM authentication for MariaDB, MySQL, and PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html).
23+
2. Set up an IAM Identity Provider and IAM role. The IAM role should be using the IAM policy set up in step 1.
24+
- If needed, review the documentation about [creating IAM identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create.html). For AD FS, see the documention about [creating IAM SAML identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html).
25+
3. Add the plugin code `federatedAuth` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value, or to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters).
26+
4. Specify parameters that are required or specific to your case.
27+
28+
### Federated Authentication Plugin Parameters
29+
| Parameter | Value | Required | Description | Default Value | Example Value |
30+
|----------------------------|:-------:|:--------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|--------------------------------------------------------|
31+
| `dbUser` | String | Yes | The user name of the IAM user with access to your database. <br>If you have previously used the IAM Authentication Plugin, this would be the same IAM user. <br>For information on how to connect to your Aurora Database with IAM, see this [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.Connecting.html). | `null` | `some_user_name` |
32+
| `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` | `[email protected]` |
33+
| `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` |
34+
| `idpEndpoint` | String | Yes | The hosting URL for the service that you are using to authenticate into AWS Aurora. | `null` | `ec2amaz-ab3cdef.example.com` |
35+
| `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` |
36+
| `iamIdpArn` | String | Yes | The ARN of the Identity Provider. | `null` | `arn:aws:iam::123456789012:saml-provider/adfs_example` |
37+
| `iamRegion` | String | Yes | The IAM region where the IAM token is generated. | `null` | `us-east-2` |
38+
| `idpName` | String | No | The name of the Identity Provider implementation used. | `adfs` | `adfs` |
39+
| `idpPort` | String | No | The port that the host for the authentication service listens at. | `443` | `1234` |
40+
| `rpIdentifier` | String | No | The relaying party identifier. | `urn:amazon:webservices` | `urn:amazon:webservices` |
41+
| `iamHost` | String | No | Overrides the host that is used to generate the IAM token. | `null` | `database.cluster-hash.us-east-1.rds.amazonaws.com` |
42+
| `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` |
43+
| `iamTokenExpiration` | Integer | No | Overrides the default IAM token cache expiration in seconds | `930` | `123` |
44+
| `httpClientSocketTimeout` | Integer | No | The socket timeout value in milliseconds for the HttpClient used by the FederatedAuthenticationPlugin. | `60000` | `60000` |
45+
| `httpClientConnectTimeout` | Integer | No | The connect timeout value in milliseconds for the HttpClient used by the FederatedAuthenticationPlugin. | `60000` | `60000` |
46+
| `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. | `true` | `false` |
47+
48+
## Sample code
49+
[FederatedAuthPluginExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/FederatedAuthPluginExample.java)

‎examples/AWSDriverExample/src/main/java/software/amazon/FederatedAuthPluginExample.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,13 @@ public static void main(String[] args) throws SQLException {
3535

3636
// Enable the AWS Federated Authentication Connection Plugin.
3737
properties.setProperty(PropertyDefinition.PLUGINS.name, "federatedAuth");
38-
properties.setProperty(FederatedAuthPlugin.IDP_NAME.name, "adfs");
3938
properties.setProperty(FederatedAuthPlugin.IDP_ENDPOINT.name, "ec2amaz-ab3cdef.example.com");
4039
properties.setProperty(FederatedAuthPlugin.IAM_ROLE_ARN.name, "arn:aws:iam::123456789012:role/adfs_example_iam_role");
4140
properties.setProperty(FederatedAuthPlugin.IAM_IDP_ARN.name, "arn:aws:iam::123456789012:saml-provider/adfs_example");
4241
properties.setProperty(FederatedAuthPlugin.IAM_REGION.name, "us-east-2");
4342
properties.setProperty(FederatedAuthPlugin.IDP_USERNAME.name, "[email protected]");
4443
properties.setProperty(FederatedAuthPlugin.IDP_PASSWORD.name, "somePassword");
45-
properties.setProperty(PropertyDefinition.USER.name, "someIamUser");
44+
properties.setProperty(FederatedAuthPlugin.DB_USER.name, "someIamUser");
4645

4746
// Try and make a connection:
4847
try (final Connection conn = DriverManager.getConnection(CONNECTION_STRING, properties);

0 commit comments

Comments
 (0)