# Connect your AWS organization

Your Shonin org uses the accounts of your AWS organization through the Shonin installation, which runs in your management account. You deploy it once, with one click, and connect it with a code.

## Before you start

- An administrator of your Shonin org, to start from the dashboard and enter the code.
- An administrator of your AWS management account, to deploy the stack. It can be the same person.

## Steps

1. In the dashboard, panel **AWS organizations**, choose **Add AWS organization**.
2. Sign in to your AWS management account, then choose **Deploy to AWS**: the AWS console opens on **Quick create stack**, with the template of the installation.
3. At the bottom of the page, select **I acknowledge that AWS CloudFormation might create IAM resources with custom names.** and choose **Create stack**. This takes a few minutes.
4. When the status of the stack `shonin-installation` is **CREATE_COMPLETE**, open its **Outputs** tab and click the link next to **ConnectUrl**. The page shows a connection code, and lets you set up your authenticator app: that page comes from your AWS account, so the app is set up there.
5. In Shonin, enter the code (and a code from the app, if you set it up), check the AWS organization Shonin shows you, and confirm.

The panel **AWS organizations** then lists the accounts you manage. Accounts added to your AWS organization later appear by themselves; to see one at once, choose **Refresh accounts**.

An AWS organization is connected to one Shonin org only, and the link cannot be changed later.

## Another AWS organization

A Shonin org can connect more than one AWS organization, each with its own installation in its management account. Only a primary admin connects another one.

1. In the dashboard, panel **AWS organizations**, choose **Add another AWS organization**.
2. Deploy the installation in the management account of that AWS organization, and get its connection code, as in steps 2 to 4 above. Skip the authenticator app on the connect page: you keep the one you have.
3. In Shonin, enter the code and choose **Continue**. Shonin shows the AWS organization, and which installation checks the second factor.
4. Enter a code from your authenticator app, or a backup code, and choose **Connect**.

Every primary admin gets an email. The panel lists each AWS organization with its accounts; **Refresh accounts** and automatic updates apply to all of them.

The installation of each AWS organization signs the access to its own accounts. The second factor is checked by one of them, the first you connected, and the others accept what it checked: you keep one authenticator app. To check it in another one, see [Second factor](second-factor.md#more-aws-organizations).

## The template

The template has one parameter, `AutomaticUpdates`, with default `yes`: see [Automatic updates](automatic-updates.md). Everything else Shonin learns when you enter the code.

The stack creates, in your management account:

- a container on Amazon ECS (AWS Fargate), with no inbound network access: it reads its requests from a queue in Shonin's account and answers on another one;
- a KMS key that signs the tokens AWS accepts, usable only by the container;
- a private S3 bucket for its state (second factor included), encrypted with a KMS key of the installation;
- the public discovery document and keys of the token issuer, on S3 and CloudFront;
- the StackSet `shonin-member-bootstrap`, which creates the role `ShoninStackSetExecutionRole` in the accounts of your AWS organization, also in accounts you add later.

When you assign a permission set, the installation creates its role in that account. See [Security](security.md).

## Without an AWS organization

A Shonin org without an AWS organization can still use accounts that another Shonin org delegates to it: see [Share accounts with another company](share-accounts.md).