Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Pre-Requisites

Complete these first:

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 deploy organisation makes AWS IAM Identity Center match the declaration. There are no imperative user commands that write to AWS behind your back — every access change is 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"],
    },
  },
});

You can edit the block by hand, or use the fjall user verbs — safe file editors that produce the same diff:

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

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. Fjall resolves each email against the identity store at deploy time.

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

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

fjall org identity setup-google --wait

If an email hasn’t 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-30T00:00:00Z"
    }
  },
  memberships: {
    AdministratorAccess: ["sarah@acme.com"],
    ReadOnlyAccess: ["contractor@agency.com"]
  }
}

Every membership email must have a matching users entry — the deploy fails at synth time otherwise. 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. Declare them like fjall-managed users; memberships for emails not declared in users fall back to a store lookup.

Groups, permission sets, and memberships

Every organisation deploys with three default groups:

Group	Description	AWS Permissions
`AdministratorAccess`	Full administrative access	All AWS services
`ReadOnlyAccess`	View-only access	Read all resources
`Billing`	Billing and cost management	Cost Explorer, Budgets

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: all workload accounts). includeManagementAccount: true is the only route to the management account.
sessionDuration — ISO 8601, between PT1H and PT12H.
managedPolicies / customerManagedPolicies / inlinePolicy / permissionsBoundary — the policy surface, mirroring AWS permission sets.
A permission set named after a default group merges over that default’s spec; defaultPermissionSets: false suppresses the three built-ins.

Everything is validated at synth time — unknown group references, case-variant duplicates, past-expiry members, 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
fjall user add lee@acme.com --group DataEng
fjall deploy organisation

# Time-boxed contractor
fjall user add contractor@agency.com --group ReadOnlyAccess --expires 2026-09-30T00:00:00Z
fjall deploy organisation

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

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

After each successful write the CLI offers to run the organisation deploy for you — identity-only deploys typically take 2–5 minutes. 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

Or from the terminal: fjall user list --live shows in-store / not-synced per declared email.

Next Steps

User CLI Reference

Full fjall user verb reference and error ladder.

Understanding Profiles

See how profiles map to AWS accounts.

Deploy Organisation

Deploy your AWS organisation.

Agent Tokens

Issue scoped API tokens for CI/CD and automation.

Install & Setup

Application Deploy

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

Understanding Profiles

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

Understanding Profiles

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