Merge pull request #3338 from EnterpriseDB/docs/big_animal_iam_feature

Updates for IAM authentication feature
EnterpriseDB · Dec 1, 2022 · 65cfc6e · 65cfc6e · github-actions · Dec 1, 2022
2 parents 0cab225 + 5e312c2
commit 65cfc6e
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 1 deletion.
diff --git a/product_docs/docs/biganimal/release/getting_started/creating_a_cluster/index.mdx b/product_docs/docs/biganimal/release/getting_started/creating_a_cluster/index.mdx
@@ -149,7 +149,9 @@ When enabling read-only workloads, keep in mind the following:
 
 For information on replication lag while using read-only workloads, see [Synchronous replication](/biganimal/latest/overview/02_high_availability/#synchronous-replication). 
 
+### Authentication
 
+Enable **Identity and Access Management (IAM) Authentication** to turn on the ability to log in to Postgres using your AWS IAM credentials. For this feature to take effect, after you create the cluster, you must add each user to a role that uses AWS IAM authentication in Postgres. For details, see [IAM authentication for Postgres](../../using_cluster/01_postgres_access/#iam_authentication_for_postgres).
 
 ## What’s next
 

diff --git a/product_docs/docs/biganimal/release/using_cluster/01_postgres_access.mdx b/product_docs/docs/biganimal/release/using_cluster/01_postgres_access.mdx
@@ -76,3 +76,39 @@ If a single database is used to host multiple schemas, create a database owner a
     prod1=# create schema app1 authorization app1;
     prod1=# create schema app2 authorization app2;
     ```
+## IAM authentication for Postgres
+
+Any AWS user with an AWS account connected to a BigAnimal subscription who has the Postgres role of "iam_aws" can authenticate to the database using their AWS IAM credentials.
+
+### Configuring IAM for Postgres
+
+Provision your cluster before configuring IAM for Postgres.
+
+1. In BigAnimal, turn on the IAM authentication feature when creating or modifying the cluster:
+    1. On the **Additional Settings** tab, under **Authentication**, select **Identity and Access Management (IAM) Authentication**. 
+    1. Select **Create Cluster** or **Save**.
+1. In AWS, get the ARN of each IAM user requiring database access. In the AWS account connected to BigAnimal, use AWS Identity and Access Management (IAM) to perform user management. See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_manage.html). 
+
+1. In Postgres, if the IAM role doesn’t exist yet, run this Postgres command:
+
+    ```
+    CREATE ROLE "iam_aws";
+    ```
+
+1. For each IAM user, run this Postgres command:
+
+    ```
+    CREATE USER "<ARN>" IN ROLE iam_aws;
+    ```
+
+### Logging in to Postgres using IAM credentials
+
+If IAM integration is configured for your cluster, you can log in to Postgres using your AWS Amazon Resource Name (ARN) and access key. Using this ARN + access key combination allows you to connect to your Postgres database using your AWS IAM standard credentials.
+
+!!! Note 
+    You can continue to log in using your Postgres username and password. However, doing so doesn’t provide IAM authentication even if this feature is configured.
+
+1. Using your AWS CLI or Cloud shell, obtain your ARN and access key. For guidance on obtaining your ARN and access key, see [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
+1. Connect to Postgres using your IAM credentials.
+1. When prompted for the password, enter your access key (&lt;access key ID>:&lt;secret access key>).
+
diff --git a/...t_docs/docs/biganimal/release/using_cluster/03_modifying_your_cluster/index.mdx b/...t_docs/docs/biganimal/release/using_cluster/03_modifying_your_cluster/index.mdx
@@ -40,7 +40,8 @@ You can also modify your cluster by installing Postgres extensions. See [Postgre
  | Database configuration parameters                    | DB Configuration | \-                                                                                                                                                                                                                                                                                 |
  | Retention period for backups                         | Additional Settings          | \-                                                                                                                                                                                                                                                                                 |
  | Read-only workloads                                  | Additional Settings | Enabling read-only workloads can incur higher cloud infrastructure charges. |
-
+ | Identity and Access Management (IAM) Authentication  | Additional Settings | Turn on the ability to log in to Postgres using AWS IAM credentials. You must then run a command to add each user’s credentials to a role that uses IAM authentication in Postgres. See [IAM authentication for Postgres](../01_postgres_access/#iam-authentication-for-postgres). 
+
 5.  Save your changes.
  !!! Note
      Saving changes might require a database restart.