Skip to content

chore: Improve SuperAdmin docs #747

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Dan Miller (milldr) merged 2 commits into from
May 9, 2025
Merged

chore: Improve SuperAdmin docs #747

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a00ac17
clean up superadmin docs
milldr May 1, 2025
53c2b11
Update docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx
milldr May 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
215 changes: 68 additions & 147 deletions docs/layers/accounts/tutorials/how-to-create-superadmin-user.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,191 +5,112 @@ sidebar_position: 23
description: Create `SuperAdmin` for secure, controlled AWS root access.
---
import Intro from '@site/src/components/Intro';
import KeyPoints from '@site/src/components/KeyPoints';
import Steps from '@site/src/components/Steps';
import Step from '@site/src/components/Step';
import StepNumber from '@site/src/components/StepNumber';

<Intro>
The `SuperAdmin` user is necessary for performing administrative functions that IAM roles cannot, ensuring secure and controlled access to the root account while minimizing risks. These are the step-by-step instructions for creating a `SuperAdmin` user in AWS, including setting permissions, enabling MFA, and securely storing credentials in 1Password.
The `SuperAdmin` user is recommended for performing certain high-risk administrative tasks that modify IAM permissions affecting users on SSO or SAML. We don't recommend making these types of changes with your own SSO or SAML identity because a misconfiguration could lead to account lockout. This guide outlines the steps to create a secure `SuperAdmin` user in AWS, including setting permissions, enabling MFA, and storing credentials safely in 1Password.
</Intro>

[REFARCH-73 - Provision SuperAdmin User for Root Level IAM Management](/layers/accounts/prepare-aws-organization/#create-the-superadmin-iam-user)

### Prerequisites

[Follow the prerequisites steps in the How-to Get Started guide](/layers/project/#0-prerequisites)

## Basic Instructions

Login to the AWS `root` account using the root credentials.

In the IAM console, select "Users" on the sidebar.

1. Click "Add users" button.
1. Enter "SuperAdmin" for "User name". Leave "AWS Management Console access unchecked." Click "Next".
1. Under "Set permissions", select "Attach existing policies directly". A list should appear, from which you should
check "AdministratorAccess". Click "Next".
1. Review and click "Create user".
1. The "Success" page should show you the "Access key ID" and hidden Secret access key" which can be revealed by
clicking "Show". Copy these to your secure credentials storage as you will need them shortly.
1. Click "Close" to return to the IAM console. Select "Users" on the sidebar if it is not already selected. You should
see a list of users. Click the user name "SuperAdmin" (which should be a hyperlink) to take you to the Users ->
SuperAdmin "Summary" page.
1. Click on the "Security credentials" tab. In the 'Multi-Factor Authentication (MFA)' section, click "Assign a virtual
MFA device".
1. Enter a name that corresponds to how you will store the MFA token (e.g. '1password')
1. Select 'Authenticator App' as the MFA device type and click 'Next'.
1. Follow the instructions to set up the MFA device. Store the TOTP key in your secure credentials storage.
1. You should be taken back to the "Security Credentials" tab, but now the "Assigned MFA device" field should have an
ARN like `arn:aws:iam::<account-number>:mfa/SuperAdmin`. Copy the ARN and keep it with the Access Key.
1. Now we need to create an Access Key for CLI access. Click on the "Create Access Key" under "Access Keys".
1. Select "Command Line Interface" and click the "I understand..." checkbox then click 'Next'.
1. Enter a description if you like, such as 'SuperAdmin CLI Access' and click 'Create'.

### Storing SuperAdmin credentials in 1Password

The `SuperAdmin` credentials should be properly stored in 1Password. Relative to other potential 1Password item types,
the most appropriate 1Password item type for these credentials is `login`. Since these are programmatic credentials and
not an actual login with an endpoint from which the website favicon can be retrieved, the icon for this item should be
manually set to the [AWS logo](https://github.com/cryptotradev/vymd-infra/blob/main/docs/img/awspng). Additionally, the
password field should be kept empty. For convenience in retrieving the TOTP code when using Leapp, save `com.leapp.app`
as a website URL.

Set the username to `SuperAdmin`, create fields for the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and the TOTP
(known as One Time Password field type in 1password) via the AWS virtual MFA device's secret.

Finally, leave a note for this item in the following format:

```
This account's Access Key should be made inactive when not needed.

CURRENT STATUS: ACTIVE

Use this account for API/command line access to administrative functions that IAM roles cannot do, such as provision IAM roles.

This account should not be allowed to log in to the AWS console, and therefore does not have a password.

Root account ID: [AWS ACCOUNT ID]

User ARN arn:aws:iam::[AWS ACCOUNT ID]:user/SuperAdmin

MFA Device ARN arn:aws:iam::[AWS ACCOUNT ID]:mfa/SuperAdmin

```

The resulting entry in 1password should appear as follows:

Hit save once you are done. Once the SuperAdmin credentials need to be disabled, do not forget to update the notes in
this item.
<Steps>
<Step>
### <StepNumber/> Create the SuperAdmin User

<img src="/assets/refarch/image-20211016-220615.png" /><br/>
First, create the SuperAdmin IAM user in the AWS web console.

### Detailed Instructions
<Steps>
1. Login to the AWS `root` account using the root credentials.

These are just some more detailed step-by-step instructions. These are redundant with the basic instructions and might
be out of date as the AWS web console interface changes.
1. In the IAM console, select "Users" on the sidebar.
<img src="/assets/refarch/image-20210720-181056.png" />

1. Login to the AWS `root` account using the root credentials from 1Password
1. Click "Add users" button
<img src="/assets/refarch/image-20210720-181130.png" />
<img src="/assets/refarch/image-20210720-181200.png" />

2. Navigate to the IAM console page
<img src="/assets/refarch/image-20210720-181056.png" /><br/>
1. Enter "SuperAdmin" for "User name" and check "Programmatic access" and leave "AWS Management Console access" unchecked. Click "Next: Permissions"
<img src="/assets/refarch/image-20210720-181251.png" />

3. In the IAM console, select `Users` on the sidebar
1. Under "Set permissions", select "Attach existing policies directly". A list should appear, from which you should check "AdministratorAccess". Click "Next: Tags"
<img src="/assets/refarch/image-20210720-181512.png" />

4. <img src="/assets/refarch/image-20210720-181130.png" /><br/>Click `Add users` button <img src="/assets/refarch/image-20210720-181200.png" /><br/>
1. Skip the tags, Click "Next: Review"

5. Enter "SuperAdmin" for `User name` and check `Programmatic access` and leave `AWS Management Console access`
unchecked. Click `Next: Permissions` at the bottom right corner of the page
1. Review and click "Create user"

<img src="/assets/refarch/image-20210720-181251.png" /><br/>
1. The Success page should show you the "Access key ID" and hidden "Secret access key" which can be revealed by clicking "Show". Copy these to your secure credentials storage as you will need them shortly
<img src="/assets/refarch/image-20210720-181626.png" />

6. Under `Set permissions` , select `Attach existing policies directly` . A list should appear, from which you should
check `AdministratorAccess` . Click `Next: Tags` at the bottom right corner of the page
1. Click "Close" to return to the IAM console. Select "Users" on the sidebar if it is not already selected. You should see a list of users. Click the user name "SuperAdmin" (which should be a hyperlink) to take you to the Users -> SuperAdmin "Summary" page
<img src="/assets/refarch/image-20210720-182019.png" />

<img src="/assets/refarch/image-20210720-181512.png" /><br/>
1. On the "Users -> SuperAdmin" "Summary" page, click on the "Security credentials" tab

7. Skip the tags, Click `Next: Review` at the bottom right corner of the page
1. In the "Sign-in credentials" section, find: "Assigned MFA device: Not assigned | Manage" and click "Manage"
<img src="/assets/refarch/image-20210720-182257.png" />

8. Review and click `Create user` at the bottom right corner of the page
1. Choose "Virtual MFA device" and click "Continue"
<img src="/assets/refarch/image-20210720-182421.png" />

9. The Success page should show you the `Access key ID` and hidden `Secret access key` which can be revealed by clicking
`Show` , copy these to your secure credentials storage as you will need them shortly
1. Press the "Show secret key" button
<img src="/assets/refarch/image-20210721-151123.png" />

<img src="/assets/refarch/image-20210720-181626.png" /><br/>
1. Copy the key into 1Password as a AWS Credential using the "MFA" field
<img src="/assets/refarch/image-20210721-151429.png" />

10. Click `Close` at the bottom right corner to return to the IAM console and select `Users` on the sidebar if it is not
already selected
1. Use the MFA codes from 1Password to complete the MFA setup process (you will input 2 consecutive codes)
<img src="/assets/refarch/image-20210721-151622.png" />

11. You should a list of users. Click the user name `SuperAdmin` (which should be a hyperlink)
1. You should be taken back to the "Security Credentials" tab, but now the "Assigned MFA device" field should have an ARN like `arn:aws:iam::<account-number>:mfa/SuperAdmin`
<img src="/assets/refarch/image-20210720-182914.png" />

<img src="/assets/refarch/image-20210720-182019.png" /><br/>
1. Copy the ARN and keep it with the Access Key in 1Password

12. On the `Users -> SuperAdmin` "Summary" page, click on the `Security credentials` tab
1. Now we need to create an Access Key for CLI access. Click on the "Create Access Key" under "Access Keys"

13. In the `Sign-in credentials` section, find: `Assigned MFA device: Not assigned | Manage` and click `Manage`
1. Select "Command Line Interface" and click the "I understand..." checkbox then click 'Next'

<img src="/assets/refarch/image-20210720-182257.png" /><br/>
1. Enter a description if you like, such as 'SuperAdmin CLI Access' and click 'Create'
</Steps>
</Step>

14. Choose `Virtual MFA device` and click `Continue`
<Step>
### <StepNumber/> Store SuperAdmin Credentials in 1Password

<img src="/assets/refarch/image-20210720-182421.png" /><br/>
The `SuperAdmin` credentials should be properly stored in 1Password. Relative to other potential 1Password item types, the most appropriate 1Password item type for these credentials is `login`. Since these are programmatic credentials and not an actual login with an endpoint from which the website favicon can be retrieved. Additionally, the password field should be kept empty. For convenience in retrieving the TOTP code when using Leapp, save `com.leapp.app` as a website URL.

15. Press the `Show secret key` button
<Steps>
1. Set the username to `SuperAdmin`
1. Create fields for the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and the TOTP (known as One Time Password field type in 1password) via the AWS virtual MFA device's secret
1. Add a note in the following format:

<img src="/assets/refarch/image-20210721-151123.png" /><br/>
```
This account's Access Key should be made inactive when not needed.

16. Copy the key into 1Password as a AWS Credential using the “MFA” field
CURRENT STATUS: ACTIVE

<img src="/assets/refarch/image-20210721-151429.png" /><br/>
Use this account for API/command line access to administrative functions that IAM roles cannot do, such as provision IAM roles.

17. Use the MFA codes from 1Password to complete the MFA setup process (you will input 2 consecutive codes)
This account should not be allowed to log in to the AWS console, and therefore does not have a password.

<img src="/assets/refarch/image-20210721-151622.png" /><br/>
Root account ID: [AWS ACCOUNT ID]

18. You should be taken back to the `Security Credentials` tab, but now the `Assigned MFA device` field should have an
ARN like `arn:aws:iam::<account-number>:mfa/SuperAdmin`
User ARN arn:aws:iam::[AWS ACCOUNT ID]:user/SuperAdmin

<img src="/assets/refarch/image-20210720-182914.png" /><br/>
MFA Device ARN arn:aws:iam::[AWS ACCOUNT ID]:mfa/SuperAdmin
```

19. Copy the ARN and keep it with the Access Key in 1Password
The resulting entry in 1password should appear as follows:
<img src="/assets/refarch/image-20211016-220615.png" />

20. Configure AWS profile with the SuperAdmin user credentials:
1. Hit save once you are done. Once the SuperAdmin credentials need to be disabled, do not forget to update the notes in this item
</Steps>
</Step>
</Steps>

21. If it does not already exist on your host computer, create the file `$HOME/.aws/config`
## References

22. Add the following lines to the end of the `$HOME/.aws/config` file:

````ini`

`[profile SuperAdmin]`

`region = us-west-2`

`default_region = us-west-2`

`mfa_serial = arn:aws:iam::<account-number>:mfa/SuperAdmin`

```

replacing `us-west-2` with the primary region where you will be hosting your company's infrastructure,

and `arn:aws:iam::<account-number>:mfa/SuperAdmin` with the "Assigned MFA device" ARN from the previous step.

21.

:::tip

Done!

:::

### Related articles

:::note

The content by label feature displays related articles automatically, based on labels you choose. To edit options for this feature, select the placeholder below and tap the pencil icon.

:::

| Related issues | |
| -------------- | --- |

```
[REFARCH-73 - Provision SuperAdmin User for Root Level IAM Management](/layers/accounts/prepare-aws-organization/#create-the-superadmin-iam-user)
Loading