Skip to main content

Role Mappings

Role Mappings let you automatically assign Guardian Pro permission levels based on the AWS IAM roles your team members use. Instead of manually assigning a Guardian Pro role to every user, you can define mapping rules that determine the appropriate access level based on existing IAM role patterns.

Why Use Role Mappings​

In most organisations, AWS IAM roles already reflect team responsibilities:

  • Platform engineers assume administrative roles with broad access.
  • Security auditors assume read-only roles scoped to security services.
  • Developers assume roles with access to specific application resources.

Role Mappings bridges this existing structure into Guardian Pro, so you do not need to maintain a separate access control scheme. When a new user is provisioned through onboarding or invitation, their Guardian Pro role can be automatically determined from their AWS IAM role.

tip

Role Mappings are optional. You can always assign Guardian Pro roles manually through the Users page. Role Mappings simply automate this process for organisations with established IAM role conventions.

Accessing Role Mappings​

Navigate to Settings > Role Mappings from the left sidebar. You need the org:read permission to view mappings and org:write to create or modify them.

How Role Mappings Work​

A role mapping is a rule that says: "When a user's AWS IAM role matches this pattern, assign them this Guardian Pro role."

Each mapping consists of:

FieldDescription
IAM Role PatternThe AWS IAM role name or ARN pattern to match against
Guardian Pro RoleThe role to assign: Admin, Standard, or Read-Only
PriorityThe order in which mappings are evaluated (lower number = higher priority)
DescriptionAn optional note explaining the purpose of this mapping

Pattern Matching​

Role Mappings support two matching modes:

  • Exact match -- The IAM role name must match exactly (e.g., GuardianProAdmin).
  • Wildcard match -- Use * as a wildcard to match partial role names (e.g., SecurityAuditor* matches SecurityAuditorProd, SecurityAuditorDev, etc.).

Evaluation Order​

When a user's IAM role matches multiple mapping rules, the rule with the highest priority (lowest priority number) is used. If no rules match, the user receives the default role configured for your organisation (typically Read-Only).

note

Priority numbers must be unique. No two mapping rules can have the same priority value.

Creating a Role Mapping​

To create a new role mapping:

  1. Navigate to Settings > Role Mappings.
  2. Click Add Mapping.
  3. Enter the IAM role pattern (exact name or wildcard pattern).
  4. Select the Guardian Pro role to assign.
  5. Set the priority (lower numbers are evaluated first).
  6. Optionally, add a description.
  7. Click Save.

Example Mappings​

Here are common mapping configurations:

IAM Role PatternGuardian Pro RolePriorityDescription
OrganizationAdmin*Admin1Full admin access for org administrators
PlatformEngineer*Admin2Full access for platform team
SecurityAuditor*Read-Only3View-only access for auditors
Developer*Standard4Standard access for development teams
*ReadOnly*Read-Only5View-only for any read-only IAM role
caution

Be careful with broad wildcard patterns like *Admin*. Ensure your priority ordering is correct so that more specific rules are evaluated before broader ones. A catch-all rule with a wildcard should always have the lowest priority (highest number).

Editing a Role Mapping​

To modify an existing mapping:

  1. Find the mapping in the list.
  2. Click the Edit icon.
  3. Update the fields as needed.
  4. Click Save.

Changes to role mappings apply to future user provisioning and role evaluations. Existing users retain their current roles unless you manually reassign them or trigger a role re-evaluation.

Deleting a Role Mapping​

To remove a mapping:

  1. Find the mapping in the list.
  2. Click the Delete icon.
  3. Confirm the deletion.

Deleting a mapping does not change the roles of users who were previously assigned through that mapping. Their current role remains in effect.

Default Role​

When no role mapping matches a user's IAM role, the user is assigned the default role. You can configure the default role at the top of the Role Mappings page.

The default role applies to:

  • Users whose IAM roles do not match any mapping pattern.
  • Users added through direct invitation (if no mapping override is specified).
info

We recommend setting the default role to Read-Only to follow the principle of least privilege. Users can then be upgraded to higher roles manually or through more specific mapping rules.

Role Mapping and Onboarding​

During the onboarding process, Guardian Pro discovers users in your AWS Organization and presents them for provisioning. When role mappings are configured, the suggested Guardian Pro role for each discovered user is automatically populated based on the mapping rules.

You can review and override these suggestions before completing user provisioning.

Testing a Mapping​

To verify how your mapping rules will evaluate a specific IAM role:

  1. On the Role Mappings page, use the Test Mapping tool.
  2. Enter an IAM role name or ARN.
  3. Guardian Pro shows which mapping rule would match and what Guardian Pro role would be assigned.

This is useful for validating your configuration before onboarding new users.

Audit Trail​

All role mapping changes -- creation, modification, and deletion -- are recorded in the audit trail. This includes who made the change and when, supporting your compliance and change management requirements.

Next Steps​