Fjall Docs — deploy AWS infrastructure into your own account

Prerequisites

Complete these first:

Enable IAM Identity Center in the management account
Deploy Organisation

Introduction

User access in a Fjall organisation is declared in code. The identityCentre block of fjall/organisation/infrastructure.ts describes your users, groups, permission sets, and memberships. fjall org deploy makes AWS IAM Identity Center match the declaration. No imperative user command writes to AWS behind your back, so every access change lands as a reviewable diff in your infrastructure file.

const organisation = OrganisationFactory.build("Organisation", {
  type: "organisation",
  accounts: ACCOUNTS,
  organisationName: "acme",
  orgEmail: "aws@acme.com",
  identityCentre: {
    source: "external",
    memberships: {
      AdministratorAccess: ["sarah@acme.com", "lee@acme.com"],
      ReadOnlyAccess: ["contractor@agency.com"],
    },
  },
});

Edit the block by hand, or use the fjall user verbs. They are safe file editors that produce the same diff.

fjall user add sarah@acme.com --group AdministratorAccess
fjall org deploy

Fjall looks up an existing IAM Identity Center instance in the management account and never creates one. Turn Identity Center on in the console before the first organisation deploy that carries an identityCentre block. Otherwise the deploy fails inside a CloudFormation custom resource rather than at synth time, which is far harder to diagnose.

Choosing an identity source

The source field declares who owns user objects. Pick the row that matches your organisation.

Mode	When to use it	User objects come from
`external`	You have Google Workspace, Okta, or Microsoft Entra and want SSO (recommended)	Your IdP, auto-provisioned via SCIM
`fjall-managed`	No external IdP. Fjall creates users in the native Identity Center directory	Declared `users` entries in the config
`external-manual`	SAML sign-in without SCIM. Users are mirrored manually to match your IdP NameIDs	Declared `users` entries, matched by NameID

external (IdP-owned, recommended)

Your IdP owns user creation and deletion. The config declares only group memberships, and Fjall resolves each email against the identity store at deploy time. Declaring a users block in this mode fails synth with a message telling you to switch to external-manual.

identityCentre: {
  source: "external",
  memberships: {
    AdministratorAccess: ["sarah@acme.com"]
  }
}

For Google Workspace, the guided runbook connects SAML and SCIM end to end:

fjall org identity setup-google --wait

--wait polls the identity store until the first SCIM-provisioned user appears, with a 1800-second budget you can change via --timeout <seconds>. If an email has not synced from your IdP yet, the deploy fails with a prescriptive IDC_* error. See the error ladder in the CLI reference. When a user is deleted and recreated in your IdP, run fjall user rebind and redeploy to re-bind memberships to the new identity.

fjall-managed

Fjall creates and manages the user objects. Declare each user with their memberships:

identityCentre: {
  source: "fjall-managed",
  users: {
    "sarah@acme.com": { givenName: "Sarah", familyName: "Chen" },
    "contractor@agency.com": {
      givenName: "Alex",
      familyName: "Reid",
      expires: "2026-09-30"
    }
  },
  memberships: {
    AdministratorAccess: ["sarah@acme.com"],
    ReadOnlyAccess: ["contractor@agency.com"]
  }
}

Every membership email needs a matching users entry. Without one the deploy fails at synth time. Users receive an AWS invitation email and set up MFA on first sign-in.

external-manual

SAML without SCIM. AWS requires user objects whose usernames mirror your IdP NameIDs, so declare them the same way as fjall-managed users. Memberships for emails not declared under users fall back to an identity-store lookup at deploy time.

Groups, permission sets, and memberships

Every organisation deploys with four built-in permission sets and their matching groups.

Group	Description	AWS managed policy
`AdministratorAccess`	Full administrative access	`AdministratorAccess`
`ReadOnlyAccess`	View-only access	`ReadOnlyAccess`
`Billing`	Billing and cost management	`AWSBillingReadOnlyAccess`
`ManagementAccountAccess`	Break-glass admin on the management account only	`AdministratorAccess`

ManagementAccountAccess is scoped to the management account alone, carries 2-hour sessions, and ships memberless. It grants nothing until someone joins the group. Beyond the defaults, the config declares custom groups and permission sets:

identityCentre: {
  source: "external",
  groups: {
    DataEng: { description: "Data engineering team" }
  },
  permissionSets: {
    DataEng: {
      managedPolicies: ["arn:aws:iam::aws:policy/AmazonAthenaFullAccess"],
      sessionDuration: "PT8H",
      accounts: ["Production", "Staging"],
      groups: ["DataEng"]
    }
  },
  memberships: {
    DataEng: ["lee@acme.com"]
  }
}

Key permission-set fields:

accounts: which ACCOUNTS-map names the set is assigned to. Default is every workload account. For a custom set, includeManagementAccount: true is the only route to the management account. The built-in ManagementAccountAccess already carries it.
sessionDuration: ISO 8601, between PT1H and PT12H. Omit it and AWS applies its own PT1H default.
managedPolicies, customerManagedPolicies, inlinePolicy, and permissionsBoundary: the policy surface, mirroring AWS permission sets.
groups: which groups the set binds to. Omit it and Fjall creates an implicit same-named group and binds that.
A permission set named after a built-in merges over that built-in’s spec, so you can retune sessionDuration or accounts without restating the policy. defaultPermissionSets: false suppresses all four built-ins.

Everything is validated at synth time. Unknown group references, case-variant duplicate emails, past-expiry members that still hold memberships, and malformed session durations fail the deploy before any CloudFormation runs.

Day-to-day access changes

Use the CLI verbs to edit the declaration, then deploy.

# Grant access (external mode: the IdP already owns the user object)
fjall user add lee@acme.com --group DataEng
fjall org deploy

# Declare a user in fjall-managed or external-manual mode
fjall user add sarah@acme.com --first Sarah --last Chen --group AdministratorAccess

# Time-boxed contractor
fjall user add contractor@agency.com --group ReadOnlyAccess --expires 2026-09-30

# Check the email resolves in the live identity store before writing
fjall user add newstarter@acme.com --group ReadOnlyAccess --live

# Remove one membership
fjall user remove lee@acme.com --group DataEng

# Remove a person entirely
fjall user remove leaver@acme.com
fjall org deploy

--first and --last declare the user entry itself, which fjall-managed and external-manual sources require. --live reads the Identity Center identity store, so it needs organisation AWS credentials. In an interactive shell, each successful write ends with an offer to run the organisation deploy in the same session. Identity-only organisation deploys typically take 2 to 5 minutes. Under --non-interactive or --agent the CLI prints the same estimate as a hint and makes no offer. Audit any time with:

fjall user list          # the declaration (pure file read)
fjall user list --live   # + drift columns from the live identity store

Verify provisioned users (external mode)

After connecting an IdP:

Log in to the AWS Console
In the top-left search bar, type IAM Identity Center and click the first result

Navigate to Users in the left navigation pane

You should see your users listed
- Check that Status is Enabled
- Check that Created by shows SCIM

From the terminal, fjall user list --live prints in-store or not-synced per declared email, plus a drift column for memberships that are declared but not yet live.

Next Steps

User CLI Reference

Full fjall user verb reference and error ladder.

AWS Profiles and Targets

See how Fjall derives profiles and resolves deploy targets.

Deploy Organisation

Deploy your AWS organisation.

Agent Tokens

Issue scoped API tokens for CI/CD and automation.

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Users and Permissions

Introduction

Choosing an identity source

external (IdP-owned, recommended)

fjall-managed

external-manual

Groups, permission sets, and memberships

Day-to-day access changes

Verify provisioned users (external mode)

Next Steps

User CLI Reference

AWS Profiles and Targets

Deploy Organisation

Agent Tokens

​Introduction

​Choosing an identity source

​external (IdP-owned, recommended)

​fjall-managed

​external-manual

​Groups, permission sets, and memberships

​Day-to-day access changes

​Verify provisioned users (external mode)

​Next Steps

User CLI Reference

AWS Profiles and Targets

Deploy Organisation

Agent Tokens

Introduction

Choosing an identity source

external (IdP-owned, recommended)

fjall-managed

external-manual

Groups, permission sets, and memberships

Day-to-day access changes

Verify provisioned users (external mode)

Next Steps