> ## Documentation Index
> Fetch the complete documentation index at: https://docs.accessowl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS

AccessOwl integrates with AWS to manage access across your AWS Organization. It works through AWS IAM Identity Center (formerly AWS SSO), syncing permission sets, account assignments, and Identity Store users and groups.

<Note>
  The integration currently covers Identity Center only. Native IAM users, IAM groups, and IAM roles in your member accounts are not synced or provisioned.
</Note>

## Capabilities

<CardGroup cols={2}>
  <Card title="Structure Sync" icon="diagram-project">
    AccessOwl periodically syncs your AWS Organization accounts, Identity Center permission sets, and Identity Center groups.
  </Card>

  <Card title="User Sync" icon="arrows-rotate">
    AccessOwl syncs Identity Center users and groups along with their permission-set assignments per account.
  </Card>

  <Card title="Provisioning" icon="user-plus">
    AccessOwl creates Identity Store users, manages group memberships, and grants or revokes permission-set assignments during access requests and revocations.
  </Card>
</CardGroup>

## How the integration works

AccessOwl connects to your AWS Organization by assuming a single IAM role — `AccessOwlManagementRole` — in your **management account**. From there it can:

* read your organization's accounts, Identity Center configuration, and Identity Store directory
* manage account assignments and Identity Store memberships
* assume the standard `OrganizationAccountAccessRole` in each member account to discover Identity Center instances delegated outside the management account

Access is gated by two AWS-native controls:

* the role's **trust policy**, which only allows AccessOwl's provider role to call `sts:AssumeRole`
* an **External ID** that AccessOwl generates per tenant and that must match on every assume-role call, protecting against the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)

## Prerequisites

* Administrator access to your AWS Organization's **management account**
* AWS IAM Identity Center enabled, with its region known (e.g. `eu-north-1`)
* Member accounts have an `OrganizationAccountAccessRole` (see [Member-account role](#member-account-role) below)

## Setup

The AccessOwl setup assistant generates the exact JSON policies — with your tenant's External ID pre-filled — and walks you through the same flow as below. This page focuses on what needs to happen on the AWS side.

<Steps>
  <Step title="Create AccessOwlManagementRole in your management account">
    In your AWS Organization's **management account**, create an IAM role named `AccessOwlManagementRole` with a **custom trust policy** — paste the trust-policy JSON shown by AccessOwl. Leave the permissions screen empty during role creation; you'll attach permissions in the next step.

    <Tip>
      The trust policy embeds your tenant's **External ID** — keep it secret, and never reuse it across tenants or environments.
    </Tip>
  </Step>

  <Step title="Attach the permissions policy to the role">
    On `AccessOwlManagementRole`, add an **inline policy** with the permissions JSON shown by AccessOwl, and name it `AccessOwlManagementRolePolicy`.

    The policy grants the minimum permissions for sync and provisioning: AWS Organizations (`ListAccounts`), Identity Center (`sso:*` for permission sets and account assignments), Identity Store (`identitystore:*` for users, groups, and memberships), and `sts:AssumeRole` into `OrganizationAccountAccessRole` in member accounts.
  </Step>

  <Step title="Ensure OrganizationAccountAccessRole exists in member accounts" id="member-account-role">
    AccessOwl assumes `OrganizationAccountAccessRole` from the management role to discover Identity Center instances that may be delegated to a member account.

    * **Accounts created through AWS Organizations** — no action needed; AWS provisions this role automatically with a trust policy for the management account.
    * **Invited accounts** — create the role yourself with a trust policy for the management account and either the AWS-managed `AdministratorAccess` policy or the same permissions policy used in step 2.

    <Note>
      The role name must be exactly `OrganizationAccountAccessRole`. A custom name is not currently supported.
    </Note>
  </Step>

  <Step title="Connect AccessOwl">
    Back in AccessOwl, submit the management role ARN, the pre-filled External ID, and your Identity Center region (e.g. `eu-north-1`). AccessOwl validates the connection and starts the initial sync.
  </Step>
</Steps>

## Validation

After the initial sync completes you should see:

* your AWS Organization accounts listed in AccessOwl
* Identity Center permission sets, Identity Store users, and Identity Store groups

Run one test grant and one test revoke through AccessOwl to confirm provisioning end-to-end before rolling it out to users.

## Troubleshooting

<AccordionGroup>
  <Accordion title="AccessOwl can't connect to the management role">
    Check that:

    * the **External ID** in AccessOwl exactly matches `sts:ExternalId` in your trust policy (no leading/trailing whitespace)
    * the **Management Account Role ARN** is for `AccessOwlManagementRole` in your *management* account, not a member account
    * the **AWS Region** in AccessOwl matches the region of your Identity Center instance
  </Accordion>

  <Accordion title="A direct permission-set revocation stays pending with AccessDeniedException">
    Direct revocation of a permission set from a `USER` principal requires both `sso:DeleteAccountAssignment` and `sso:DescribeAccountAssignmentDeletionStatus`. Confirm both are present in the inline policy on `AccessOwlManagementRole` and on the affected member account if you've customized the policy there.
  </Accordion>

  <Accordion title="An Identity Center instance delegated to a member account doesn't show up">
    AccessOwl discovers delegated Identity Center instances by assuming `OrganizationAccountAccessRole` in each member account. If a delegated instance is missing, verify in that account that the role exists, is named exactly `OrganizationAccountAccessRole`, and trusts the management account.
  </Accordion>

  <Accordion title="AWS says 'Has prohibited field Resource' when pasting a policy">
    You're pasting the *permissions policy* into the *trust policy* editor. The trust policy goes on the **Trust relationships** tab (or during role creation under *Custom trust policy*); the permissions policy goes on the **Permissions** tab under **Add permissions → Create inline policy**.
  </Accordion>
</AccordionGroup>