Welcome to the Software Development Life Cycle (SDLC) Orgnaization CDK app

As described in root README, this CDK app strive to give you a clean and easy to use set of environments (AWS Accounts) to develop and operate sofware on AWS following best practices.

MUST READ

This first CDK app is deploying several AWS accounts which are resources with specific contraints in regards to deletion (Official doc, such as 90 days wait period). Therefore, be aware that rolling back the creation of those resources is not supported.
Since everything is code in a repository, access and permission of to this repository needs to be carefully managed.

Step #	Feature	Description
0	Under the hood	Details about what we are doing
1	Configure your local credentials	`aws configure --profile main-admin`
2	Fork and init the repo	Get the code
3	Deploy the pipeline	Deploy your organization through a CI/CD pipeline
4	Setup your SSO domain	Prepare you user permissions and groups
5	Setup your dev environment	Prepare your local environment to be ready to develop
6	Start coding	Jump to next section about developing and deploying your first web site

Under the hood

This CDK app will instanciate the following resources:

An AWS Organizations
Multiple AWS Accounts under different Organizational Unit
A central AWS CloudTrail for organizations
Few basics security guard rails using AWS Config
A DNS Zone (if a domain is provided) using Route53 HostedZone

Those are exposed through the AwsOrganizationsStack.

The deployment of this organization is automated through a CI/CD pipeline that is going to be deployed in your main account through the deployment of the AWSBootstrapKit-LandingZone-PipelineStack. Which enable to track any update made to it through git source control.

DNS hierarchy:

Deployments

Prerequisites

A GitHub account
npm and awscli installed
A valid email (can be your root account one)
- without "+" in it
- provided by a provider supporting subaddressing which means supporting '+' email extension (Most providers such as gmail/google, outlook etc. support it. If you're not sure check this page "Address modifiers" column or send an email to yourself adding a plus extension such as myname+test@myemaildomain.com . if you receive it, you're good).
An AWS account with an IAM user with Administrator permission

Configure your local credentials

Click to go through this step

To authenticate requests made using the CLI, we need to give your IAM user credentials (If you don't have one follow this instruction with Programmatic access Access type selected and AdministratorAccess policy) and the region you want to use to the Command line:

aws configure --profile main-admin
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: eu-west-1
Default output format [None]: json

Here we use the --profile parameter with main-admin in order to, in the future be able to swtich between accounts.

You can now test our set up:

aws --profile=main-admin  sts get-caller-identity

{
    "UserId": "A1B2C3D4E5F6G7EXAMPLE",
    "Account": "111122223333",
    "Arn": "arn:aws:iam::111122223333:user/Administrator"
}

This command show you basically what your current crendentials are attached to :

Account tell you which Account Id you are talking to
Arn tell you which Role you are using

To learn more, check the official doc.

Fork and init the repo

Click to go through this step

Fork the repository on your GitHub account by clicking here.

Clone the repository locally:

git clone https://github.com/<YOUR_GITHUB_ALIAS>/aws-bootstrap-kit-examples

Link your GitHub repository to AWS by
1. Pushing your github personal secret token (follow this instruction if you don't have one with admin:repo_hook full control and repo full control) in AWS Secrets Manager, a service that stores your secret securely
```
aws --profile main-admin secretsmanager create-secret --name GITHUB_TOKEN --secret-string <YOUR_GITHUB_PERSONAL_ACCESS_TOKEN>
```
2. Set in source/1-SDLC-organization/cdk.json the following variables:
  - email corresponding to the administrator email that will be used to create additional AWS account (without "+" character)
    
    You will receive an email with a verification link to validate it
  - github_alias coresponding to your github username (your_alias in https://github.com/your_alias/your_repo)
  - github_repo_name corresponding to the name when you created the repository (your_repo in this example)
  - gihub_repo_branch corresponding to the main branch of your repo. (should be called main)
  - pipeline_deployable_regions corresponding to the lists of AWS regions you plan to deploy your future applications to.
  - (optional) domain_name a DNS domain name to use to expose your services publicly (it needs to be already registered in a registrar such Amazon route53)
  it should look like: cd <YOUR REPO> cat 1-SDLC-organization/cdk.json { "app": "npx ts-node bin/sdlc-organization.ts", "context": { "@aws-cdk/core:enableStackNameDuplicates": "true", "aws-cdk:enableDiffNoFail": "true", "@aws-cdk/core:stackRelativeExports": "true", "@aws-cdk/core:newStyleStackSynthesis": true, "github_alias": "your_alias", "github_repo_name": "aws-bootstrap-kit-examples", "github_repo_branch": "main", "email": "admin@yourdomain.com", "force_email_verification": true, "pipeline_deployable_regions": [ eu-west-1, eu-west-2 ], "domain_name": "yourdomain.com" } }
3. Push new changes to your repo
```
git add source/1-SDLC-organization/cdk.json
git commit -m "set required bootstrap variables"
git push
```

Install dependencies and deploy the pipeline

Click to go through this step

Go to the SDLC Organization folder
```
cd source/1-SDLC-Organization
```
Install dependencies
```
npm install
```
Bootstrap AWS account
```
npm run bootstrap
```
build and deploy package
```
npm run build
npm run deploy
```
Check the status of the deployed CI/CD pipeline in AWS CodePipeline Console (click here to learn more about AWS Code Pipeline)
When all green, unlock deployment to prod by approving the change to be deployed by clicking the "review" button in prod section of the pipeline.

PS: You can inspect what is going to be deployed by clicking "Details" link of "orgStack.Prepare" action.
A Validation Email is sent to your inbox, please click on the confirmation link for the deployment to complete. THIS WILL BLOCK YOUR DEPLOYMENT, IF YOU DO NOT CLICK ON VERIFICATION LINK RECEIVED IN YOUR EMAIL

This was step was enabled by the force_email_verification boolean set in your cdk.json. to ensure that the email provided satisfies the rules we previously mentioned (the email doesn't contain + and the email providor supports subaddressing)
When all green, you should be able to
1. check your organization structure in AWS Organizations console
2. Get into any of those sub accounts by getting the Account ID from AWS Organizations console and using the switch role button on top left drop down of the screen and the OrganizationAccountAccessRole Role name.
Check the doc for more details.

Your Operator Environment is ready! Now let's open it to the team!

Going further

If you added domain_name in your config file (cdk.json) earlier, a last step is need to delegate your registered domain to the new hosted zone created by the previous delployment. Otherwise you can skip this section.

Finalize DNS setup

Click to go through this step

First let's get the NS servers registered in the new hosted zone by
1. Got to AWS Route53 Hosted Zone page
2. click on the hosted zone with 5 Record count and with the Domain name coresponding to your root domain name specified in domain_name earlier
3. Copy the Value of the NS Type Record row of your domain name
Go to your registrar configuration console and replace NS servers by the one copied earlier.

Your Done! Now you can manage your domain through AWS Route53

Enable SSO

In order to facilitate the management of permissions on the access to this different accounts we suggest to setup an SSO portal following the steps described bellow. That's going to give you the capability to centrally manage and access your different AWS account with a single identity (login and password) or even delegate this to a third party provider such as Google Workspace (GSuite).

Staying with IAM users and groups would means not getting a central portal with a single identity and would force you to remember the different account ID and role to login into:

Whatch this quick presentation video to learn more:

Setup your SSO domain

Click to go through this step

Sorry we can't automate those step yet 😢

Go to the AWS SSO Home page and Click Enable AWS SSO

Create permission sets

We want to be able to manage two groups of users:

the Administrators who will have access to all accounts with AdministratorAccess permissions
the Developers who will have access only to the Dev account with DeveloperAccess permissions and ViewOnlyAccess permissions to the Staging and Prod accounts

Through 5 set of permissions:

AdministratorAccess grants administrator access to an AWS account. A user with this permission set is able to create, update or delete any resources in an AWS account including IAM users, roles and groups. It relies on the AdministratorAccess AWS managed job function policy.
DeveloperAccess allows developers to create, update or delete AWS resources from an account excluding users and groups. A developer with this permission set is also able to create, delete and update roles as well as creating, updating, deleting and attaching role policies to a resource. It allows a developer to deploy a CDK app into and account directly with the cdk deploy command. It relies on the PowerUserAccess AWS managed job function policy plus a set of IAM actions.
DevOpsAccess allows DevOps engineers to deploy and manage CI/CD pipelines through CDK. It relies on 5 AWS managed policies: AWSCloudFormationFullAcces, AWSCodeBuildAdminAccess, AWSCodePipelineFullAccess, AmazonS3FullAccess, AmazonEC2ContainerRegistryFullAccess, SecretsManagerReadWrite. It relies on a set of IAM, KMS and Organizations actions.
ApproverAccess allows users to view and approve manual changes for all pipelines. It relies on the AWSCodePipelineApproverAccess AWS managed policy.
ViewOnlyAccess allows users to view resources and basic metadata across all AWS services. It relies on the ViewOnlyAccess AWS managed policy.

AdministratorAccess

To set up these accesses, we first need to create a permission set which correspond to the set of permissions that an Administrator will have when going to a specific account:

Click on the AWS Accounts section
Go to Permission sets tab and click Create permission set
Select Create a custom permission set and click Next: Details
Type in the info
1. Name: AdministratorAccess
2. Session duaration: X hours
3. Check the Attach AWS managed policies and Create a custom permissions policy boxes.
4. Select the AdministratorAccess managed policy
5. Enter the following custom permissions policy:
{}
click Next: Tags
Skip tags by click Next: Review
Click Create to finalize the creation of the permissions set

DeveloperAccess

Repeat previous steps with

Name: DeveloperAccess
Manage policies:
- PowerUserAccess

Custom policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:GetRole",
                "iam:PassRole",
                "iam:UpdateRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

DevOpsAccess

Repeat previous steps with

Name: DevOpsAccess
Manage policies:
- AWSCloudFormationFullAccess
- AWSCodeBuildAdminAccess
- AWSCodePipelineFullAccess
- AmazonS3FullAccess
- *AmazonEC2ContainerRegistryFullAccess
- SecretsManagerReadWrite

Custom policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:GetRole",
                "iam:PassRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:PutRolePolicy",
                "iam:GetRolePolicy",
                "iam:DeleteRolepolicy",
                "kms:CreateKey",
                "kms:PutKeyPolicy",
                "kms:DescribeKey",
                "kms:CreateAlias",
                "kms:DeleteAlias",
                "kms:ScheduleKeyDeletion",
                "organizations:ListAccounts"
            ],
            "Effect": "Allow",
            "Resource": "*"
        },
        {
            "Action": [
                "sts:AssumeRole"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:iam::*:role/cdk*"
        }
    ]
}

ApproverAccess

Repeat previous steps with
1. Name: ApproverAccess
2. Manage policies:
  - AWSCodePipelineApproverAccess
3. Custom policy:
```
{}
```

ViewOnlyAccess

Repeat previous steps with
1. Name: ViewOnlyAccess
2. Manage policies:
  - ViewOnlyAccess
3. Custom policy:
```
{}
```

You must end with the following permission sets:

ViewOnlyAccess
ApproverAccess
DevOpsAccess
DeveloperAccess
AdministratorAccess

Create your groups

Now we are going to create the Administrators, Developers, DevOpsEngineers and Approvers groups, we basically will follow the steps listed in the official documentation:

Click on the Groups Tab
Click Create group
Type Adminstrators as group name and click Create
Repeat steps 1 to 3 for Developers, DevOpsEngineers, Approvers

Link groups to accounts and permission sets

Now we are going to assign the Administrators group to all the accounts with the the AdministratorAccess permission set. It will result to giving Administrator access to users in the Administrators group to all your accounts:

Come back to AWS Accounts section
Select all your accounts and click Assign users
Go to Groups tab, select Admninistrators group and click Next: Permissions set
Select AdminstriatorAccess permissions set and click Finish
It will take a few seconds to configure all your accounts
When all is complete, click on Proceed to AWS accounts
Repeat 1 to 6 with Developers, DevOpsEngineers and Approvers groups with the following associations:

Groups	PermissionSets	Accounts
Developers	DeveloperAccess	Dev
Developers	ReadOnlyAccess	Staging, Prod
DevOpsEngineers	DevOpsAccess	CICD
Approvers	ApproverAccess	CICD

Now let's create your Administrator user !

Create your administrator SSO user

Now we are going to create an Administrator user, we basically will follow the steps listed in the official documentation:

Click on the Users section
Click Add user
Fill in the form with your personal data and click Next Groups:
- username will be used for future login
- Email address will be used for enrolling so need to be a valid email
Select the Administrators group created previously and click Add user
Check your email and Accept invitation
You should be redirected to a page to set your password then click Update user
Well done your account has been successfully activated! Click Continue
You have now access to your SSO app list. Click on AWS Account card to expand the list of accounts
Click on your main account to expand the list of your access to this account
Click on Management console to access to the console of your main account
Your are now connected with your new SSO Administrator user

Let's assign the Developers group to Dev, Staging and Prod accounts with this new SSO Administrator user

Customize your SSO endpoint

From now on, you or any of your developers won't have to login anymore directly to AWS console but directly through AWS SSO portal. In the previous step you might have noticed that your SSO console is accessible through a unique URL such as https://d-123456789a.awsapps.com/start which is not that easy to remember, let's customize it to match your company domain:

Search for SSO on the console home page and go to the service
At the bottom of the page, click the Customize link located in User portal section
Type your domain name and click Save

Tada !! You can now login to AWS Console through your SSO portal using your customized url !

Setup your dev environment

Click to go through this step

Create a developer SSO user

(This section is optional but will be one to use each time you want to onboard a new dev in your team)

Now we are going to create a Developer user with enough rate to develop and publish an app to the different environemnt, we basically will follow the steps listed in the official documentation:

Click on the Users section
Click Add user
Fill in the form with your personal data and click Next Groups:
- username will be used for future login
- Email address will be used for enrolling so need to be a valid email
Select the Developers groups created previously and click Add user
Check your email and Accept invitation
You should be redirected to a page to set your password then click Update user
Well done your account has been successfully activated! Click Continue
You have now access to your SSO app list with your Developer user

AWS CLI V2

TL;DR

Just run

 aws configure sso --profile dev

and choose

The previously customized URL as SSO Start URL with the /start/ at the end
your dev account in the list.

And login with

aws sso login --profile dev

In order to interact with your different environment through the awscli or any AWS SDKs locally, you will need to get your credentials.

To authenticate requests made using the CLI, we need to give the credentials generated by AWS SSO and link them to what we call profile. So for each environment you want to have access to through AWS CLI v2 and CDK you will have to configure a specific profile for it running the command below.

Here we setup your first profile that will be used to replace your IAM user administrator one (--profile dev):

aws configure sso --profile dev
SSO start URL [None]: https://yourdomain.awsapps.com/start
SSO Region [None]: eu-west-1
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

https://device.sso.eu-west-1.amazonaws.com/

Then enter the code:

ABCD-ABCD
There are 5 AWS accounts available to you.
Using the account ID 111122223333
The only role available to you is: DeveloperAccess
Using the role name "DeveloperAccess"
CLI default client Region [None]: eu-west-1
CLI default output format [None]: json

To use this profile, specify the profile name using --profile, as shown:

aws s3 ls --profile dev

Here we use the --profile parameter with dev in order to, in the future be able to swtich between accounts.

You can now test our set up:

aws --profile=dev  sts get-caller-identity
 
{
        "UserId": "A1B2C3D4E5F6G7EXAMPLE:admin",
    "Account": "111122223333",
       "Arn": "arn:aws:sts::111122223333:assumed-role/AWSReservedSSO_AdministratorAccess_1234a12345a12aa1/admin"
}

This command show you basically what your current crendentials are attached to :

Account tell you which Account Id you are talking to
Arn tell you which Role you are using

To learn more, check the official doc.

This procedure should be repeted for all the AWS Account you want to interact with.

Then, when token expire, you can refresh it by running

aws sso login --profile dev

Now you can interact with your different AWS Accounts using AWS CLI

CDK and SSO

CDK and AWS SSO are not yet friends (see github issue 5455). So since in the future we will have to deploy infrastructure as code apps into multiple environment, we will need to make it work.

There is several workaround and here is one using a quick utility written in nodejs called "cdk-sso-sync":

npm install -g cdk-sso-sync

Then simply run

aws sso login --profile dev
cdk-sso-sync dev

This will simply extract the credentials you got from the aws sso login command and sync them with the CDK credentials source (~/.aws/credentials).

Now you can deploy CDK apps in your different AWS Accounts using CDK CLI

Leverage AWS IDE Toolkits

In order to improve your productivity, do not hesitate to leverage AWS IDE Toolkits by checking the official docmumentation.

At the time of writting, we support the following IDEs:

AWS Cloud9
Eclipse
IntelliJ
PyCharm
Visual Studio
Visual Studio Code
Azure DevOps
Rider

You are now Ready to start coding !

Next step

Click to go through this step

Start coding and deploy your first website by jumping to the landing page app example.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Welcome to the Software Development Life Cycle (SDLC) Orgnaization CDK app

MUST READ

Under the hood

Deployments

Prerequisites

Configure your local credentials

Fork and init the repo

Install dependencies and deploy the pipeline

Going further

Finalize DNS setup

Enable SSO

Setup your SSO domain

Create permission sets

AdministratorAccess

DeveloperAccess

DevOpsAccess

ApproverAccess

ViewOnlyAccess

Create your groups

Link groups to accounts and permission sets

Create your administrator SSO user

Customize your SSO endpoint

Setup your dev environment

Create a developer SSO user

AWS CLI V2

CDK and SSO

Leverage AWS IDE Toolkits

Next step

Files

README.md

Latest commit

History

README.md

File metadata and controls

Welcome to the Software Development Life Cycle (SDLC) Orgnaization CDK app

MUST READ

Under the hood

Deployments

Prerequisites

Configure your local credentials

Fork and init the repo

Install dependencies and deploy the pipeline

Going further

Finalize DNS setup

Enable SSO

Setup your SSO domain

Create permission sets

AdministratorAccess

DeveloperAccess

DevOpsAccess

ApproverAccess

ViewOnlyAccess

Create your groups

Link groups to accounts and permission sets

Create your administrator SSO user

Customize your SSO endpoint

Setup your dev environment

Create a developer SSO user

AWS CLI V2

CDK and SSO

Leverage AWS IDE Toolkits

Next step