Skip to main content
This integration is in Beta. Contact your Lumos team to have it enabled for your domain.

​
What You’re Setting Up

You’re creating a read-only IAM role in your AWS account that Lumos assumes via AWS STS using an External-ID-gated trust policy. Lumos uses this role to surface non-human-identity risk — over-privileged roles, weak OIDC trust, wildcard-principal trust policies, externally-shared resources, publicly-invokable Lambda Function URLs, unused access keys, abandoned IAM users, GuardDuty compromise signals, and more. The policy is organised so that statements line up one-to-one with a setting in the integration UI: switch a workload off and you can delete its statement. The six statements prefixed NHIAgent have no setting — those are read by the NHI security agent and it produces findings without installing the data. What Lumos does NOT do:
  • No writes — every action is read-only.
  • No data-plane access — Lumos never reads secret values, S3 objects, KMS encryption, DynamoDB rows, or log-stream contents.
  • No CloudTrail log-file access — Lumos reads management-event history through the CloudTrail API, not from your CloudTrail S3 bucket, and only to establish when a workload last ran.
  • No role assumption beyond this scoped role.
Every call Lumos makes lands in your CloudTrail so you can audit exactly what ran.

​
Prerequisites

Before you start, make sure you have:
  • AWS IAM admin permissions in the account you want to connect (or a role that can create IAM roles and policies).
  • The Service Role External ID shown on your Lumos integration page (used in Step 2). Do not generate your own — Lumos issues a per-tenant value.
  • For full finding coverage, enable these in every region you want scanned:
    • IAM Access Analyzer with both analyzer types configured: an External Access analyzer (Type ACCOUNT or ORGANIZATION) powers externally-shared-resource and public-resource findings; an Unused Access analyzer powers stale-access-key and abandoned-user findings.
    • Amazon GuardDuty for active-compromise and lateral-movement detection. Neither is required to connect or to sync. Leaving them off costs you the findings listed under the NHIAgent statements in the policy and nothing else.
  • If you’re connecting multiple AWS accounts: each needs its own role and connection. See the “Connecting many accounts at once” section for StackSet instructions. Include your Organization management or delegated-admin account so Lumos can tell org-sibling trust relationships apart from external ones. One connection covers every region in an account, so you don’t need a separate connection per region.

​
Step 1 — Create the IAM policy

In the AWS console: IAM → Policies → Create policy → JSON. Paste the policy below and name it LumosNHIReadOnly-policy (any name works). The policy is split into one statement per integration setting so you can remove the services you do not want scanned. If you remove a service, toggle its setting off in the integration UI as well. Validate reports a toggled-on service with a missing permission as a setup error; a sync with the setting left on fails with AccessDenied. See the “Tailoring the policy” section below for what each statement covers and what you give up by dropping it.
ℹ A note on repeated actions: a few IAM actions appear in more than one statement — iam:ListRoles in three, iam:GetPolicy and iam:GetPolicyVersion in four. That is deliberate. Those calls are shared by several settings: resolving EKS IRSA bindings and federated trust policies both walk the full role list, and attached managed policies are resolved for users, roles and groups alike. Repeating them means each statement is independently deletable. IAM combines the grants automatically, so there is no need to consolidate.

​
Step 2: Create the IAM role

  1. Go to IAM → Roles → Create role.
  2. For Trusted entity type, choose AWS account.
  3. Under An AWS account, select Another AWS account and enter the Lumos account ID: 349123981986
  4. Check Require external ID and enter the Service Role External ID shown in the Lumos connector setup form.
  5. Click Next.
  6. On the Add permissions screen, search for the policy you created in Step 1, select it, and click Next.
  7. Give the role a name (e.g. LumosNHIReadOnly) and click Create role.

​
Step 3 — Note the role ARN

After the role is created, copy its ARN (format: arn:aws:iam::<your-account-id>:role/LumosNHIReadOnly). You’ll paste it into Lumos in the next step.

​
Step 4 — Update the trust policy

  1. Open the role you just created (click View role from the success banner, or find it under IAM → Roles).
  2. Go to the Trust relationships tab and click Edit trust policy.
  3. In the JSON document, set the AWS value inside the Principal block to the Lumos Customer Integrator Role ARN shown in the Lumos connector setup form.
  4. Click Save changes.

​
Step 5 — Connect in Lumos

  1. In the Lumos app, go to Integrations → Add Integration and search for “AWS IAM Identity Center (NHI)”.
Fill in the connector settings in Lumos with the values you collected:
  • Regions - one or more AWS region codes. Leave blank to scan every region in the account. While AWS reports me-south-1 and me-central-1 as unavailable, Lumos skips them when Regions is blank. If you list either region yourself, validation fails and asks you to remove it.
  • IAM Identity Center ARN - (Optional) Instance ARN from IAM Identity Center Settings. Connecting does not require IAM Identity Center; if the ARN is missing or does not match, Lumos logs a warning and continues.
  • Service Role ARN - ARN of the IAM role created in Step 3
  • Service toggles - one toggle per Fetch… statement in the policy. Turn off any service whose statement you removed. The EC2 toggle is labeled Fetch EC2 Instances and corresponds to the FetchEc2InstanceProfiles statement.
When you select Validate, Lumos first confirms it can assume the role and discover at least one region, then makes one read-only call per AWS service you toggled on, in the first region in your list. If a permission is missing, the error names every missing permission together with the setting that needs it. Services you leave off are not checked, so you do not need KMS or Bedrock permissions just to connect.
If you connected this integration before the Regions setting existed, your connection keeps scanning the one region it was created with. Set Regions, or leave it blank, to scan every enabled region. The old single-region field is ignored.

​
Connecting many accounts at once

The steps above connect one AWS account. To onboard an entire AWS Organization, Lumos publishes a CloudFormation StackSet template and an onboarding script that deploy the role across every account you select and connect them in a single run. Follow AWS_SETUP.md in the Lumos connector scripts repo. The script applies the same Regions value and service toggles to every connection it creates and deploys the matching permissions.

​
Scan behavior

  • Cadence: Follow the NHI security agent configuration. By default, Lumos doesn’t pull AWS IAM data on a regular basis unless the agent is configured to run on a schedule.
  • Session lifetime: each scan opens a short-lived STS session (5-10 min). Lumos never holds long-lived credentials.
  • Regions: scanning more regions takes longer, but not proportionally. Lumos queries regions in parallel, and the largest data sets — IAM users, roles, groups and policies — are global and fetched once regardless of how many regions you scan.
  • Unavailable regions: AWS currently reports me-south-1 and me-central-1 as unavailable. Accounts that opted into these regions still report them as enabled, but their endpoints never connect. When Regions is blank, Lumos drops them from the discovered region list and scans every other enabled region. When Regions lists either one, Lumos rejects the configuration instead of narrowing it without telling you.
  • Federated trust credentials: Lumos lists one OIDC or SAML credential per role trust policy that trusts the identity provider. For OIDC trusts with a sub condition, such as a GitHub repository, Lumos lists one credential per role and subject. Each credential is linked to the federated non-human account it grants access to. Identity providers that no role trusts, and EKS OIDC providers used for IRSA, are still listed once per provider with no linked account. If a role later trusts an unused provider, the next sync replaces the standalone credential with per-trust credentials. A trust policy that names a deleted provider gets no credential and does not fail the sync. OIDC and SAML credentials synced before per-trust credentials were introduced get new IDs on the next sync.
  • IAM user classification: Lumos treats an IAM user as a non-human service identity when the user has no console password (login profile) and has never signed in to the console. Lumos shows these programmatic-only users, with their access keys and permissions, as non-human accounts. Every other IAM user appears as a user account.

​
Troubleshooting

Validation fails with “The Regions setting includes AWS regions that are currently unavailable” The Regions setting lists me-south-1 or me-central-1, which AWS currently reports as unavailable. Remove the region from the Regions setting, or leave the setting blank to scan every available region enabled on the account.

​
Tailoring the policy

Statement names match the settings in the integration UI. Every statement aside from AlwaysRequired can be deleted before you create the policy — Lumos skips that service and the rest of the scan is unaffected. For any services removed from the policy, make sure that the corresponding setting in the Integration UI is toggled off. Statements prefixed with NHIAgent  have no integration setting at all as they power agent findings rather than data syncs.

​
Security FAQ

Does Lumos access data inside my AWS account (S3 objects, secret values, log contents)? No. The S3 permissions grant bucket-level metadata only — inventory, bucket policies, ACLs and public-access-block settings — never object contents.  DenyDataPlaneReads then explicitly blocks  s3:GetObject, s3:ListBucket, secretsmanager:GetSecretValue, SSM parameter reads, kms:Decrypt, DynamoDB item reads and CloudWatch Logs event reads. An explicit Deny in IAM overrides every Allow, so those calls fail for this role regardless of what else the policy grants. Every call Lumos makes lands in your CloudTrail so you can audit exactly what ran. Does Lumos read CloudTrail events? Yes, in a narrow way. Lumos calls cloudtrail:LookupEvents to find when a workload last ran where the service’s own API can’t say — for example AWS Batch, whose job list only retains finished jobs for about seven days, so older runs are recovered from SubmitJob events. Lumos reads this through the CloudTrail API rather than from your log bucket. It only runs when the CloudTrail activity settings are on. Why is iam:GetAccountAuthorizationDetails in the policy? It’s AWS’s dedicated read-only API for retrieving the IAM authorization graph — users, roles, groups, their inline + managed policy documents, trust policies, and RoleLastUsed. Using it in one call (rather than ~20 per-entity reads) keeps your CloudTrail cleaner and makes scans predictable. It’s IAM-metadata-only; there is no data-plane exposure. How are credentials handled? The Lumos service account in AWS account 349123981986 assumes your role via sts:AssumeRole with the External ID condition. Can I scope the role down further? Yes. The policy is split by integration setting so you can delete whole statements before creating it — see the “Tailoring the policy” section for what each one covers and what dropping it costs you. Only AlwaysRequired  must stay. Your Lumos account team can walk through the trade-offs. Can I remove the role later? Yes. Delete the role in IAM. The next Lumos scan fails with AccessDenied and Lumos surfaces a “connection lost” banner in the integration UI. No data exfiltration — Lumos cannot assume the role once it’s deleted.