Policy References
A Policy Reference is a pointer to an IAM policy that already exists in your AWS accounts. Prism attaches it to the roles it provisions at the policy's real ARN — it never copies the document, never adds a prefix, and never edits, versions or deletes it.
A reference stores only a name and an IAM path. The account ID is filled in when Prism attaches it, so one reference resolves to a different real policy in every account:
| Account | What Prism attaches for reference S3ReadBaseline at path /security/ |
|---|---|
111122223333 | arn:aws:iam::111122223333:policy/security/S3ReadBaseline |
444455556666 | arn:aws:iam::444455556666:policy/security/S3ReadBaseline |
If those two accounts hold different documents under that name, the permission set grants different permissions in each. That is the intended behaviour, and it is the reason references exist — see Documents in Accounts.
References vs Customer Managed Policies
Both attach to the same provisioned role and both consume one of its ten managed-policy slots. The difference is who owns the document.
| Customer Managed Policy | Policy Reference | |
|---|---|---|
| Console label | Prism-managed | Reference |
| Who writes the document | You, in Prism | Your organisation, in each account |
| What Prism creates in the account | Prism-<policy-name> | Nothing — it attaches what is already there |
| Same document in every account | Yes | Not necessarily |
| Editable in Prism | Yes | No |
| Removing it in Prism | Detaches and deletes Prism's copy | Detaches only |
Use a Customer Managed Policy when you want one document you control everywhere. Use a Policy Reference when the policy already exists in your accounts and each account's own version is the correct one.
Policy References List
Admin Portal > Customer Managed Policies lists both kinds together. References carry a blue Reference chip and show their IAM path beneath the name.
| Column | Meaning for a reference |
|---|---|
| Type | Reference |
| Permission Sets | How many permission sets attach it |
| Documents in Accounts | How many distinct documents were found — not a count of accounts |
Available Actions
References support view detail and remove only. There is no edit action: Prism does not own the document and cannot change it.
Where References Come From
References reach Prism two ways.
Imported from IAM Identity Center
When a permission set in Identity Center carries a customer managed policy reference, SSO replication imports it automatically. Identity Center is the source of truth for these — every replication run rebuilds the reference list from what Identity Center reports.
Because replication rebuilds the list from Identity Center, a reference you attach in Prism to a permission set that also exists in Identity Center is removed on the next replication run, and detached from the roles in AWS. To attach a reference permanently to such a permission set, add it in Identity Center.
Importing a reference records it in Prism. The policy is attached in AWS the next time that permission set's role is provisioned or refreshed.
Added manually in Prism
Use Add Reference when the policy exists in your accounts but is not declared on the permission set in Identity Center.
Add a Reference
Prerequisites
- The policy should already exist in the accounts where the permission set is provisioned. You can add a reference before creating the policy, but it will not attach anywhere until the policy exists.
Step-by-Step Guide
- Navigate to Admin Portal > Customer Managed Policies.
- Click Add Reference.
- Enter the Policy name exactly as it appears in IAM. Prism adds no prefix.
- Enter the Path, for example
/or/security/. - Click Add reference.
Field Reference
| Field | Rules |
|---|---|
| Policy name | Must match the customer's IAM policy name exactly. Up to 128 characters, matching [A-Za-z0-9+=,.@_-]. |
| Path | The IAM path the policy lives under. Defaults to /. Must begin and end with /. |
Adding a reference that already exists with the same name and path does not create a duplicate. Prism reuses the existing reference and the dialog simply closes.
Attach a Reference to a Permission Set
References are attached through the permission set edit flow, exactly like Customer Managed Policies.
Step-by-Step Guide
- Navigate to Admin Portal > Permission Sets.
- Open the permission set, or create a new one.
- Expand the Policy Attachments section.
- Tick the reference under Customer-owned policy references. The slot meter updates live.
- Save.
Prism attaches the customer's ARN to every role already provisioned for this permission set.
A role can carry at most 10 managed policies. AWS Managed, Prism-managed and references all count toward that one limit. Over the limit, Prism shows the breakdown — for example "10 AWS-managed + 0 Prism-managed + 2 referenced = 12. Remove 2 before saving." — and disables save.
Detach a Reference
Uncheck the reference and save. Prism detaches the policy from every role provisioned for that permission set. Your IAM policy is not deleted.
Documents in Accounts
Open a reference to see what it actually resolves to. Prism reads the policy in each account and groups the accounts by document.
Reading the breakdown
| What you see | Meaning |
|---|---|
| 1 document | Every account that has this policy holds the same document. Healthy. |
| N different documents | The policy differs between accounts. The permission set grants different permissions depending on the account. |
| Not yet checked | No check has run yet, or a check ran and found the policy in no account at all. Open the reference to tell the two apart. |
Each group shows the account IDs that share it and the document itself. The largest group is marked Plurality — that is the document conversion would adopt.
Accounts that could not be read
Two states are reported separately because they need opposite fixes:
| State | Meaning | What to do |
|---|---|---|
| Not present | Prism read the account successfully; the policy does not exist there. | Create the policy in that account, or accept that the permission set grants nothing through this reference there. |
| Could not be read | Prism was denied when reading the account. The policy may exist and may differ. | Fix Prism's access to that account, then re-check. |
Which accounts are checked
Only accounts where a permission set carrying this reference is provisioned. Accounts that are not onboarded, not assigned this permission set, or whose assignment has not finished provisioning are not checked and are not reported at all.
Re-check Accounts
The breakdown refreshes automatically during SSO replication. To refresh it on demand, open the reference and click Re-check accounts. This is read-only — it reads the policies and updates the breakdown, and changes nothing in AWS.
If a reference has stopped being provisioned anywhere, Re-check accounts reports success but leaves the previous breakdown on screen. The stale breakdown is cleared by the next SSO replication run.
Convert a Reference to a Prism-Managed Policy
Conversion takes over ownership: Prism creates its own Prism-<policy-name> copy carrying one document, and stops attaching your original.
Conversion cannot be undone, and in accounts whose document differs from the one Prism adopts, permissions change.
When to convert
Convert when the divergence is accidental and you want one document everywhere under Prism's control. Do not convert when each account's version is deliberately different — conversion flattens that.
Prerequisites
- The reference must have been checked at least once and found in at least one account. A reference that has never been checked cannot be converted.
- No Prism-managed policy may already exist with the same name.
Step-by-Step Guide
- Open the reference from Admin Portal > Customer Managed Policies.
- Click Convert to Prism-owned.
- Review the impact preview.
- Tick the acknowledgement checkbox.
- Type the policy name to confirm.
- Click Convert.
Reading the impact preview
Prism adopts the plurality document — the one held by the most accounts — and shows what that means per account:
| Bucket | Meaning |
|---|---|
| Permissions change | These accounts hold a different document today. Converting rewrites what they grant. Read this list carefully. |
| No change | These accounts already hold exactly the document Prism will own. |
| Created for the first time | The policy does not exist in these accounts. Conversion creates it there, granting permissions that did not exist before. |
| Unknown | Prism could not read these accounts, so the effect cannot be predicted. |
What happens next
Conversion updates Prism's records immediately, but makes no AWS calls. The Prism-<policy-name> policy is created in your accounts, and your original detached, the next time each role is provisioned — during the next SSO replication run, or when you next save that permission set.
Until then, roles still carry your original policy.
What is left alone
Your original policy stays in every account, byte-for-byte unchanged. Prism simply stops attaching it.
Converting also permanently consumes that name and path. If you add the same reference again later, it will appear to succeed but will not show in the list and cannot be attached.
Remove a Reference
Removing a reference stops Prism attaching it. It does not delete your policy.
Step-by-Step Guide
- Navigate to Admin Portal > Customer Managed Policies.
- Click the delete icon on the reference row.
- Read the confirmation, which names the permission sets that lose it.
- Click Remove reference.
Prism detaches the policy from every role provisioned for the affected permission sets. Your IAM policy remains in every account, and anything outside Prism that attaches it keeps working.
You can add the reference again later and Prism will re-attach the same existing policy.
Edge Cases & FAQs
Why does one reference show different permissions in different accounts?
Because it points at a policy each account owns separately. Prism attaches the ARN; AWS resolves it to whatever that account holds. See Documents in Accounts.
The referenced policy is missing in one account. What happens?
That account's attach fails and the failure is recorded. The role is still created in that account — it simply comes out without that policy — and the other accounts are unaffected.
IAM Identity Center behaves differently. If a permission set in Identity Center references a customer managed policy that is missing in an account, Identity Center refuses to provision the permission set to that account at all. Prism is deliberately more permissive: it provisions what it can and records the rest.
Can a reference and a Customer Managed Policy have the same name?
Yes. They are different IAM objects — :policy/Baseline and :policy/Prism-Baseline. They can both be attached to the same permission set and both count toward the ten-policy limit.
You cannot, however, convert a reference to a name that a Prism-managed policy already uses.
Why did my reference disappear after a replication run?
If the permission set also exists in IAM Identity Center, replication rebuilds its reference list from Identity Center. A reference added only in Prism is removed. Add it in Identity Center instead.
Does removing a reference delete my policy?
No. Prism never deletes a policy it did not create. Removal detaches only.
Can I edit a referenced policy in Prism?
No. Edit it in the AWS account that owns it, then use Re-check accounts to refresh what Prism shows.
Navigation
- Admin Portal > Customer Managed Policies, References are listed here alongside Prism-managed policies.
- Admin Portal > Permission Sets, Attach references to permission sets here.
- Admin Portal > Assignments, Provision permission sets (and the policies they attach) to AWS accounts.