Package Exports

aws-organization-formation

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (aws-organization-formation) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

AWS Organization Formation

Makes managing AWS Organizations easy!

Organization Formation allows you to manage AWS Organization resources and accounts using CloudFormation syntax

AWS Organization Formation

Installation

> npm i aws-organization-formation

Getting started

the following command will initialize organization formation and create an organization template.

> org-formation init organization.yml [--profile my-aws-profile]

after changing the organization template use:

> org-formation update organization.yml [--profile my-aws-profile]

> org-formation create-change-set organization.yml [--profile my-aws-profile]

and

> org-formation execute-change-set changeSetName [--profile my-aws-profile]

Why is this important

Just like with resources within your AWS Account managing AWS Organization resources allows you to apply changes to these resources automatically, reducing manual work, inconsistencies and mistakes.

If you are considering to use an account vending machine (e.g. AWS Control Tower) to create and manage new accounts within your organization: Do realize that the account vending machine allows you to quickly create organization resources but only has limited facilities when it comes to updating and maintaining these resoruces.

Example Template

AWSTemplateFormatVersion: '2010-09-09-OC'

Organization:
  Root:
    Type: OC::ORG::MasterAccount
    Properties:
      AccountName: My Organization Root
      AccountId: '123123123123'
      Tags:
        budget-alarm-threshold: '2500'
        account-owner-email: my@email.com

  OrganizationRoot:
    Type: OC::ORG::OrganizationRoot
    Properties:
      ServiceControlPolicies:
        - !Ref RestrictUnusedRegionsSCP

  ProductionAccount:
    Type: OC::ORG::Account
    Properties:
      RootEmail: production@myorg.com
      AccountName: Production Account
      Tags:
        budget-alarm-threshold: '2500'
        account-owner-email: my@email.com

  DevelopmentAccount:
    Type: OC::ORG::Account
    Properties:
      RootEmail: development@myorg.com
      AccountName: Development Account
      Tags:
        budget-alarm-threshold: '2500'
        account-owner-email: my@email.com

  DevelopmentOU:
    Type: OC::ORG::OrganizationalUnit
    Properties:
      OrganizationalUnitName: development
      Accounts:
        - !Ref DevelopmentAccount

  ProductionOU:
    Type: OC::ORG::OrganizationalUnit
    Properties:
      OrganizationalUnitName: production
      Accounts:
        - !Ref ProductionAccount

  RestrictUnusedRegionsSCP:
    Type: OC::ORG::ServiceControlPolicy
    Properties:
      PolicyName: RestrictUnusedRegions
      Description: Restrict Unused regions
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Sid: DenyUnsupportedRegions
            Effect: Deny
            NotAction:
              - 'cloudfront:*'
              - 'iam:*'
              - 'route53:*'
              - 'support:*'
            Resource: '*'
            Condition:
              StringNotEquals:
                'aws:RequestedRegion':
                  - eu-west-1
                  - us-east-1
                  - eu-central-1

List of Resource Types

Organization Formation supports the following AWS Organization resources:

MasterAccount

MasterAccount is the AWS Account that functions as the master account within your organization.

Type OC::ORG::MasterAccount

Properties

Property	Value	Remarks
AccountName	Name of the master account	This property is required. Changing the name of the AWS MasterAccount resource is not possible, this requires the root account to log in to the master account and change this manually. However, it is possible to change the AccountName of the MasterAccount in the template and this change will be reflected when doing a !GetAtt on the resource from within a template.
AccountId	AccountId of the master account	This property is required. Changing the AccountId of the master account is not supported.
RootEmail	RootEmail of the master account	This property is optional. Changing the RootEmail of the MasterAccount AWS resource is not possible, this requires the root account to log in to the master account and change this manually. However, it is possible to change the RootEmail of the MasterAccount in the template and this change will be reflected when doing a !GetAtt on the resource from within a template.
ServiceControlPolicies	Reference or list of References	This property is optional. Reference or list of References to ServiceControlPolicy resources that must be enforced on the MasterAccount
PasswordPolicy	Reference	This property is optional. Reference to the PasswordPolicy resource that must be enforced on the MasterAccount.
Alias	IAM alias	This property is optional. The IAM Alias associated with the account. Organization Formation supports a maximum of 1 IAM alias per account
Tags	Dictionary	This property is optional. Dictionary that contains the tags on the MasterAccount resource

Example

    Type: OC::ORG::MasterAccount
    Properties:
      Alias: org-formation-master
      AccountName: My Organization Formation Master Account
      AccountId: '123456789012'
      ServiceControlPolicies: !Ref ServiceControlPolicy
      PasswordPolicy: !Ref PasswordPolicy
      Tags:
        tag1: Value of Tag
        tag2: Value of Tag 2

!Ref Returns the AccountId of the MasterAccount resource.

!GetAtt <logicalId>.AccountName returns the AccountName of the MasterAccount resource.

!GetAtt <logicalId>.Alias returns the IAM alias of the MasterAccount resource.

!GetAtt <logicalId>.AccountId returns the AccountId of the MasterAccount resource.

!GetAtt <logicalId>.RootEmail returns the RootEmail of the MasterAccount resource.

!GetAtt <logicalId>.Tags.<Key> returns the value of tag <Key> for the MasterAccount resource.

Account

Account is an AWS Account within your organization.

Type OC::ORG::Account

Properties

Property	Value	Remarks
AccountName	Name of the account	This property is required. Changing the name of the AWS Account resource is not possible, this requires the root account to log in to the account and change this manually. However, it is possible to change the AccountName of the Account in the template and this change will be reflected when doing a !GetAtt on the resource from within a template.
AccountId	AccountId of account	This property is optional. Changing the AccountId of the account is not supported
RootEmail	RootEmail of the account	This property is optional (only if AccountId is specified) Changing the RootEmail of the Account AWS resource is not possible, this requires the root account to log in to the master account and change this manually. However, it is possible to change the RootEmail of the MasterAccount in the template and this change will be reflected when doing a !GetAtt on the resource from within a template.
ServiceControlPolicies	Reference or list of References	This property is optional. Reference or list of References to ServiceControlPolicy resources that must be enforced on the Account.
PasswordPolicy	Reference	This property is optional. Reference to the PasswordPolicy resource that must be enforced on the Account.
Alias	IAM alias	This property is optional. The IAM Alias associated with the account. Organization Formation supports a maximum of 1 IAM alias per account
Tags	Dictionary	This property is optional. Dictionary that contains the tags on the Account resource

Note When creating an account the RootEmail and AccountName are used to create the Account resource in AWS. The AccountId property can later be added as a means of ‘documentation’ but this is not required.

!Ref Returns the AccountId of the Account resource.

!GetAtt <logicalId>.AccountName returns the AccountName of the Account resource.

!GetAtt <logicalId>.Alias returns the IAM alias of the Account resource.

!GetAtt <logicalId>.AccountId returns the AccountId of the Account resource.

!GetAtt <logicalId>.RootEmail returns the RootEmail of the Account resource.

!GetAtt <logicalId>.Tags.<Key> returns the value of tag <Key> for the Account resource.

Example

  MyAccount1:
    Type: OC::ORG::Account
    Properties:
      RootEmail: my-aws-account-1@org-formation.com
      Alias: org-formation-account-1
      AccountName: Org Formation Sample Account 1
      AccountId: '123456789012'
      ServiceControlPolicies: !Ref ServiceControlPolicy
      PasswordPolicy: !Ref PasswordPolicy
      Tags:
        tag1: Value of Tag
        tag2: Value of Tag 2

OrganizationRoot

OrganizationRoot is the AWS Root Resource that functions like a top-level Organizational Unit within your Organization.

Type OC::ORG::OrganizationRoot

Properties

Property	Value	Remarks
ServiceControlPolicies	Reference or list of References	This property is optional. Reference or list of References to ServiceControlPolicy resources that must be enforced on all accounts (including master account) within the AWS Organization.

Note Any account (or master account) within an AWS organization that is not part of an Organizational Unit will be a member of the Organizational Root.

!Ref Returns the physical id of the OrganizationRoot resource.

Example

  OrganizationRoot:
    Type: OC::ORG::OrganizationRoot
    Properties:
      ServiceControlPolicies:
        - !Ref DenyChangeOfOrgRoleSCP
        - !Ref RestrictUnusedRegionsSCP

OrganizationalUnit

OrganizationalUnit is an AWS Organizational Unit within your organization and can be used to group accounts and apply policies to the accounts within the organizational unit.

Type OC::ORG::OrganizationalUnit

Properties

Property	Value	Remarks
OrganizationalUnitName	Name of the organizational unit	This property is required.
Accounts	Reference or list of References	This property is optional. Reference or list of References to Account resources that need to be part of the Organizational Unit.
ServiceControlPolicies	Reference or list of References	This property is optional. Reference or list of References to ServiceControlPolicy resources that must be enforced on all accounts (including master account) within the AWS Organization.

Note It is currently not supported to nest organizational units (have an OU as the parent of another OU). It is also not possible to add a MasterAccount resource to an OU.

!Ref Returns the physical id of the OrganizationalUnit resource.

Example

  DevelopmentOU:
    Type: OC::ORG::OrganizationalUnit
    Properties:
      OrganizationalUnitName: development
      ServiceControlPolicies:
        - !Ref DenyChangeOfOrgRoleSCP
      Accounts:
        - !Ref DevelopmentAccount1
        - !Ref DevelopmentAccount2

ServiceControlPolicy

ServiceControlPolicy is an AWS Service Control Policy that can be used to manage permissions within the accounts contained in your organization.

Type OC::ORG::ServiceControlPolicy

Properties

Property	Value	Remarks
PolicyName	Name of the SCP	This property is required.
Description	Description of the SCP	This property is optional.
PolicyDocument	Policy Document	This property is optional.

!Ref Returns the physical id of the ServiceControlPolicy resource.

Example

  RestrictUnusedRegionsSCP:
    Type: OC::ORG::ServiceControlPolicy
    Properties:
      PolicyName: RestrictUnusedRegions
      Description: Restrict Unused regions
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Sid: DenyUnsupportedRegions
            Effect: Deny
            NotAction:
              - 'cloudfront:*'
              - 'iam:*'
              - 'route53:*'
              - 'support:*'
            Resource: '*'
            Condition:
              StringNotEquals:
                'aws:RequestedRegion':
                  - eu-west-1
                  - us-east-1
                  - eu-central-1

PasswordPolicy

PasswordPolicy is an AWS IAM Password Policy that applies to all IAM Users within the account.

Type OC::ORG::PasswordPolicy

Properties

Property	Value	Remarks
MaxPasswordAge	number	This property is optional.
MinimumPasswordLength	number	This property is optional.
RequireLowercaseCharacters	boolean	This property is optional.
RequireNumbers	boolean	This property is optional.
RequireSymbols	boolean	This property is optional.
RequireUppercaseCharacters	boolean	This property is optional.
PasswordReusePrevention	number	This property is optional.
AllowUsersToChangePassword	boolean	This property is optional.

Example

  PasswordPolicy:
    Type: OC::ORG::PasswordPolicy
    Properties:
      MaxPasswordAge: 30
      MinimumPasswordLength: 12
      RequireLowercaseCharacters: true
      RequireNumbers: true
      RequireSymbols: true
      RequireUppercaseCharacters: true
      PasswordReusePrevention: 5
      AllowUsersToChangePassword: true

Managing resources across accounts

CloudFormation is the infrastructure as code solution native to AWS. It works great when managing resources within a single organization but doesnt contain syntax to manage resources across multiple accounts.

examples:

In CloudFormation it is not possible to specify a !Ref to another resource in another account or region.
In CloudFormation it is not possible to reference organization resource attributes
In CloudFormation it is possible to deploy stacks to multiple accounts (using StackSets) but only a subset of Cloudformation features can be used.

The constraints above can be difficult when managing a baseline of resources across different accounts in an AWS Organization:

Relationships between resources in different accounts/regions are important.
Variability in resource configuration needs to be managed centranlly and relative to the account resource

Organization Formation allows you to define any CloudFormation resource and annotate this with additional attributes that contain information about how these should be bound to the accounts within your organization.

example: In this example a IAM Group will be created in the SharedUsersAccount and a IAM Role will be created in all accounts. The IAM Role however can only be assume from the SharedUserAccount and the Group can only assume this specific Role.

AWSTemplateFormatVersion: 2010-09-09-OC

# include organization template.
Organization: !Include ./organization.yml

# default region (can be list)
OrganizationBindingRegion: eu-central-1

Resources:

  # this resource will only be created in the SharedUsersAccount
  DeveloperGroup:
    OrganizationBinding:
      Account: !Ref SharedUsersAccount
    Type: AWS::IAM::Group
    Properties:
      GroupName: DevelopersGroup
      Policies:
        - PolicyName: assume-roles
          PolicyDocument:
            Version: 2012-10-17
            Statement:
              - Effect: Allow
                Action: sts:AssumeRole
                Resource: arn:aws:iam::*:role/DeveloperRole

  # this resource will only be created in all accounts (except the organizational master)
  DeveloperRole:
    OrganizationBinding:
      Account: '*'
    Type: AWS::IAM::Role
    Properties:
      ManagedPolicyArns:
      - arn:aws:iam::aws:policy/PowerUserAccess
      RoleName: DeveloperRole
      AssumeRolePolicyDocument:
       Version: 2012-10-17
       Statement:
         - Effect: Allow
           Action: sts:AssumeRole
           Principal:
            AWS: !Ref SharedUsersAccount # role can only be assumed from SharedUsersAccount