chore: update documentation to new authentication methods (#133)

* chore: update documentation to new authentication methods skyscrapers/platform#1275 * chore: update documentation to new authentication methods skyscrapers/platform#1275 * fix: markdown error * fix: markdown error * chore: simplify * chore: simplify * fix: rendering
skyscrapers · Oct 24, 2024 · eac0484 · eac0484
1 parent 48a8886
commit eac0484
Show file tree

Hide file tree

Showing 9 changed files with 123 additions and 7 deletions.
diff --git a/aws/cloudformation_templates/sks_admin.yml b/aws/cloudformation_templates/sks_admin.yml
@@ -0,0 +1,31 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: CloudFormation template for a admin IAM role with trust policy towards Skyscrapers
+
+Parameters:
+  SkyscrapersMasterAccount:
+    Type: String
+    Description: "The account ID for the Skyscrapers master account"
+    Default: "910233315570"
+
+Resources:
+  SksReadonlyRole:
+    Type: "AWS::IAM::Role"
+    Properties:
+      RoleName: "sks-admin"
+      Path: "/skyscrapers/ops/"
+      Description: "Role used by Skyscrapers engineers to obtain admin access in the AWS account."
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Sid: "AllowAssumeRoleFromSkyscrapersMasterSSO"
+            Effect: "Allow"
+            Action:
+              - "sts:AssumeRole"
+            Principal:
+              AWS:
+                - !Sub "arn:aws:iam::${SkyscrapersMasterAccount}:root"
+            Condition:
+              ArnLike:
+                "aws:PrincipalArn": !Sub "arn:aws:iam::${SkyscrapersMasterAccount}:role/aws-reserved/sso.amazonaws.com/eu-west-1/AWSReservedSSO_CustomerAdmins_*"
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/AdministratorAccess
diff --git a/aws/cloudformation_templates/sks_ro.yml b/aws/cloudformation_templates/sks_ro.yml
@@ -0,0 +1,31 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: CloudFormation template for a read-only IAM role with trust policy towards Skyscrapers
+
+Parameters:
+  SkyscrapersMasterAccount:
+    Type: String
+    Description: "The account ID for the Skyscrapers master account"
+    Default: "910233315570"
+
+Resources:
+  SksReadonlyRole:
+    Type: "AWS::IAM::Role"
+    Properties:
+      RoleName: "sks-readonly"
+      Path: "/skyscrapers/ops/"
+      Description: "Role used by Skyscrapers engineers to obtain read only access in the AWS account."
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Sid: "AllowAssumeRoleFromSkyscrapersMasterSSO"
+            Effect: "Allow"
+            Action:
+              - "sts:AssumeRole"
+            Principal:
+              AWS:
+                - !Sub "arn:aws:iam::${SkyscrapersMasterAccount}:root"
+            Condition:
+              ArnLike:
+                "aws:PrincipalArn": !Sub "arn:aws:iam::${SkyscrapersMasterAccount}:role/aws-reserved/sso.amazonaws.com/eu-west-1/AWSReservedSSO_CustomerReadOnly_*"
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/ReadOnlyAccess
diff --git a/aws/iam_delegated_access.md b/aws/iam_delegated_access.md
@@ -1,9 +1,63 @@
 # How to provide Skyscrapers access to your AWS account
 
-1. Log into the AWS Console of the account you want to give us access to
-2. Go to IAM
-3. Create a new role. Choose type Another AWS account
-4. Enter the ID of our NOC account `568346047405`
-5. Attach the required policy (for example `ReadOnlyAccess` or `AdministratorAccess`)
-6. Set Role name `skyscrapers_full_operators`
-7. Provide us your account IDs
+## Overview
+
+In order to provide Skyscrapers with access to your AWS account(s), you can use this documentation to configure your accounts with the necessary permissions and trust relationship towards Skyscrapers. This will allow Skyscrapers engineers to assume these roles and perform the necessary tasks in your account.
+
+The following roles can be created:
+
+- The [ReadOnly IAM role](./cloudformation_templates/sks_ro.yml) gets deployed with the `ReadOnlyAccess` policy. This allows Skyscrapers engineers to obtain read-only access in the AWS account. This role is useful for monitoring, auditing, and troubleshooting purposes.
+- [Admin IAM role](./cloudformation_templates/sks_admin.yml) gets deployed with the `AdministratorAccess` policy. This allows Skyscrapers engineers to obtain full access in the AWS account. This role is useful for performing administrative tasks, such as creating, modifying, and deleting resources.
+
+This guide will walk you through the steps to create an ReadOnly and Admin IAM role in your AWS account through CloudFormation.
+
+## Prerequisites
+
+- You must have an AWS account with sufficient permissions to create IAM roles and apply CloudFormation stacks.
+- Familiarity with CloudFormation and AWS IAM concepts is recommended but not required.
+
+## Steps to Apply the Template
+
+1. **Download the CloudFormation Template**
+
+Download the CloudFormation YAML template file(s) you want to apply using the following link or copy the content below:
+
+- [ReadOnly IAM role](./cloudformation_templates/sks_ro.yml)
+- [Admin IAM role](./cloudformation_templates/sks_admin.yml)
+
+### Deploy the Template via the AWS Management Console
+
+> [!NOTE]
+> If you encounter any issues or have questions, please contact the Skyscrapers support team for assistance.
+
+1. Log in to the [AWS Management Console](https://aws.amazon.com/console/).
+2. Navigate to **CloudFormation** using the search bar or [click here](https://eu-west-1.console.aws.amazon.com/cloudformation/home).
+   ![CloudFormation](./img/CF_home.png)
+3. Click **Create stack** if this is your first stack or alternatively at the top right and select **With new resources (standard)**.
+4. In the **Create Stack** page:
+   - Choose **Upload a template file** and upload the downloaded YAML file.
+   - Click **Next**.
+   ![Create Stack](./img/step1.png)
+5. Provide a **Stack Name** (e.g., `Skyscrapers-Readonly-Access`) and click **Next** to proceed.
+   ![Stack Name](./img/step2.png)
+6. Under **Configure stack options**, you can add stack-level tags if desired and click **Next** to proceed.
+   - You'll need to acknowledge that the template may create IAM resources as the template creates IAM roles.
+   ![Stack Configuration](./img/step3.png)
+7. Review your stack configuration, and check the box acknowledging the creation of IAM resources.
+   ![Review](./img/step4.png)
+8. Click **Create stack** to start the deployment.
+9. Verify the deployment status in the CloudFormation console.
+   ![Deployment](./img/deploy.png)
+
+Once the deployment is complete, navigate to the **CloudFormation** console and ensure that the status of your stack shows **CREATE_COMPLETE**.
+
+To verify the created role:
+
+1. Go to the **IAM Console**.
+2. Under **Roles**, find the role named `sks-readonly` and/or `sks-admin`.
+3. Review the trust relationship and the attached policies to ensure everything is set up correctly.
+
+## Updating or Deleting the Stack
+
+- To **update** the stack, you can re-upload a modified version of the template in the CloudFormation console and choose **Update Stack**.
+- To **delete** the stack, navigate to the CloudFormation console, select the stack, and click **Delete**.
diff --git a/aws/img/CF_home.png b/aws/img/CF_home.png
diff --git a/aws/img/deploy.png b/aws/img/deploy.png
diff --git a/aws/img/step1.png b/aws/img/step1.png
diff --git a/aws/img/step2.png b/aws/img/step2.png
diff --git a/aws/img/step3.png b/aws/img/step3.png
diff --git a/aws/img/step4.png b/aws/img/step4.png