Skip to content

Files

Latest commit

 

History

History
68 lines (51 loc) · 6.86 KB

UsingTheIamAuthenticationPlugin.md

File metadata and controls

68 lines (51 loc) · 6.86 KB

AWS IAM Authentication Plugin

What is IAM?

AWS Identity and Access Management (IAM) grants users access control across all Amazon Web Services. IAM supports granular permissions, giving you the ability to grant different permissions to different users. For more information on IAM and it's use cases, please refer to the IAM documentation.

AWS IAM Database Authentication

The AWS Advanced NodeJS Wrapper supports Amazon AWS Identity and Access Management (IAM) authentication. IAM database authentication use is limited to certain database engines. For more information on limitations and recommendations, please review the IAM documentation.

Prerequisites

How do I use IAM with the AWS Advanced NodeJS Wrapper?

  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:
    1. If needed, review the documentation about creating a new database.
    2. If needed, review the documentation about modifying an existing database.
  2. Set up an AWS IAM policy for AWS IAM database authentication.
  3. Create a database account using AWS IAM database authentication. This will be the user specified in the connection parameters.
    1. Connect to your database of choice using primary logins.
      1. For a MySQL database, use the following command to create a new user:
        CREATE USER example_user_name IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
      2. For a PostgreSQL database, use the following command to create a new user:
        CREATE USER db_userx; GRANT rds_iam TO db_userx;
  4. Add the plugin code iam to the plugins connection parameter.
Parameter Value Required Description Default Value Example Value
iamDefaultPort String No This property will override the default port that is used to generate the IAM token. The default port is determined based on the underlying database. null 1234
iamHost String Only required when using custom endpoints This property will override the default hostname that is used to generate the IAM token. The host value from the connection configuration database.cluster-hash.us-east-1.rds.amazonaws.com
iamRegion String No This property will override the default region that is used to generate the IAM token. If the property is not set, the wrapper will attempt to parse the region from the host provided in the configuration parameters. null us-east-2
iamTokenExpiration Number No This property determines how long an IAM token is kept in the driver cache before a new one is generated. The default expiration time is set to be 15 minutes. Note that IAM database authentication tokens have a lifetime of 15 minutes. 900 600

This plugin requires a valid set of AWS credentials to retrieve the database credentials from AWS Secrets Manager. The AWS credentials must be located in one of these locations supported by the AWS SDK's default credentials provider. See also at AWS Credentials Configuration

Using the IAM Authentication Plugin with Custom Endpoints

When using AWS IAM database authentication with a custom domain or an IP address, in addition to the clusterInstanceHostPattern variable, the iamHost must be specified and must point to a valid Amazon endpoint, i.e. db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com.

For instance, if you are connecting to an instance with the IP address of 12.345.678.90 and an instance endpoint of db-identifier.XYZ.us-east-2.rds.amazonaws.com and you are connecting using the IP endpoint, your connection configuration should look like the following:

const config = {
  host: "12.345.678.90",
  port: port,
  user: username,
  plugins: "iam",
  database: database,
  iamRegion: "us-east-1",
  iamHost: "db-identifier.XYZ.us-east-2.rds.amazonaws.com",
  clusterInstanceHostPattern: "?.XYZ.us-east-2.rds.amazonaws.com",
  ssl: {
    ca: readFileSync("path/to/ssl/certificate.pem").toString()
  }
};

You can learn more about clusterInstanceHostPattern here.

Sample code

IAM Authentication Plugin example for PostgreSQL
IAM Authentication Plugin example for MySQL