# Test access with the policy simulator

Ask whether a user, a role or an unsaved policy allows an action on a resource, and see which statement decides it.

The simulator changes nothing and uses the same evaluation as every request. Replace
org-EXAMPLE1234 with your organization id and user-id with the IAM user's id.

## Prerequisites

- To test a user or a role, `iam:SimulatePrincipalPolicy` on it.
- To test a draft policy, `iam:SimulateCustomPolicy`. A draft tested on a user or a role needs both.
- In the console, `iam:ListUsers` and `iam:ListRoles` to choose among users and roles under
  **Who**; without them the list offers only you.

Both simulate actions are reads, included in `IamReadOnlyAccess`.

## Run a simulation

**Console**
1. Open **Identity**, then choose **Policy simulator**.
2. For **Who**, choose a user or a role, or **No principal (the draft alone)** to test only a draft.
3. For **Action**, choose one action, such as `ec2:StopInstances`.
4. For **Resource**, enter a resource name such as
   `rn:ews:de1:org-EXAMPLE1234:ec2:instance/i-0123`, or `*`.
5. (Optional) For **Draft policy (optional, not saved)**, paste a policy document. It is evaluated as
   if it were attached to the principal.
6. (Optional) Open **Request context** and set the source IP, whether the session signed in with a
   second factor, and the zone.
7. Choose **Simulate**.

**CLI**
```sh
dcloud iam policies simulate --action ec2:StopInstances \
  --resource 'rn:ews:de1:org-EXAMPLE1234:ec2:instance/i-0123' \
  --principal '{"type":"user","id":"user-id"}' \
  --context '{"sourceIp":"192.0.2.10","multiFactorAuthPresent":true}'
```

**API**
```http
POST /iam/api/simulate
{ "principal": { "type": "user", "id": "3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f" }, "action": "ec2:StopInstances", "resource": "rn:ews:de1:org-EXAMPLE1234:ec2:instance/i-0123" }
```

`policyDocuments` takes up to 10 drafts as JSON text.

## Result

The answer is **Allowed**, **Explicitly denied** or **Implicitly denied** (`allowed`,
`explicitly_denied`, `implicitly_denied` in the API). Under **Statements that name this action**,
every statement for the action is listed with its effect, the policy it is in, how that policy
reaches the principal (directly, through a group, through a role, or as the draft), whether it
decides, and why: the resource did not match, the condition did not hold, or the condition could not
be decided.

- A condition key you leave empty is unknown, as for a request that does not carry it: an `Allow`
  that depends on it does not apply, and a `Deny` does. The time is now and the region is yours
  unless the CLI or API sets `currentTime` or `requestedRegion`.
- An inactive user is noted on the answer: it cannot sign in or use access keys, whatever the
  policies say.
- An S3 bucket's own policy is not part of the simulation.

In the audit log, a refused entry has the link **Why? Open in the policy simulator**, which opens
the simulator with that user, action and resource filled in.

## If the simulation is refused

- 400 `Name a principal, pass policyDocuments, or both`
- 400 `Unknown action "…"`
- 400 `Resource is not in this organization`
- 400 for a draft that does not pass the policy checks; the message names the draft by its position
  and gives the reason.
- 404 `No such user` or `No such role`.

## Related

- [How a request is decided](how-a-request-is-decided.md)
- [Policy documents](policy-documents.md)
- `iam.policies.simulate` · `dcloud iam policies simulate`
