Manage an organizational structure with Okta and G Suite using Terraform 🏗
This project was developed at LiveRamp, but is no longer the canonical home
of future progress on this project. To download the latest version, report
an issue or submit a pull request, please visit joshk0/terraorg.
Any perspectives or direction on the canonical repository are endorsed
solely by its author and not by LiveRamp.
This tool helps define organizational structure using flat JSON files as a
source of truth for who is a member of an organization. Traditionally, there
are multiple sources of truth that need to be separately maintained. These JSON
files are processed into Terraform files which are meant to create nested
groups representing the organization that are usable in Okta and G Suite.
Additionally, the tool facilitates using this source of truth to generate
Markdown documentation about the org as well.
Based on the org that this tool was originally designed for, orgs are expected
to have three levels:
The tool generates groups for each granular unit of organization in Okta and G
Suite in Terraform. With patching, it could be possible for more organizational
systems to be supported.
Firstly, take your entire existing organization and define it using the
constructs of squads, platoons and organization. Groups will be generated;
use these groups to assign access to resources rather than individually
assigning access.
Whenever a person joins your organization, it should be the responsibility of
managers in the organization, or their delegates, to update the organizational
JSON files. If done correctly, updating the file, re-running terraorg to
generate source code, and applying the resulting source code would instantly
grant the person access to required services. Similarly, if a person leaves,
remove that person from the file and run the tool again.
See examples/
directory for examples of squads.json
, platoons.json
andorg.json
.
The tool expects the following environment variables to be defined and fails if
they are missing:
OKTA_API_TOKEN
: An API token with read/write admin access to your OktaOKTA_ORG_NAME
: Name of the Okta organization.OKTA_BASE_URL
: either okta.com
or oktapreview.com
depending on yourGSUITE_DOMAIN
: The G Suite domain suffix e.g. yourcompany.com
whichThe following environment variables are optional; if not specified, ensure
that your runtime setup matches the defaults.
TERRAORG_SQUADS
: defaulting to squads.json
, location of the squadsTERRAORG_PLATOONS
: defaulting to platoons.json
, location of the platoonsTERRAORG_ROOT
: defaulting to org.json
, location of the rootTERRAORG_OKTA_CACHE
: defaulting to okta_cache.json
, location of the OktaSLACK_DOMAIN
: defaulting to yourdomain.slack.com
, prefix of your SlackWhen running terraorg
, pass a second argument containing a subcommand.
Valid subcommands:
fmt
: Idiomatic formatting for all of your org files which will beterraform fmt
.auto.XXXX.tf
.generate-platoons-md
: Generate Markdown documentation for Squads.generate-squads-md
: Generate Markdown documentation for Squads.generate-tf
: Generate Terraform files. Output files will be of the formvalidate
: Ensure the input JSON files represent a valid, self-consistentSee examples/
directory for how to set up your Terraform workspace for plans
and applies of the files generated by this tool. At a minimum, you will need to
furnish articulate/terraform-provider-okta and
DeviaVir/terraform-provider-gsuite, and enable those as providers.
Please consult the respective Terraform modules’ home pages for more
information on how to configure the providers.
At LiveRamp, a pull request based workflow leveraging Atlantis is used to
interact with terraorg. The repository containing LiveRamp’s engineering
organizational structure is locked down and requires approval from
organizational leadership for any change.
Once approved, Atlantis leverages its API access to Okta and G Suite in order
to effect the group changes.
Similar process can be defined using CI tools such as Jenkins and Circle CI.
Implementation of such process is left as an exercise to the reader.