Outcome
By the end of this lesson, you will be able to state exactly what IAM import writes and what it never touches, run the review-then-apply flow, and defend why nothing is applied automatically.
| Tier | Architect |
| JTBD | ”Onboard 200 people into ZopNight without rebuilding an access model I already maintain.” |
| Personas | Security/Compliance · Platform Engineer · Engineering Leader |
| Prerequisites | M3.1 (RBAC) |
| Time | 9 minutes |
| Bloom verb | State (Remember), Run (Apply), Defend (Evaluate) |
1. Concept
You already maintain an access model in AWS, GCP or Azure. Rebuilding it by hand in ZopNight for a 200-person org is a week of work and a permanent divergence risk.
Cloud IAM Import reads the principals from a connected cloud account and proposes an equivalent set of ZopNight users, teams and roles.
IT READS the customer's cloud IAM: users, groups, roles, and their attached policies
IT WRITES ZopNight's OWN users, teams and roles
IT NEVER touches the customer's cloud IAM. Not once, in any direction.That second row is the one to be exact about in a security review. The import is a one-way read of your cloud identity model and a write into ZopNight’s own tables.
Nothing applies automatically
THE FLOW 1. Connect a cloud account 2. Click Import IAM 3. REVIEW every proposed user, role and team 4. Apply
Nothing is written until step 4.The reason is worth stating in full, because “why isn’t this automatic” is the first question everyone asks:
Auto-applying would silently grant people access to a cost platform on the strength of permissions granted for something else.
THE CONCRETE FAILURE IT PREVENTS
An engineer holds an AWS role that lets them read S3 buckets in one account, for a data pipeline.
Auto-import would translate that into ZopNight access and hand them a view of the organisation's entire cloud spend.
Nobody granted that. The AWS grant was about a data pipeline, and cost visibility was never the intent.Cloud IAM encodes intent about infrastructure. It does not encode intent about who should see the bill. Those two frequently differ, and the review step is where a human states the difference.
Why this is an Architect-tier concern
Import is fast and its consequences are org-wide and durable. An import applied without review is not a mistake you notice quickly: nothing breaks, and a group of people simply have more visibility than anyone decided to give them.
So the review is not a formality. It is the only point in the flow where organisational intent enters.
What to actually look for in review
1. WHO GAINED ACCESS THEY DID NOT HAVE? Sort the proposed user list by whether they are new to ZopNight. Those are the additions.
2. WHICH PROPOSED ROLES ARE BROADER THAN THE PERSON'S JOB? A cloud admin is not automatically a cost admin.
3. WHO IS IN NEEDS ATTENTION, AND WHY? Unrecognised grants land there (L2). That list is where the genuinely ambiguous cases are.
4. DOES ANY PROPOSED TEAM LOOK WRONG? Cloud groups are frequently organised around infrastructure boundaries rather than cost ownership.Point 4 is the one people miss. A cloud group called s3-readers is a perfectly sensible infrastructure group and a meaningless cost-attribution team.
Where it lives
Import runs from the cloud account, and it isAdmin-only to initiate: it creates users and roles, andin M3.1's terms, changing who can change things is Admin.
The write target is ZopNight's users, teams and roles.The read source is the discoverer's IAM collectors plusthe config service's import logic.2. Demo
An import reviewed properly, and what the review caught:
ORG: mid-size company, 3 AWS accounts, 180 cloud principals, 12 people currently in ZopNight
IMPORT IAM on the production account proposed users 147 proposed teams 19 proposed roles 6 needs attention 11
REVIEW, in the four passes from the concept section
PASS 1: who is new? 135 of the 147 are not currently in ZopNight. That is the real number under discussion: this import would multiply the org's ZopNight population by 12.
DECISION: not all at once. They filtered the import to two teams for the first apply.
PASS 2: roles broader than the job? 4 of the 6 proposed roles mapped from cloud administrator policies -> ZopNight Admin.
Two of those four people are infrastructure admins who have no business changing cost budgets or connecting billing credentials.
DECISION: downgraded both to Editor before applying. The cloud grant was about infrastructure; the cost platform is a different question.
PASS 3: needs attention (11) 9 were custom roles whose actions did not translate cleanly (L2). 2 were service-account-only principals with no human behind them.
DECISION: resolved the 9 by hand, dropped the 2.
PASS 4: do the teams make sense? 19 proposed teams, of which: 7 mapped to real delivery teams -> kept 9 were infrastructure groupings (`s3-readers`, `vpc-admins`, `ec2-operators`) -> DROPPED 3 were legacy groups with no members -> dropped
The 9 infrastructure groups were the important catch. They are sensible AWS groups and meaningless cost teams: importing them would have produced a showback dimension nobody could act on, and it would have looked authoritative.
APPLIED 38 users, 7 teams, 6 roles (2 downgraded)
WHAT AUTO-APPLY WOULD HAVE PRODUCED 147 users, 19 teams, 4 unintended Admins, and a team structure organised around S3 and VPCs.3. Hands-on (6 min)
1. Run Import IAM on one connected account. DO NOT APPLY. proposed users ______ proposed teams ______ proposed roles ______ needs attention ______
2. How many proposed users are NOT already in ZopNight? ______ Is that a number your org would approve in one go? Y / N
3. Look at the proposed roles. How many map to ZopNight Admin? ______ For each, name the specific Admin-only capability that person needs: ______________________________________________ If you cannot name one, downgrade to Editor.
4. Look at the proposed teams. How many are organised around INFRASTRUCTURE rather than cost ownership? ______ Those are the ones to drop.
5. Write the sentence you would use in a security review to describe what import writes: ______________________________________________Why this part is console only. Cloud IAM Import runs in the console. There is no way to do it from an assistant, by design: the import reads your cloud provider’s identity graph and proposes role mappings, and accepting one grants access.
Everything after the import answers from an assistant: who is in the org, what role they hold, and what that role can actually do.
Tools that read it afterwards: list_users (read, Govern), add_org_member (write, tier 1, metadata only), get_my_permissions (read, Introspect). The full catalogue is at zop.dev/learn/mcp-tools.
4. Knowledge check
Q1
Cloud IAM Import writes to:
A. ZopNight’s own users, teams and roles only
B. The customer’s cloud IAM, adding a ZopNight role
C. Both, to keep them in sync
D. A staging table until a scheduled sync runs
Show answer
Correct: A. It reads the customer’s cloud IAM and never modifies it in any direction. Being exact about this is the first thing a security reviewer will test. The import is a one-way read of your cloud identity model and a write into ZopNight’s own tables.
Q2
Why does nothing apply automatically?
A. Because the translation is simply not reliable enough to be trusted blindly
B. Because the email addresses are frequently missing from the cloud principals that are being read
C. Because the provider APIs are rate-limited on the principal listing calls
D. Because cloud IAM encodes intent about infrastructure, not about who should see the bill
Show answer
Correct: D. Auto-applying would grant people access to a cost platform on the strength of permissions granted for something else: an S3 read role for a data pipeline would become a view of the organisation’s entire cloud spend, which nobody decided to give. The review step is the only point in the flow where organisational intent enters, which is why it is not a formality. An unreviewed import fails silently: nothing breaks and a group of people simply see more than anyone intended.
Q3
An import proposes a team named s3-readers with 14 members. The right handling:
A. Import it; it reflects a real cloud group
B. Import it and rename it after applying
C. Drop it
D. Import it as a role rather than a team
Show answer
Correct: C. Cloud groups are frequently organised around infrastructure boundaries rather than cost ownership, and s3-readers is a sensible AWS group and a meaningless cost-attribution team. Importing it would produce a showback dimension nobody can act on that nonetheless looks authoritative. This is the pass most reviewers skip. A team in ZopNight becomes a showback dimension, so a team that does not correspond to a cost-accountable group actively degrades attribution while appearing to improve coverage.
5. Apply
Run an import on one account and review it without applying. The count of proposed users who are not currently in ZopNight is the number to take to whoever owns access decisions in your org, and it is usually an order of magnitude larger than people expect.
Filter your first apply to one or two teams. Import is idempotent (L4), so a staged rollout costs nothing.
Related lessons
- L2: The translation staircase (next)
- L3: The org-management exclusion
- T3.M3.1.L2: System roles
- T3.M3.5.L2: Team attribution and shared resources
Glossary terms touched
IAM import · Principal · Needs Attention · Cost ownership