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.

Prerequisites

• This plugin requires the following packages to be installed:
  • @aws-sdk/rds-signer
  • aws-sdk
  • axios-cookiejar-support
  • entities

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.

How to use the Federated Authentication Plugin with the AWS Advanced NodeJS 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 plugins connection parameter.
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_username
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
idpPort	Number	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	Number	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. Target drivers with different protocols will require users to provide a default port.	null	1234
iamTokenExpiration	Number	No	Overrides the default IAM token cache expiration in seconds.	900	123
httpsAgentOptions	Object	No	This property adds parameters to the httpsAgent that connects to the hosting URL. For more information on the parameters, see this documentation.	null	{ timeout: 5000 }