Onboard your new AWS Organization to Stax

Learn how to onboard your new AWS Organization Account to Stax

Article Tags
On This Page
What is Stax OnboardingStages of OnboardingPreparing Your AWS OrganizationInformation You Need to Provide UsWhat NextFAQ

Hello and welcome to your guide to onboarding your new AWS Organization to the Stax Platform!

This guide will outline the steps and requirements you must complete before Stax can begin the onboarding process.

Please follow each section and its steps carefully to ensure a trouble-free implementation of your AWS Organization into the Stax Platform.


What is Stax Onboarding

In this scenario you may have a brand new AWS Account with the intention of enabling it as your AWS Organization master account with no existing member, or application, accounts. What Stax Onboarding means in this scenario is;

  • We ask you to deploy a role that provides our Control Plane access to your AWS Organization master account

  • Once you have done this and let us know, we will then attempt to Provision your AWS Organization

  • This essentially means;

    1. We test and confirm we have access to your AWS Organization account
    2. We enable required AWS Organization features if they have not been enabled
    3. Once the three above tasks are completed, the Stax team will create your Stax customer utilizing your AWS Organization master account

Stages of Onboarding

There are two stages of the onboarding process for this scenario

1. Provision

  • We first attempt to provision and prepare your AWS Organization for Stax Onboarding
  • Once we are confident we have everything we need to create your customer on the Stax Platform we will being this process

2. Create

  • During the create stage, we will be creating a Stax customer for your organization which will essentially fully integrate your AWS Organization into the Stax Platform
  • Once the create stage has been completed, you will be provided access to your new Stax customer

--

Preparing Your AWS Organization

If you have already enabled AWS Organizations the key part of the process is fundamentally completed, however your AWS Organization may be in a state that isn't necessarily compatible with how Stax needs to utilize it.

If you have yet to enable AWS Organizations, Stax will perform this for you.

Granting Stax Access

The first piece of preparation is to provide the Stax Control Plane with access to your AWS Organization account. This process is fairly simple however there are some specifics you must be aware of when following these steps, so please read carefully.

Deploying the stax-Provisioning role

Note: Please see the FAQ section below if you have more specific questions about this step

Stax have a CloudFormation template which contains an IAM Role named stax-Provisioning.

Stax require this role to be created in your AWS Organization account so we can access your AWS Organization Account and any subsequent AWS Organization application accounts to perform the work required to onboard your AWS Organization and AWS Organization application accounts to Stax.

This role has a custom policy attached, here is the inline policy document (you may also cross check this with the CloudFormation template we will provide later).

Policies:
- PolicyName: "stax-access"
    PolicyDocument:
    Version: "2012-10-17"
    Statement:
    - Effect: "Allow"
        Action:
        - "iam:*"
        - "cloudformation:*"
        - "organizations:*"
        - "sts:AssumeRole"
        Resource: "*"

These permissions are required to perform the minimum amount of actions the Stax platform needs to take to get your AWS Organization onboarded. Changing these permissions is not an option.

Now that you're aware of what permissions this role is going to have, we need to have you deploy the CloudFormation stack to your AWS Organization. Please follow these steps in order to avoid running into issues.

Deployment steps

  1. Login to your AWS Organization account using a role/user which has adequate permissions to deploy a CloudFormation stack via the web console.

  2. You then need to click the link relevant to the Stax installation you will be onboarding your AWS Organization to (see table below).

    • Note: A Stax representative should have advised you which installation you should be onboarded to, if not it is generally the same geographical region you predominantly operate out of.
    • If you are unsure, please contact your Stax representative to confirm which Stax Installation you are being onboarded to.
  3. Upon clicking the link you will be redirected to a Quick create stack page within the AWS Console.

    • Note: Please do not change any of the parameter settings on this page. Adjusting the parameters will cause the onboarding process to fail.
  4. Scroll to the bottom of this page and click the checkbox under the Capabilities heading (see image below).

  5. Once this has been completed, click the Create Stack button.

  6. You will be redirected to the CloudFormation Stacks page.

  7. You will see the stack has begun creation, monitor this page to ensure the creation is successful (see image below).

  8. Once this process has finished, you have successfully completed this part of the preparation.

stax-Provisioning CloudFormation stack

Stax Installation RegionCloudFormation stack
stax-au1Click Here
stax-us1Click Here
stax-eu1Click Here

Important note regarding OrganizationAccountAccessRole and AWS application accounts

By default, when creating new AWS application accounts via AWS Organizations, an IAM role named OrganizationAccountAccessRole is created by AWS in each application account when it is created.

  • This role is what the Stax Platform uses during the provisioning phase to ensure all your accounts are ready for use against the Stax Platform.
  • However, there are scenarios where you may have imported an AWS account into your existing AWS Organization, if this is the case, these imported accounts may not have the OrganizationAccountAccessRole. This is a problem for Stax as we need this role to be able to put your AWS Organization and your AWS application accounts in a useable state.
  • In the event you do not have the OrganizationAccountAccessRole in some application accounts or you've chosen to remove that role, you MUST also deploy the stax-Provisioning CloudFormation stack mentioned above in each account that does not have the OrganizationAccountAccessRole.
  • Performing this work before letting us know your AWS Organization is ready will ensure we can quickly get your AWS Organization integrated into the Stax Platform.
  • If at any stage of the provisioning process has detected AWS Access/Permission issues with one or more of your AWS application accounts, Stax will NOT be able to proceed and you will be provided a list of AWS application accounts that need to either have the OrganizationAccountAccessRole created with the correct permissions by you or you the customer will need to deploy the stax-Provisioning CloudFormation stack in each account that we have reported as having a problem.

Unfortunately, this is not something the Stax Platform can work around and is a fundamental requirement of getting you onto the Stax Platform

Billing access

Stax need to ensure IAM billing access is enabled within your AWS Organization to assist in retrieving cost and billing information.

How to enable IAM billing access

  1. Ensure you are still logged into the AWS Organization as the root user.
  2. In the AWS Console on the top navigation bar on the right hand side look for the account name (It is the first drop down available in the top navigation bar).
  3. Click on this and then click the My Account link.
  4. A new page will load, scroll towards the bottom of the page until you locate the IAM User and Role Access to Billing Information section.
  5. Click the Edit link next to this.
  6. Click on the checkbox marked as Activate IAM Access and click the Update button.
  7. Once this has finished, you have successfully completed this part of the preparation

IAM Billing

AWS Account Limit increase

By default, Stax will create a minimum of five AWS application accounts for usage when you want them. However AWS enforces strict AWS Account limits when you first create an account, so you will need to raise a request with AWS to increase the AWS Account limit.

Increasing your AWS Account limit

  1. Ensure you are logged into your AWS Organization account via the AWS Web Console

  2. On the top right navigation pane there is a drop down called Support

  3. Click this and then select Support Center

  4. On the Support Center page click the Create Case button

    • Part 1 - On the Create case page select the Service limit increase pane/checkbox
    • Part 1 - Under Case classification set the Limit type to Organizations
    • Support Ticket - Part 1
  5. Scroll down

    • Part 2 - Under the Requests section select Number of Accounts from the Limit drop down box
    • Part 2 - Set the New limit value to 50
    • Part 2 - Under Case description enter the following text line - `This master Organizations account will be used by a SaaS platform. The SaaS platform will be creating our AWS accounts and will need the limit increased to achieve this.
    • Support Ticket - Part 2
  6. Scroll to the bottom you do not need to change any other fields

  7. Click the submit button

  8. AWS will generally reply within the next 24 hours

    • Note: Sometimes AWS will refuse a limit increase of 50 accounts, at a minimum you should have the limit increased to at least 10, however 20 or higher is preferable.

Information You Need to Provide Us

This is where you can help us! To allow the onboarding process to move smoothly, we need some very basic information from you.

The new AWS Master Account Email address and AWS Account ID

  • AWS Master Account Email Address

The Stax platform team requires the email address you have used to sign up the New AWS Master account. Please pass this on to your Stax platform representative.

  • AWS Master Account AWS Account ID

The Stax platform team also require the AWS Master Account Id for the new AWS Master account, this is a 12-digit number than can be retrieved from the My Account page, please pass this information on to your Stax platform representative.

Desired Application Account Email Structure

The Stax platform provides a facility to allow you to determine the email account structure we will use for your AWS Organization application accounts. This is more of a naming convention option to allow you to more easily identify your AWS Organization application accounts.

This allows you to set a prefix, use a Stax variable and define your own domain name as the attached email address for your AWS Organization application accounts.

  • Example 1

CompanyName+${Stax::AccountId}@CompanyDomain.com

This allows you to prefix the start of the email address and include the AWS Account UUID and set your companies domain name

  • Example 2

${Stax::AccountId}@CompanyDomain.com

This is similar to the default Stax platform naming convention, however we attach your domain name to the email rather than a default Stax domain

Note: The ${Stax::AccountId} is a UUID that is generated for your AWS application account when it is created


What Next

Once you have completed all of the above steps and provided the relevant information Stax will attempt to go through the four stages listed above.


FAQ

Why do we need to grant Stax access to our AWS Accounts?

Fundamentally, Stax interacts at the AWS level with your accounts to perform numerous tasks that require access to your accounts.

We do our best to avoid the usage of the OrganizationAccountAccessRole where possible, and the majority of our interactions can be tracked against Stax named IAM roles in all of your accounts.

What changes do you make to our accounts?

During this provisioning phase it is minimal. We simply enable some billing features and deploy a number of buckets within your root account for said billing information.

Additionally we create an Organizational Unit called Unallocated this is used to place pooled AWS application accounts that we create for you ahead of time, so when you do chose to create an account via the Stax platform we have a pre-allocated AWS account ready for us to harden in a timely manner.

On top of the Unallocated Organizational Unit we create, we also create a Service Control Policy and attach it to this Organizational Unit, this policy simply restricts access to these AWS accounts and only allows usage of the OrganizationAccountAccessRole to interact within the account(s) when they are pending allocation.

Can I only create AWS account in Stax after implementation?

No. As you are the owner of the AWS Organization account you can still use any method you chose to create new AWS Accounts.

It is however recommended that you use the Stax Platform to create new AWS Accounts once your AWS Organization has been integrated with the platform.

We are having issues deploying the CloudFormation stack

Please contact your Stax representative for assistance if you are having difficulties with this process.

We have imported accounts and don't have the OrganizationAccountAccessRole

As per the highlighted section above, if you have an imported account without the OrganizationAccountAccessRole and you do not wish to create it, you must deploy the stax-Provisioning CloudFormation stack in these accounts before we can successfully provision your AWS Organization.

I have other questions

Please contact your Stax representative with your queries if this document does not cover it.