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

# Identity Center

*This article applies to AWS connections created after July 2025, where the Domain ID under your Lumos domain shows* `aws-sso_ics`*. If your Domain ID shows* `aws.amazon.com`*, your connection uses the archived pre-July-2025 setup, and the main differences are noted inline below.*

## After this article

You'll be able to connect AWS IAM Identity Center to Lumos to sync users, the AWS accounts they can access, their permission sets, and groups. Lumos can also create, update, and delete users and manage permission set and group assignments through the IAM role. With SCIM enabled, Lumos can additionally deactivate and reactivate users and sync enterprise attributes.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | Yes | User account records |
| AWS Accounts | Permission | Yes | No | Accounts under the organization |
| Permission Sets | Permission | Yes | Yes | Permission sets assigned across accounts |
| Groups | Permission | Yes | Yes | Identity Center group memberships |

| Deprovisioning Action | Type | Description |
| :- | :- | :- |
| Deactivate | User | Deactivate a user in Identity Center. Requires SCIM |
| Delete | User | Delete a user in Identity Center, through SCIM or through the Identity Store API when SCIM isn't configured |

**Provisioning behavior:**

* **Create:** with SCIM configured, Lumos creates the user via `POST /Users`. Without SCIM, it uses the Identity Store `CreateUser` action. Creation is idempotent: if AWS reports a conflict, Lumos looks up the existing user by username and then by email, links that account, and reports "Account already exists. No create action was needed."
* **Update:** profile changes (including the SCIM enterprise attributes listed below) go through a SCIM `PATCH`, or the Identity Store `UpdateUser` action when SCIM isn't configured.
* **Deactivate and reactivate:** SCIM only. If the account is already in the requested state, the action is a safe no-op.
* **Permission sets:** assignment and removal run through `CreateAccountAssignment` and `DeleteAccountAssignment`, which are asynchronous in AWS. Lumos polls the assignment status with increasing backoff until AWS reports it complete, so most assignments finish within seconds. Removing an assignment that AWS reports as already gone is treated as a successful no-op.
* **Groups:** Lumos creates or deletes the group membership in the Identity Store. Assigning a group the user already belongs to (for example when an access request is extended) is a safe no-op.

## Required plan and roles

* **AWS permissions:** you need elevated AWS permissions for **IAM**, **IAM Identity Center (SSO)**, and **AWS Organizations** to complete the setup.
* **Identity source:** your IAM Identity Center instance must use an **External identity provider** as its identity source.
* **Role permissions (simplest):** attach the AWS managed policies `AWSSSODirectoryAdministrator` and `AWSSSOMasterAccountAdministrator` to the role Lumos assumes.
* **Role permissions (least privilege):** attach this custom policy instead:

json

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAccessToIdentityCenter",
      "Effect": "Allow",
      "Action": [
        "identitystore:ListUsers",
        "identitystore:DescribeUser",
        "identitystore:ListGroups",
        "identitystore:DescribeGroup",
        "identitystore:ListGroupMemberships",
        "identitystore:GetGroupMembershipId",
        "identitystore:CreateGroupMembership",
        "identitystore:DeleteGroupMembership",
        "identitystore:CreateUser",
        "identitystore:DeleteUser",
        "organizations:DescribeAccount",
        "organizations:ListAccounts",
        "sso:DescribePermissionSet",
        "sso:ListAccountAssignments",
        "sso:ListAccountsForProvisionedPermissionSet",
        "sso:ListPermissionSetsProvisionedToAccount",
        "sso:ListInstances",
        "sso:ListPermissionSets",
        "sso:DescribeInstance",
        "sso:DescribeAccountAssignmentCreationStatus",
        "sso:DescribeAccountAssignmentDeletionStatus",
        "sso:DeleteAccountAssignment",
        "sso:CreateAccountAssignment",
        "sso:ListAccountAssignmentsForPrincipal"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AccessToSSOProvisionedRoles",
      "Effect": "Allow",
      "Action": [
        "iam:AttachRolePolicy",
        "iam:DeleteRolePolicy",
        "iam:DetachRolePolicy",
        "iam:ListAttachedRolePolicies",
        "iam:GetRole",
        "iam:CreateRole",
        "iam:DeleteRole",
        "iam:PutRolePolicy",
        "iam:UpdateRole",
        "iam:ListRolePolicies",
        "iam:UpdateRoleDescription"
      ],
      "Resource": "arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*"
    },
    {
      "Sid": "AccessToSCIMProvider",
      "Effect": "Allow",
      "Action": ["iam:GetSAMLProvider"],
      "Resource": "arn:aws:iam::*:saml-provider/AWSSSO_*_DO_NOT_DELETE"
    }
  ]
}
```

* **Read-only option:** for a read-only connection, drop all write actions from the policy above (keep only the `List*`, `Describe*`, and `Get*` actions) and leave the SCIM fields empty in Lumos. The SCIM token grants write access.
* **Permission purposes:**
  * `identitystore:*` actions read and manage users and groups in the Identity Store.
  * `sso:*` actions read permission sets and create or delete account assignments.
  * `organizations:*` actions map accounts under your organization.
  * The `iam:*` role actions are scoped to the AWS-reserved roles that Identity Center creates in member accounts when assignments change.

## Read-only access vs provisioning

**Is read-only possible?** Yes. Attach only the `List*`, `Describe*`, and `Get*` actions from the custom policy (the read-only reduction described above) and leave the SCIM Tenant ID and API Key fields empty in Lumos, since the SCIM token is what grants write access.

**What read-only requires.** A role with the read-only reduction of the custom IAM Identity Center policy above (Identity Store, SSO Admin, and Organizations read and list actions only), with no SCIM Tenant ID or API Key entered in Lumos. Follow the steps below, skipping the SCIM token generation in Phase 1 step 2.

**What full provisioning requires.** The full custom policy (or the `AWSSSODirectoryAdministrator` and `AWSSSOMasterAccountAdministrator` managed policies) plus the SCIM Tenant ID and API Key from Identity Center's Manage Provisioning page. Deactivating and reactivating users only works through SCIM. Creating, updating, and deleting users falls back to the Identity Store API when SCIM isn't configured.

**Watch out for.** AWS Identity Center only supports one active SCIM provisioning source at a time. If your identity provider (for example Okta) already owns SCIM provisioning, adding the Lumos SCIM token will conflict with it. Connect read-only instead and let the IdP keep handling lifecycle. Moving SCIM ownership to Lumos later requires the staged sequence set out in the Switching SCIM provisioning from your IdP to Lumos section below (disable SCIM in the IdP first, generate a new token, then roll out to a pilot group) rather than just adding the token.

## Instructions

**Phase 1: Prepare AWS**

1. Open the **IAM Identity Center** console → **Settings** and confirm **Identity source** shows **External identity provider**. If not, follow [AWS's instructions to change the identity source](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html).
2. Click **Actions** → **Manage Provisioning** to collect two SCIM values:
   * Copy the **SCIM endpoint**. This is the `Tenant ID` value for Lumos, and you can enter either the full SCIM endpoint URL or just the alphanumeric tenant ID from it. You can also find it under **Settings** → **Automatic provisioning** → **SCIM endpoint**.
   * Click **Generate token** and copy it. This is the `API Key` value for Lumos. You can also generate it under **Settings** → **Automatic provisioning** → **Access tokens**. SCIM is optional, but it's required for user activation and deactivation and for enterprise attributes. Skip these two values for read-only.
3. Back on **Settings**, copy the **IAM Identity Center ARN** (format `arn:aws:sso:::instance/ins-{id}`).
4. Note your **AWS Region** (shown in the top-right corner of the console, for example `us-west-2`).

Create the IAM role Lumos will assume, using either the AWS Console (Option A) or Terraform (Option B). **Option A: AWS Console**

* IAM Console → **Roles** → **Create Role** → **Another AWS account** → Account ID `349123981986`.
* Enable **Require external ID** and enter a secure value.
* Attach the managed policies or the least-privilege custom policy from above.
* Edit the trust relationship so the `Principal` is `arn:aws:iam::349123981986:user/global-service-account`.
* The connector uses the default **1 hour** session duration. Pre-July-2025 connections required the max session duration set to 12 hours.

**Option B: Terraform**

```hcl theme={null}
   data "aws_iam_policy" "AWSSSODirectoryAdministrator" {
     arn = "arn:aws:iam::aws:policy/AWSSSODirectoryAdministrator"
   }

   data "aws_iam_policy" "AWSSSOMasterAccountAdministrator" {
     arn = "arn:aws:iam::aws:policy/AWSSSOMasterAccountAdministrator"
   }

   resource "aws_iam_role" "lumos_identity_center_role" {
     name = "LumosIdentityCenterIntegrationRole"
     max_session_duration = 43200

     assume_role_policy = jsonencode({
       Version = "2012-10-17",
       Statement = [{
         Action = "sts:AssumeRole",
         Effect = "Allow",
         Principal = {
           AWS = "arn:aws:iam::349123981986:user/global-service-account"
         },
         Condition = {
           StringEquals = {
             "sts:ExternalId" = "CHOOSE_YOUR_EXTERNAL_ID"
           }
         }
       }]
     })
   }

   resource "aws_iam_role_policy_attachment" "directory_admin" {
     role       = aws_iam_role.lumos_identity_center_role.name
     policy_arn = data.aws_iam_policy.AWSSSODirectoryAdministrator.arn
   }

   resource "aws_iam_role_policy_attachment" "master_admin" {
     role       = aws_iam_role.lumos_identity_center_role.name
     policy_arn = data.aws_iam_policy.AWSSSOMasterAccountAdministrator.arn
   }
```

6. Copy the role ARN and your external ID.

**Phase 2: Connect in Lumos**

1. Find the AWS IAM Identity Center card in your Lumos integrations. Reconnect an existing card or add a new one.
2. Enter the **Region**, **IAM Identity Center ARN**, **Service Role ARN**, **External ID**, and, optionally for provisioning, the **Tenant ID** (SCIM endpoint) and **API Key** (SCIM token).
3. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Access Denied when assuming the role.** Verify the Service Role ARN. Check the External ID matches the trust policy exactly. Confirm Lumos account `349123981986` is a trusted principal, and verify the role exists.

**Instance not found.** Verify IAM Identity Center is enabled. Check the ARN format is `arn:aws:sso:::instance/ins-{id}` and was copied from **Settings** → **Instance ARN**.

**SCIM operations are failing.** Verify SCIM (automatic provisioning) is enabled in Identity Center. Regenerate the access token if it expired, and check the SCIM identifier matches your tenant ID. The SCIM endpoint URL must match the expected AWS pattern (`https://scim.{region}.amazonaws.com/{tenant_id}/scim/v2/`).

**Permission set assignment times out.** Account assignment creation and deletion is asynchronous in AWS. Lumos polls the assignment status with backoff until AWS reports it complete, so a step that still times out usually means AWS itself has not settled the change. Check the AWS console for the final status before retrying.

**Insufficient permissions.** Review that your custom policy includes the Identity Store, SSO Admin, and Organizations read actions.

**Users managed by an external IdP.** AWS Identity Center supports only one active SCIM provisioning source at a time, because the SCIM token is the system of record for lifecycle operations. AWS's SCIM token can be used by one service only, so you can't share the same token between Okta and Lumos. If your users are provisioned into Identity Center by your identity provider's SCIM (for example, Okta), connect read-only (leave SCIM fields empty) for Access Reviews and role mining. Okta can stay in place for SSO while Lumos handles SCIM. If sharing the token would break your existing flow, connect without SCIM. To move SCIM ownership from your IdP to Lumos, follow the sequence in the next section.

**IAM users aren't visible.** This connector surfaces Identity Center identities only. Native IAM users in individual accounts require the separate AWS IAM connector.

**Provisioning works for member accounts but fails on the management account.** If you trimmed the `iam:*` statements out of the custom policy, assignments into member accounts can still succeed while assignments in the account that hosts IAM Identity Center return a permissions error. The Identity Center provisioned roles and the SAML provider are anchored in that account, so the role actions scoped to `arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*` and `iam:GetSAMLProvider` scoped to `arn:aws:iam::*:saml-provider/AWSSSO_*_DO_NOT_DELETE` are required there. Add both statements from the custom policy above to the Lumos role, then retry the provisioning action.

**A synced permission can't be deleted in Lumos.** Groups and permission sets that Lumos reads from Identity Center are owned by the integration, so removing them in Lumos doesn't stick and they return on the next sync. Remove the underlying group or assignment at the source, either in Identity Center or in the identity provider that pushes the group into Identity Center, and let the next sync drop it. If you only need the permission out of the AppStore, hide it in Lumos instead.

**"Account already exists. No create action was needed."** A Create Account step that provisions into IAM Identity Center returns this error, and the workflow stops on a manual task, when the user already has an Identity Center account. This happens when the step sits in the account provisioning workflow of a different app, such as a custom app whose accounts Lumos doesn't sync. Lumos checks for an existing account on the app being requested, and an app with no synced accounts always looks like the user has no account, so the create step runs every time. Two options:

* Drive account creation from the AWS IAM Identity Center app itself. The existing-account check then looks at Identity Center, where Lumos already syncs accounts, so it skips creation for existing users and still creates accounts for new ones.
* Contact Lumos support about enabling handling that recognizes the existing Identity Center account and continues the workflow instead of raising a manual task. This requires SCIM to be configured on the connection and the existing Identity Center account to be matched to the user's Lumos identity.

When you test this, use a user who has an Identity Center account but has never been set up on the requesting app. Earlier failed runs can leave an account record on the requesting app, and once that record exists Lumos skips the account provisioning steps for that user, so the workflow reports success without assigning the entitlement.

**"Group membership not found for given Pool/Group/Member" when removing access.** Lumos looked up the Identity Center group membership to delete and AWS reported that the user isn't in that group. This usually means the matching assignment step never completed, so there is nothing to remove. Check the user's group memberships in Identity Center, and if the access was granted through a workflow, confirm that the assignment step ran successfully.

## Switching SCIM provisioning from your IdP to Lumos

Adding the Lumos SCIM token doesn't automatically deprovision users that your IdP already provisioned. Connecting Lumos with the SCIM token lets Lumos provision and deprovision going forward, but Lumos doesn't run a destructive reset on initial connection. Deprovisioning happens only when an explicit Lumos-driven lifecycle event runs, such as a user marked inactive or removed through an access policy or offboarding workflow.

The risk isn't a mass removal on connection. It's that AWS supports only one active SCIM source, so you need to transition ownership carefully. Recommended sequence when moving from an IdP to Lumos:

1. Disable SCIM provisioning in your IdP first. This stops the IdP from pushing updates or treating Lumos-managed users as out of sync.
2. Don't delete users in AWS Identity Center. Existing users can stay in place, and Lumos maps and manages them going forward.
3. Generate a new SCIM access token in AWS Identity Center: **Settings** → **Manage Provisioning** → **Generate token**.
4. Connect Lumos using the SCIM endpoint and token. Lumos requires both the SCIM tenant identifier and the SCIM token for provisioning operations.
5. Validate lifecycle management in a staged way. Start with a small pilot group of users to confirm behavior before expanding coverage.