Skip to content

UsingTheFederatedAuthPlugin.md

Latest commit

 

History

History
88 lines (68 loc) · 12.1 KB

UsingTheFederatedAuthPlugin.md

File metadata and controls

88 lines (68 loc) · 12.1 KB
Raw

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

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:
  2. Set up an IAM Identity Provider and IAM role. The IAM role should be using the IAM policy set up in step 1.
  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 }

MySQL requires an encrypted connection

The Federated Authentication Plugin authenticates with a generated token, which Aurora MySQL asks the client to send using the server's mysql_clear_password authentication plugin. The underlying MySQL driver refuses that plugin unless enableCleartextPlugin is enabled, so set the ssl connection property when using federatedAuth with MySQL — the wrapper then enables the option for you, and the token is only ever sent over an encrypted connection.

Without ssl the wrapper logs a warning, leaves the option unset, and the connection attempt fails; it will not send an authentication token unencrypted implicitly. PostgreSQL is unaffected.

For the full explanation, including how to opt out, see MySQL requires an encrypted connection in the IAM Authentication Plugin documentation.

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": "*"
    }
  ]
}