Roles and IAM Policies

An IAM policy defines statements. A role collects IAM policies. Users and teams can receive roles through organization or team assignments. API-token role assignments are organization-scoped; they do not have a separate team assignment scope.

Keeptrusts evaluates access with deny-by-default behavior:

1. A matching deny wins.
2. A matching allow grants the action.
3. No matching allow means deny.

Design a policy

Each statement has:

• effect: allow or deny;
• one or more action patterns;
• one or more resource KRN patterns; and
• optional conditions over caller, resource, or request attributes.

Start with the Permissions Reference. Do not invent action strings from UI labels.

Use exact actions and narrow resources where practical. A wildcard resource can be appropriate for a collection-wide reviewer role, but it should be a reviewed decision rather than a default.

Create through the console

1. Open IAM → Policies, then select New policy.
2. Give the policy a job-focused name and description.
3. Add the smallest actions and resources that satisfy the workflow.
4. Add conditions only when the relevant attributes are reliably present.
5. Save and inspect the policy detail page.
6. Open IAM → Roles, then select New role.
7. Attach the policy to the role.
8. Assign the role to a test team or member.
9. Verify expected allows and expected denies.

Do not confuse these IAM policies with the separate Access policy creation route. That route stores Unified Access request-execution constraints such as model, gateway, provider, project, configuration, and agent scope; it does not create an IAM statement policy or attach one to a role. See Unified Access for its current enforcement boundaries.

Inspect effective access

Review all three views:

View	Question
Policy statements	What can this policy allow or deny?
Role effective actions	What does the complete role resolve to?
Role assignments	Which users, teams, or tokens receive the role?

An attached policy is not effective for a person until the role is assigned in the applicable scope. Conversely, deleting one assignment may leave access through another team, direct grant, or role.

Test policy logic before applying

The CLI can simulate an IAM policy document:

kt policy evaluate \
  --file iam-policies.yaml \
  --action events:read \
  --resource-krn 'krn:keeptrusts:events:eu:org_example:events' \
  --json

Optional caller, resource, and request attributes are JSON. Test:

• the expected allowed action;
• a nearby action that must remain denied;
• an in-scope resource;
• an out-of-scope resource; and
• each meaningful condition boundary.

Simulation tests the supplied statements. It does not prove that production identity attributes, assignment scope, or authentication state match the simulation.

Deny and wildcard review

Treat these as high-impact:

• deny statements;
• * actions or resources;
• broad region or organization wildcards;
• conditions that depend on optional attributes;
• roles assigned to owners or automation tokens; and
• changes to policies attached to many roles.

A deny can override several allows. Before adding one, inspect every role and principal that can encounter the matching action and resource.

Remove access safely

1. Inspect role assignments.
2. Find alternative direct and inherited grants.
3. Simulate the intended post-change result.
4. Detach the role or policy in a test scope.
5. Verify expected denial with a representative account.
6. Apply to the production scope.
7. Review Trail.

Use explicit confirmation for destructive CLI commands:

kt role detach-policy \
  --role-id role_example \
  --policy-id policy_example \
  --yes

Common mistakes

Mistake	Better approach
Testing with an owner	Test with the actual role and scope.
Assigning roles directly to everyone	Assign a job-function role to a team.
Using a broad wildcard because one request failed	Inspect the rejected action and resource KRN.
Deleting a policy before checking assignments	Inspect effective actions and assignments first.
Treating SSO group mapping as the policy itself	Map groups to reviewed roles and teams.

Next steps

• Permissions Reference
• Members and Teams
• IAM CLI
• Policy Lifecycle