org-formation-sso-import v0.0.2
org-formation-sso-import
An experimental™️ script to import AWS SSO groups, permission sets and assignments into a OrgFormation workspace.
!WARNING\ The experimental™️ nature of this project is to be taken very seriously. This is still a new project which has been tested only against a limited number of use cases and configuration. It might not work 100% with your specific configuration. Please use it with caution and report any issues you might find. Even better, consider opening a PR to improve it if you find any bug or a missing feature! 😇
The problem
If you have already bootstrapped your Landing Zone manually (or with some other
tool other than OrgFormation, e.g. Control Tower) and you want to start using
OrgFormation, you can easily import all your accounts and organizational units
with the org-formation init
command. However, there is no simple way to import
all your SSO resources like Groups, Permission Sets, and Assignments.
This means that you generally have 3 options:
- Start from scratch: Delete all your AWS SSO configuration and recreate everything as IaC in your OrgFormation template. Of course, this means that you might have some downtime where your users might not be able to access specific accounts or use specific profiles.
- Manage forward: Leave your existing AWS SSO configuration as is and start managing new resources with OrgFormation. This is generally not recommended as it will lead to a split-brain configuration where some resources are managed by OrgFormation and some are managed manually.
- Manual import: Manually import all your AWS SSO configuration into your OrgFormation template. This is probably the best approach because it allows to keep your existing resources and start managing them with OrgFormation. The problem is that this is a very manual and error-prone process. After all, importing resources in an existing CloudFormation stack is like performing brain surgery with a spoon! 🧠😨 So, unless you are a CloudFormation ninja (or a brain surgeon), you should probably avoid this approach.
This script tries to provide a fourth option. It basically tries to automate away all the complexity of a manual import by following a set of opinionated steps. This script will create a new OrgFormation template in your workspace, import Groups, Permission Sets and Assignments from AWS SSO and deploy them in a new CloudFormation stack in your management account. All by running one simple command!
Installation
Installation is optional (you can run the script directly with npx
), but if
you want to install it globally, you can run:
npm install -g org-formation-sso-import
Requirements
- Node.js 20.x or later
- AWS CLI (configured with the right permissions - ideally an admin user in the management account)
Usage
In your OrgFormation workspace, run the following command:
npx org-formation-sso-import
(or just org-formation-sso-import
if you installed it globally)
!NOTE\ This command assumes that your
organization.yml
file is in the root of your workspace.!IMPORTANT\ Your
organization.yml
file must have explicitAccountId
properties for every account in your organization.
If all goes well, you should see 2 new files in your workspace:
organization-tasks.yml
: This file contains the OrgFormation tasks to manage your AWS SSO configuration.templates/sso-assignments.yml
: The template you can edit to update your Groups, Permission Sets and Assignments.
After any change you can run:
org-formation perform-tasks organization-tasks.yml
to deploy the changes.
Configuration options
You can get the list of available options by running:
org-formation-sso-import --help
This will print something like:
--stack-name <value>
-s <value>
Pass the name of the stack to be deployed (default: "SsoAssignments")
--identity-store-id <value>
-i <value>
Pass the id of the identity store. If not provided will try to fetch for an existing one
--managing-instance-arn <value>
-m <value>
Pass the arn of the managing instance. If not provided will try to fetch for an existing one
--verbose
-v
Enables verbose mode
--help
-h
Prints this help
How it works
This script will perform a number of actions to import your AWS SSO configuration into your OrgFormation templates:
- It will create a new CloudFormation stack in your management account with the
name you provide (or
SsoAssignments
by default) and deploy it using OrgFormation. - It will query your AWS SSO configuration and retrieve groups, permission sets and assignments.
- It will import all of these resources into the CloudFormation SSO stack managed by OrgFormation (this follows the steps described in this AWS tutorial).
- It will create a new OrgFormation template in your workspace with the resources imported from AWS SSO.
From this point on, you can manage your AWS SSO configuration as IaC with OrgFormation and you wont' have to delete and recreate your groups, permission sets and assignments just to be able to manage them in OrgFormation.
Contributing
Everyone is very welcome to contribute to this project. You can contribute just by submitting bugs or suggesting improvements by opening an issue on GitHub.
License
Licensed under MIT License. © Luciano Mammino.