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
  • Getting started
  • Why managing your organization as code is important
  • Example Template
  • List of Resource Types
    • MasterAccount
    • Account
    • OrganizationRoot
    • OrganizationalUnit
    • ServiceControlPolicy
    • PasswordPolicy
  • Managing resources across accounts
    • OrganizationBinding: Where to create which resource
    • Creating cross account resource dependencies
    • Referencing the account the resource is created in
    • Foreach: Iterating over accounts when creating resources
  • Updating multiple templates at once

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]

or

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

and

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

Why managing your organization as code is 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

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

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

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

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

!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

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

OrganizationBinding: Where to create which resource

In Orgnization Formation every resource can have an OrganizationBinding attribute. This attribute specifies in which accounts the resource must be created. The OrganizationBinding atribute looks like:

Resources:
  Bucket:
    OrganizationBinding:
      Region: eu-west-1
      Account:
       - !Ref Account1
       - !Ref Account2
    Type: AWS::S3::Bucket

In the example above the resource Bucket will be created for Account1 and Account2 in the eu-west-1 region.

There is a lot of other ways to specify an account binding though:

Attributes can be combined and are additive (except for ExcludeAccount).

Creating cross account resource dependencies

If you have a resource that you need to refer to from within another resource (using !Ref or !GetAtt) Organization Formation helps you to do this across AWS accounts.

As every resource has its own OrganizationBinding and therefore will need to be added to a different set of accounts Organization Formation creates a template specific to every target account refered to from within the template.

If, within a template, you use !Ref ir !GetAtt to refer to another resource in another account Organization Formation will create an export in the template that exposes the resource and create a parameter in the template that uses the value. It will work exactly how you would expect it to in cloudformation.

example:

AWSTemplateFormatVersion: '2010-09-09-OC'

Organization: !Include ./organization.yml
OrganizationBindingRegion: eu-central-1

Resources:

  CloudTrailS3Bucket:
    OrganizationBinding:
      Account: !Ref ComplianceAccount
    DeletionPolicy: Retain
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub 'cloudtrail-${ComplianceAccount}'

  # omitted some resources like bucket policy

  CloudTrail:
    OrganizationBinding:
      Account: '*'
      IncludeMasterAccount: true
    Type: AWS::CloudTrail::Trail
    Properties:
      # this will, in any account, resolve to the name of CloudTrailS3Bucket in the ComplianceAccount.
      S3BucketName: !Ref CloudTrailS3Bucket
      IsLogging: false

note: The above will only work if resource CloudTrailS3Bucket only is bound to 1 account and region. If a resource is deployed to multiple accounts, you can alternatively use the syntax !Ref ComplianceAccount.Resources.CloudTrailS3Bucket or !GetAtt ComplianceAccount.Resources.CloudTrailS3Bucket.Arn.

Referencing the account the resource is created in

In CloudFormation it is possible to reference the accountId of the account the resource is created in using AWS::AccountId and the region using AWS::Region. As Organization Formation template are regular cloudformation this remains possible.

Organization Formation adds a way to reference the account resource of the account for which the resource is created using AWSAccount

example

  Budget:
    Type: AWS::Budgets::Budget
    OrganizationBinding:
      Account: '*'
    Properties:
      Budget:
        BudgetName: !Sub '${resourcePrefix}-budget-${AWSAccount.Alias}'
        BudgetLimit:
          Amount: !GetAtt AWSAccount.Tags.budget-alarm-threshold
          Unit: USD
        TimeUnit: MONTHLY
        BudgetType: COST

Foreach: Iterating over accounts when creating resources

If, in Organization Formation, you need to create a resource for each account in a specific selection you can do so with a Foreach attribute.

example

  Member:
    Type: AWS::GuardDuty::Member
    OrganizationBinding:
      IncludeMasterAccount: true
    Foreach:
      Account: '*'
    Properties:
      DetectorId: !Ref Detector
      Email: !GetAtt CurrentAccount.RootEmail
      MemberId: !Ref CurrentAccount
      Status: Invited
      DisableEmailNotification: true

In the example above a Member resource will be created in the Master for each account in the selector Account: '*'. The account that is iterated over can be accessed using CurrentAccount.

The Foreach attribute is has the same expressiveness as the OrganizationBinding but does not support Region.

Please consider the following template for some more context. It sets up GuardDuty for a complete organization using 3 resources!

AWSTemplateFormatVersion: '2010-09-09-OC'

Organization: !Include ./organization.yml
OrganizationBindingRegion: eu-central-1

Resources:
  Detector:
    Type: AWS::GuardDuty::Detector
    OrganizationBinding:
      Account: '*'
      IncludeMasterAccount: true
    Properties:
      Enable: 'true'
  Master:
    DependsOnAccount: !Ref MasterAccount
    Type: AWS::GuardDuty::Master
    OrganizationBinding:
      Account: '*'
    Properties:
      DetectorId: !Ref Detector
      MasterId: !Ref MasterAccount
  Member:
    Type: AWS::GuardDuty::Member
    OrganizationBinding:
      IncludeMasterAccount: true
    Foreach:
      Account: '*'
    Properties:
      DetectorId: !Ref Detector
      Email: !GetAtt CurrentAccount.RootEmail
      MemberId: !Ref CurrentAccount
      Status: Invited
      DisableEmailNotification: true

The template above specifies that:

• Every account, including the master account, gets a Detector resource.
• Ever account, except for the master account, gets a Master resource.
• The MasterAccount gets a Member resource for each account that is refered to from the Master resource in that account.

yes, the creation of Master resources to 'Members' and Member ressources to the Master account is confusing. This, unfortunately, is how Guardduty works in CloudFormation.

Updating multiple templates at once

You might well have multiple templates you would like to provision within your organization and manage centrally. Additionally might want to have a code repository set up with these templates and run them using a CI/CD solution.

A solution to update multiple Organization Formation templates at once is task files:

example:

OrganizationUpdate:
  Type: update-organization
  Template: ./organization.yml

Roles:
  Type: update-stacks
  Template: ./roles.yml
  StackName: roles

BudgetAlarms:
  Type: update-stacks
  Template: ./budget-alarms.yml
  StackName: budget-alarms

The tasks listed in the file above can be executed using:

> org-formation perform-tasks taskfile.yml [--profile my-aws-profile]

List of Task Types

update-organization

The update-organization task will update all the organization resources based on the template specified as Template.

update-stacks

The update-stacks task will provision all resources in all accounts specified in Template.

example

BudgetAlarms:
  Type: update-stacks
  Template: ./budget-alarms.yml
  StackName: budget-alarms
  TerminationProtection: true
  OrganizationBinding:
    AccountsWithTag: budget-alarm-threshold
  OrganizationBindingRegion: eu-central-1
  Parameters:
    resourcePrefix: my

CloudformationSetup:
  Type: update-stacks
  Template: ./cloudformation-setup.yml
  StackName: cloudformation-setup
  StackDescription: 'Cloudformation setup used by stacksets'
  OrganizationFile: ./organization.yml
  TerminationProtection: true
  OrganizationBindingRegion: eu-central-1
  OrganizationBinding:
    Account: '*'

include

The include include another taskfile with tasks to be executed.

example

Include:
  Type: include
  DependsOn: otherTask
  Path: ./build-tasks-include.yml
  MaxConcurrentTasks: 10
  FailedTaskTolerance: 10