Skip to content

Commit

Permalink
Merge pull request #73 from ohmurayu/feature/awssso-credential
Browse files Browse the repository at this point in the history 
doc: Update docs to use AWS SSO credential directly
  • Loading branch information
@wmikuriy
wmikuriy authored Sep 2, 2022
2 parents f9f382c + d1c90b7 commit 121ea77
Show file tree
Hide file tree
Showing 4 changed files with 65 additions and 139 deletions.
76 changes: 24 additions & 52 deletions doc/DeployToControlTower.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,10 @@ Registers a hook to perform checks by Linter, Formatter, and Git-Secrets when co

Permanent credentials are also available, but AWS SSO is recommended for ControlTower environments. AWS SSO allows you to log in to the Management Console and run the AWS CLI with SSO authentication.

> NOTE:
>
> Starting with CDK v2.18.0, you can use AWS SSO profiles to deploy the CDK directly, eliminating the need to use wrapping in the authentication process within the profile.
#### 4-1. Check the version of the AWS CLI

AWS CLI - To use the AWS SSO integration, you must use AWS CLIv2.
Expand All @@ -129,83 +133,53 @@ Verify that the output is version 2 or higher
aws-cli/2.3.0 Python/3.8.8 Darwin/20.6.0 exe/x86_64 prompt/off
```

#### 4-2. Introduce aws2-wrap
#### 4-2. Configure an AWS CLI Profile for Audit Account Deployment

AWS CLI - To use AWS SSO integration from a CDK, an open source tool, aws2-wrap ([https://github.com/linaro-its/aws2-wrap]) to the environment where you want to run the CDK

```sh
pip3 install aws2-wrap
```

#### 4-3. Configure an AWS CLI Profile for Audit Account Deployment

Next, configure a CLI profile for deploying to the Audit account in Control Tower. Here, the ID of the management account is `11111111111` and the ID of the Audit account is `2222222222`.
Next, configure a CLI profile for deploying to the Audit account in Control Tower. Here, the ID of the Audit account is `2222222222`.

~/.aws/config

```text
# for Management Account Login
[profile ct-management-sso]
# for Audit Account
[profile ct-audit]
sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/
sso_region = ap-northeast-1
sso_account_id = 1111111111111
sso_account_id = 222222222222
sso_role_name = AWSAdministratorAccess
region = ap-northeast-1
# Accessing with AWSControlTowerExecution Role on Audit Account
[profile ct-audit-exec-role]
role_arn = arn:aws:iam::222222222222:role/AWSControlTowerExecution
source_profile = ct-management-sso
region = ap-northeast-1
# for CDK access to ct-audit-exec-role
[profile ct-audit-exec]
credential_process = aws2-wrap --process --profile ct-audit-exec-role
region = ap-northeast-1
```

> NOTE:
>
> According to the ControlTower specification, in order to deploy to the Audit account, you must first use the `AWSAdministratorAccess` role of the management account You must log in and switch to the `AWSControlTowerExecution` role in the Audit account to perform the action.
> By SSO logging in with the `ct-management-sso`profile, you can use the `ct-audit-exec-role` profile to perform operations on the Audit account It's possible. To access this from the CDK, use the wrapped profile `ct-audit-exec`.
> According to the ControlTower specification, in order to modify the resouces created by ControlTower in the Audit account, you must first use the `AWSAdministratorAccess` role of the management account You must log in and switch to the `AWSControlTowerExecution` role in the Audit account to perform the action.
> BLEA doen't modify resources created by ControlTower, so we use AWSAdministratorAccess role in the Audit account directly.
#### 4-4. Configure an AWS CLI Profile for Guest Account Deployment
#### 4-3. Configure an AWS CLI Profile for Guest Account Deployment

Configure an AWS CLI profile for deploying to the guest account. Here, the ID of the guest account is `123456789012`.

~/.aws/config

```text
# for Guest Account Login
[profile ct-guest-sso]
# for Guest Account
[profile ct-guest]
sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/
sso_region = ap-northeast-1
sso_account_id = 123456789012
sso_role_name = AWSAdministratorAccess
region = ap-northeast-1
# for CDK access to ct-guest-sso
[profile ct-guest]
credential_process = aws2-wrap --process --profile ct-guest-sso
region = ap-northeast-1
```

> NOTE:
>
> SSO login to the guest account with the `ct-guest-sso` profile. To access this from the CDK, we use the wrapped profile `ct-guest`.
#### 4-5. CLI login using AWS SSO
#### 4-4. CLI login using AWS SSO

Log in to AWS SSO with the following command: Here is an example of logging in with `ct-guest-sso`profile.
Log in to AWS SSO with the following command: Here is an example of logging in with `ct-guest`profile.

```sh
aws sso login --profile ct-guest-sso
aws sso login --profile ct-guest
```

This command launches a browser and displays the AWS SSO login screen. If you have entered the guest account administrator username (email address) and password correctly, the screen will return to the terminal, where you can use the AWS CLI to work with the guest account.

> Notes: The `ct-guest` profile authenticates via aws2-warp and is used when running a CDK.
### 5. Set a baseline for notifications in the Audit account (Local)

The Audit account has an SNS Topic created by ControlTower that sends all AWS Config change notifications. Set a baseline to notify Slack of this content.
Expand Down Expand Up @@ -238,7 +212,7 @@ usecases/base-ct-audit/cdk.json
"dev-audit": {
"description": "Context samples for ControlTower Audit Account - Specific account & region",
"env": {
"account": "333333333333",
"account": "222222222222",
"region": "ap-northeast-1"
},
"slackNotifier": {
Expand Down Expand Up @@ -271,24 +245,22 @@ The contents of this setting are as follows.

Log in to your management account using AWS SSO with the following command:

> Audit accounts can only be set up with the `AWSControlTowerExecution` role in the management account (ControlTower specification)
```sh
aws sso login --profile ct-management-sso
aws sso login --profile ct-audit
```

Bootstrap a bucket for CDK to the Audit account (first time only)

```sh
cd usecases/base-ct-audit
npx cdk bootstrap -c environment=dev-audit --profile ct-audit-exec
npx cdk bootstrap -c environment=dev-audit --profile ct-audit
```

Deploy a governance base to the Audit account

```sh
cd usecases/base-ct-audit
npx cdk deploy --all -c environment=dev-audit --profile ct-audit-exec
npx cdk deploy --all -c environment=dev-audit --profile ct-audit
```

You should now be notified of all AWS Config change events for accounts managed by this ControlTower.
Expand Down Expand Up @@ -333,7 +305,7 @@ usecases/base-ct-guest/cdk.json
"stage": {
"description": "Context samples for Staging - Specific account & region ",
"env": {
"account": "111111111111",
"account": "123456789012",
"region": "ap-northeast-1"
},
"envName": "Staging",
Expand Down Expand Up @@ -364,7 +336,7 @@ The contents of this setting are as follows.
Log in to your guest account using AWS SSO.

```sh
aws sso login --profile ct-guest-sso
aws sso login --profile ct-guest
```

Bootstrap a bucket for CDK (first time only).
Expand Down Expand Up @@ -441,7 +413,7 @@ Configure the Context using the same steps as in the Standalone version.
(If you are not logged in) Log in to your guest account using AWS SSO.

```sh
aws sso login --profile ct-guest-sso
aws sso login --profile ct-guest
```

Deploy a guest application.
Expand Down
76 changes: 23 additions & 53 deletions doc/DeployToControlTower_ja.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,10 @@ Git に Commit する際に Linter, Formatter, git-secrets によるチェック

恒久的な認証情報も利用可能ですが、ControlTower 環境では AWS SSO の利用を推奨します。AWS SSO によって、マネジメントコンソールへのログインおよび SSO 認証による AWS CLI の実行が可能です。

> NOTE:
>
> CDK v2.18.0 以降、AWS SSO のプロファイルを使って CDK を直接デプロイできるようになり、プロファイル内の認証プロセスでラッピングを使う必要がなくなりました。
#### 4-1. AWS CLI のバージョンを確認する

AWS CLI - AWS SSO 統合を使うためには、AWS CLIv2 を使う必要があります。
Expand All @@ -129,84 +133,52 @@ aws --version
aws-cli/2.3.0 Python/3.8.8 Darwin/20.6.0 exe/x86_64 prompt/off
```

#### 4-2. aws2-wrap を導入する
#### 4-2. Audit アカウントデプロイ用の AWS CLI プロファイルを設定する

AWS CLI - AWS SSO 統合を CDK から使用するため、オープンソースのツールである aws2-wrap ([https://github.com/linaro-its/aws2-wrap]) を CDK を実行する環境にインストールします

```sh
pip3 install aws2-wrap
```

#### 4-3. Audit アカウントデプロイ用の AWS CLI プロファイルを設定する

次に、Control Tower の Audit アカウントにデプロイするための CLI プロファイルを設定します。ここではマネジメントアカウントの ID を `1111111111111`, Audit アカウントの ID を `222222222222` としています。
次に、Control Tower の Audit アカウントにデプロイするための CLI プロファイルを設定します。ここでは Audit アカウントの ID を `222222222222` としています。

~/.aws/config

```text
# for Management Account Login
[profile ct-management-sso]
# for Audit Account
[profile ct-audit]
sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/
sso_region = ap-northeast-1
sso_account_id = 1111111111111
sso_account_id = 222222222222
sso_role_name = AWSAdministratorAccess
region = ap-northeast-1
# Accessing with AWSControlTowerExecution Role on Audit Account
[profile ct-audit-exec-role]
role_arn = arn:aws:iam::222222222222:role/AWSControlTowerExecution
source_profile = ct-management-sso
region = ap-northeast-1
# for CDK access to ct-audit-exec-role
[profile ct-audit-exec]
credential_process = aws2-wrap --process --profile ct-audit-exec-role
region = ap-northeast-1
```

> NOTE:
>
> ControlTower の仕様により、Audit アカウントにデプロイするためには、まずマネジメントアカウントの `AWSAdministratorAccess` ロールでログインし、Audit アカウントの`AWSControlTowerExecution`ロールにスイッチして処理を実行する必要があります。
>
> `ct-management-sso`プロファイルで SSO ログインすることで、`ct-audit-exec-role`プロファイルを使って Audit アカウント上での操作が可能です。これに CDK からアクセスするため、ラッピングされたプロファイルである `ct-audit-exec` を使用します。
> ControlTower の仕様により、ControlTower が Audit アカウントにデプロイしたリソースを変更する場合は、まずマネジメントアカウントの `AWSAdministratorAccess` ロールでログインし、Audit アカウントの`AWSControlTowerExecution` ロールにスイッチして処理を実行する必要があります。BLEA は ControlTower が作成したリソースを変更しないため、直接 Audit アカウントの AWSAdministratorAccess ロールを使用しています
#### 4-4. ゲストアカウントデプロイ用の AWS CLI プロファイルを設定する
#### 4-3. ゲストアカウントデプロイ用の AWS CLI プロファイルを設定する

ゲストアカウントにデプロイするための AWS CLI プロファイルを設定します。ここではゲストアカウントの ID を`123456789012`としています。

~/.aws/config

```text
# for Guest Account Login
[profile ct-guest-sso]
# for Guest Account
[profile ct-guest]
sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/
sso_region = ap-northeast-1
sso_account_id = 123456789012
sso_role_name = AWSAdministratorAccess
region = ap-northeast-1
# for CDK access to ct-guest-sso
[profile ct-guest]
credential_process = aws2-wrap --process --profile ct-guest-sso
region = ap-northeast-1
```

> NOTE:
>
> `ct-guest-sso`プロファイルで ゲストアカウントに SSO ログインします。これに CDK からアクセスするため、ラッピングされたプロファイルである `ct-guest` を使用します。
#### 4-5. AWS SSO を使った CLI ログイン
#### 4-4. AWS SSO を使った CLI ログイン

次のコマンドで AWS SSO にログインします。ここでは`ct-guest-sso`プロファイルでログインする例を示します。
次のコマンドで AWS SSO にログインします。ここでは`ct-guest`プロファイルでログインする例を示します。

```sh
aws sso login --profile ct-guest-sso
aws sso login --profile ct-guest
```

このコマンドによって ブラウザが起動し、AWS SSO のログイン画面が表示されます。ゲストアカウントの管理者ユーザー名（メールアドレス）とパスワードを正しく入力すると画面がターミナルに戻り、 AWS CLI で ゲストアカウントでの作業が可能になります。

> Notes: `ct-guest`プロファイルは aws2-warp を経由した認証を行なっており、CDK を実行する場合に使用します。
### 5. Audit アカウントに通知用のベースラインを設定する(Local)

Audit アカウントには ControlTower が作成した、すべての AWS Config の変更通知が送られる SNS Topic があります。この内容を Slack に通知するようベースラインを設定します。
Expand Down Expand Up @@ -239,7 +211,7 @@ usecases/base-ct-audit/cdk.json
"dev-audit": {
"description": "Context samples for ControlTower Audit Account - Specific account & region",
"env": {
"account": "333333333333",
"account": "222222222222",
"region": "ap-northeast-1"
},
"slackNotifier": {
Expand Down Expand Up @@ -271,24 +243,22 @@ usecases/base-ct-audit/cdk.json

以下のコマンドで AWS SSO を使ってマネジメントアカウントにログインします。

> Audit アカウントは マネジメントアカウントの `AWSControlTowerExecution` ロールでのみセットアップが可能です（ControlTower の仕様）
```sh
aws sso login --profile ct-management-sso
aws sso login --profile ct-audit
```

Audit アカウントに CDK 用バケットをブートストラップします(初回のみ)

```sh
cd usecases/base-ct-audit
npx cdk bootstrap -c environment=dev-audit --profile ct-audit-exec
npx cdk bootstrap -c environment=dev-audit --profile ct-audit
```

Audit アカウントにガバナンスベースをデプロイします

```sh
cd usecases/base-ct-audit
npx cdk deploy --all -c environment=dev-audit --profile ct-audit-exec
npx cdk deploy --all -c environment=dev-audit --profile ct-audit
```

以上で、この ControlTower 管理下にあるアカウントのすべての AWS Config 変更イベントが通知されるようになります。
Expand Down Expand Up @@ -332,7 +302,7 @@ usecases/base-ct-guest/cdk.json
"stage": {
"description": "Context samples for Staging - Specific account & region ",
"env": {
"account": "111111111111",
"account": "123456789012",
"region": "ap-northeast-1"
},
"envName": "Staging",
Expand Down Expand Up @@ -363,7 +333,7 @@ usecases/base-ct-guest/cdk.json
AWS SSO を使ってゲストアカウントにログインします。

```sh
aws sso login --profile ct-guest-sso
aws sso login --profile ct-guest
```

CDK 用バケットをブートストラップします(初回のみ)。
Expand Down Expand Up @@ -439,7 +409,7 @@ Standalone 版と同じ手順で Context を設定します。
（ログインしていない場合）AWS SSO を使ってゲストアカウントにログインします。

```sh
aws sso login --profile ct-guest-sso
aws sso login --profile ct-guest
```

ゲストアプリケーションをデプロイします。
Expand Down
Loading

0 comments on commit 121ea77

Please sign in to comment.