How to enforce creation of roles in a specific path

May 20, 2024: This blog post has been updated with use case examples.

The Optimize AWS administration with IAM paths blog post delves into the fundamental workings of the AWS Identity and Access Management (IAM) path feature. This post explores how you can use IAM paths to strike a balance between centralized IT and development teams. Centralized IT teams, including those that handle identity and access management, security, and networking, are responsible for maintaining strict governance over critical infrastructure, data, and resources, due to their sensitive nature. Historically, many organizations have centralized access management for developers under central IT teams. However, imposing a top-down, rigid governance approach can hinder business agility and impede the productivity of development teams. Central IT teams can have trouble keeping up with the fast pace of innovation in the cloud, often becoming a bottleneck. In this post, we propose an approach that better fosters agility, by promoting centralized governance while allowing decentralized access management that is aligned with the requirements of individual teams.

The IAM role path feature strikes a balance between centralized control and delegated access management for development teams. Central IT teams can be allocated dedicated paths (for example, /iam/, /security/, /network/) to manage identities and permissions within their respective domains. You can implement strict guardrails for these paths by using service control policies (SCPs), IAM policies, and permissions boundaries, with automated pipelines. Concurrently, development teams can be empowered by assigning them dedicated paths (for example, /devteam/, /product/) to self-service access and customize policies that are tailored to their workflows.

Solution overview

In this blog post, we cover working examples of how you can use IAM paths to enable the following two use cases:

Securing sensitive roles for centralized teams – You can use IAM role paths to create and isolate privileged team roles intended for your security, compliance, and infrastructure teams. By defining IAM paths for the sensitive teams’ roles, you can restrict access and enable granular permissions for your most critical AWS resources. This enhances security posture by separating duties.
Enabling self-service role creation for developers – By designating a separate path for development teams along with permissions boundaries, you empower your development teams to create and manage their own IAM roles as needed. This path acts as a separation for developers to provision roles independently while staying within security boundaries. Setting boundaries on developer privileges promotes agility and accountability in role management.

Figure 1: Sample architecture

The IAM role paths shown in Figure 1 illustrate how you can use role paths to separate roles for a centralized IT team and development team. By defining separate role paths, you can implement security controls at varying levels to achieve granular management of permissions. For example, the /iam/ path consolidates privileged roles, like Centralized IT team IAM administrator, that need tight governance. Meanwhile, the /D1/ path delegates customized access for developer and tester roles across the development team.

This approach offers several other advantages, including the following:

Reduced SCP maintenance – By basing SCPs on IAM paths instead of individual IAM roles, centralized IT teams can minimize the need for SCP modifications, saving time and resources.
Scalability and auditing – As the organization grows, you can accommodate new teams by assigning them dedicated IAM paths, helping to create a scalable and manageable IAM architecture. Additionally, the use of IAM paths facilitates auditing by providing a clear separation of roles and permissions based on IAM paths.

Secure sensitive roles for centralized teams

Let’s walk through how you can create the centralized IT team roles in a predefined IAM path, and look at some examples of preventative and detective controls that you can implement based on the paths.

You can create an IAM administrator role called IAMAdmin for centralized IT teams by using the AWS CLI create-role command, and you can attach a policy document by using the AWS CLI put-role-policy command.

You can also use an AWS CloudFormation template and the IAM API to create an IAM role with a path.

Here are example AWS CLI commands:

aws iam create-role --role-name IAMAdmin --path /iam/ --assume-role-policy-document file://assume.json (where assume.json is the trust policy JSON document)
aws iam put-role-policy --role-name IAMAdmin --policy-name IAMAdminpolicy --policy-document file://policy.json (where policy.json is the IAM policy for the IAM Administrator)

This is what an IAM role path looks like as an Amazon Resource Name (ARN) for the IAMAdmin role:

arn:aws:iam::123456789012:role/iam/IAMAdmin

These commands create an IAMAdmin role for centralized IT admin functions under the /iam/ path.

Preventative controls for sensitive paths for central IT teams

To make sure that the new /iam/ role path can only be access by the central IAM team, you can use an SCP. Here is a walkthrough of the SCP that you can set up.

The following SCP limits IAM actions in central IT team paths such as /iam/, /network/, and /security/:
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DenyIAMActionsforNonCentralteamRoles",
            "Effect": "Deny",
            "Action": [
                "iam:AttachRolePolicy",
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:DeleteRolePermissionsBoundary",
                "iam:DeleteRolePolicy",
                "iam:DetachRolePolicy",
                "iam:PutRolePermissionsBoundary",
                "iam:PutRolePolicy",
                "iam:UpdateRole",
                "iam:UpdateAssumeRolePolicy",
                "iam:UpdateRoleDescription",
                "iam:TagRole",
                "iam:UntagRole"
            ],
            "Resource": ["arn:aws:iam::*:role/network/*","arn:aws:iam::*:role/security/*",
                                   "arn:aws:iam::*:role/iam/*"],
            "Condition": {
                "ArnNotLike": {
                    "aws:PrincipalArn": ["arn:aws:iam::*:role/iam/*"]
               }
            }
        }
    ]
}
```
With just one statement in the SCP, this preventative control helps provide protection to your high-privilege roles for central IT team roles, regardless of the role’s name. We recommend that you also protect iam:PassRole and sts:AssumeRole for high-privilege roles in sensitive paths.

This example uses the following paths:
- /network/ – Centralized IT team roles for managing the core network infrastructure across the organization.
- /security/ – Centralized IT team roles for managing the core security operations across the organization.
- /iam/ – Centralized IT team roles that are allowed to perform IAM actions, such as CreateRole, AttachPolicy, or DeleteRole for centralized IT teams. Typically these roles have IAM administration capabilities.
If a developer team with IAM permissions to iam:CreateRole in the /D1/ path tries to create an IAM role in the /iam/ path, they will receive an AccessDenied error due to the provided SCP. Here’s an example of the error snippet:
```
Username,eventTime,eventSource,eventName,sourceIPAddress,errorCode,errorMessage
"User: arn:aws:sts::123456789012:assumed-role/D1/iamadmin is not authorized to perform: iam:CreateRole on resource: arn:aws:iam::123456789012:role/iam/NewRole with an explicit deny in a service control policy"
```
Also, if the centralized IT team IAM admins add a new role in the /iam/ path, they don’t need to update the SCP to protect the newly created IAM role. This is because the SCP is applied to the /iam/ path, so roles created within that path will automatically be protected by the SCP. By using path-based resource patterns in the SCP, rather than specifying individual role ARNs, the centralized IT team can streamline the administration process and make sure that the roles within the designated path are consistently governed by the SCP, without the need for manual updates or modifications to the SCP itself. This approach saves valuable administrative time and effort, while maintaining a consistent and scalable security posture across the organization’s IAM roles.

The following SCP restricts access to sensitive data buckets owned by centralized IT teams, such as a centralized AWS CloudTrail bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RestrictAccessPolicy",
      "Effect": "Deny",
      "Action": "s3:*",
      "Resource": ["arn:aws:s3:::sensitivedatabucket","arn:aws:s3:::sensitivedatabucket/*"],
      "Condition": {
        "ArnNotLike": {
          "aws:PrincipalArn": ["arn:aws:iam::123456789012:role/security/*"]
        }
      }
    }
  ]}

This example uses the following path:

/security/ – Centralized IT team roles for managing the core security operations across the organization.

If a developer team with IAM permissions to S3:* in the /D1/ path tries to access sensitivedatabucket, they will receive an AccessDenied error due to the provided SCP. Here’s an example of the error snippet:

Username,eventTime,eventSource,eventName,sourceIPAddress,errorCode,errorMessage
"User: arn:aws:sts::123456789012:assumed-role/D1/developer is not authorized to perform: s3:GetObject on resource: arn:aws:s3:::sensitivedatabucket/sensitive-data.txt with an explicit deny in a service control policy"

Detective controls for sensitive paths for centralized IT teams

Now we’ll walk through some of the detective controls that you can enable on the sensitive paths for central IT teams.

The following AWS CloudTrail Lake query can be used to monitor CreateRole API actions:

SELECT
    userIdentity.arn as "Username", eventTime, eventSource, eventName, sourceIPAddress, errorCode, errorMessage
FROM
    <Event data store ID>
WHERE
    userIdentity.arn IS NOT NULL
    AND eventName = 'CreateRole'
    AND userIdentity.arn LIKE '%/iam/%'
    AND eventTime > '2023-07-01 14:00:00'
    AND eventTime < '2023-11-08 18:00:00';

This query lists out CreateRole events for roles in the /iam/ path. Following are some example outputs:

Username,eventTime,eventSource,eventName,sourceIPAddress,errorCode,errorMessage
		
"User: arn:aws:sts::123456789012:assumed-role/D1/iamadmin is not authorized to perform: iam:CreateRole on resource: arn:aws:iam::123456789012:role/iam/IAMAdmTest with an explicit deny in a service control policy

To receive alerts on activities inside a sensitive IAM path, such as /iam/, you can use an Amazon EventBridge rule as a detective control to send an email notification using an SNS topic when an IAM role is created in the /iam/ path. Following is an example rule:

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "CloudFormation template for EventBridge rule 'EnterpriseRoleCreationNotification'",
  "Resources": {
    "EventRule0": {
      "Type": "AWS::Events::Rule",
      "Properties": {
        "EventBusName": "default",
        "EventPattern": {
          "source": ["aws.iam"],
          "detail-type": ["AWS API Call via CloudTrail"],
          "detail": {
            "eventSource": ["iam.amazonaws.com"],
            "eventName": ["CreateRole"],
            "requestParameters": {
              "path": [{"wildcard": "*/iam/*"}]
               }
            }
          }
        },
        "Name": "EnterpriseRoleCreationNotification",
        "State": "ENABLED",
        "Targets": [{
          "Id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
          "Arn": "<ARN of your SNS Topic>"
        }]
      }
    }
  }
}

Using an IAM path for centralized IT team roles has the following tradeoffs:

Benefits	Key considerations
By creating high-privilege roles in IAM paths, you can enable broader security controls at the path level The IAM path conveys the contextual purpose of the role	Complex paths could be hard to maintain Roles paths are immutable The role name can’t be same even on separate IAM paths—in other words, migration to this approach would entail the creation of new roles with a different name

Enable safe delegation of IAM role creation for development teams

To enable development teams to create roles in their own paths, let’s walk through how you can create the developer team roles in a predefined path.

Following is an example IAM policy created for development team D1, called D1-IAM-Admin, created by the IAMAdmin role. The D1-IAM-Admin role can be used by development team D1 to self-service their IAM needs.

Example IAM policy for the D1-IAM-Admin role

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Condition": {
                "StringEquals": {
                    "iam:PermissionsBoundary": ["arn:aws:iam::987456123000:policy/permissionsboundaries/PermissionsboundaryA"]
                }
            },
            "Action": [
                "iam:CreateRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:PutRolePolicy",
                "iam:DeleteRolePolicy",
                "iam:DeleteRole"
            ],
            "Resource": "arn:aws:iam::987456123000:role/D1/*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "iam:CreatePolicy",
                "iam:CreatePolicyVersion",
                "iam:DeletePolicyVersion"
            ],
            "Resource": "arn:aws:iam::987456123000:policy/D1/*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "iam:GetRole",
                "iam:ListRoles"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "iam:CreateInstanceProfile",
                "iam:AddRoleToInstanceProfile",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:DeleteInstanceProfile"
            ],
            "Resource": [
                "arn:aws:iam::987456123000:role/D1/*",
                "arn:aws:iam::987456123000:instance-profile/D1/instanceprofiles/*"
            ],
            "Effect": "Allow"
        },
        {
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::987456123000:role/D1/*",
            "Effect": "Allow"
        }
    ]
}

These permissions allow D1-IAM-Admin to create additional IAM roles in the /D1/ IAM path while mandating the use of a permissions boundary during the process.

When a developer tries to create a role by using D1-IAM-Admin outside of the /D1/ path, for example in the /iam/ path, the developer gets the following error:

Username,eventTime,eventSource,eventName,sourceIPAddress,errorCode,errorMessage
"User: arn:aws:sts::987456123000:assumed-role/D1/IAMAdmin is not authorized to perform: iam:CreateRole on resource: arn:aws:iam::987456123000:role/iam/CreateRoleTest because no identity-based policy allows the iam:CreateRole action (Service: Iam, Status Code: 403, Request ID: b81c39ba-dae8-4d74-9202-136b0c86a37b)"

When a developer tries to create a role by using D1-IAM-Admin in the /D1/ path, the developer is able to create the role:

"responseElements": {"role": {"path": "/D1/","roleName": 
"CreateRoleTesting","roleId": "AROAT6MRMMOYDOD6K5PXK","arn": 
"arn:aws:iam::987456123000:role/D1/CreateRoleTest",           
"createDate": "Apr 3, 2024 5:41:31 PM"}}

Both central IT teams and development teams can use CloudTrail queries to audit and set up EventBridge alarms for their respective paths. An example CloudTrail query and EventBridge rule are provided above for the /iam/ path.

Important considerations

When you implement specific paths for IAM roles, make sure to consider the following:

Avoid using specific business unit names or other names that are subject to change as the organization structure shifts.
Keep role paths relatively flat. Complex nested role paths become difficult to visualize and manage over time.
Use a consistent naming convention and structure for all roles across all accounts. For example, /security/, /networking/.
The path of an IAM role is part of the ARN. After you define the ARN, you can’t change it later. Therefore, just like the name of the role, consider what the path should be during the early discussions of design.
IAM roles can’t have the same name, even on different paths.
When you switch roles through the console, you need to include the path because it’s part of the role’s ARN.
The path of an IAM role can’t exceed 512 characters. For more information, see IAM and AWS STS quotas.
The role name can’t exceed 64 characters. If you intend to use a role with the Switch Role feature in the AWS Management Console, then the combined path and role name can’t exceed 64 characters.
The AWS console does not support the creation of IAM role paths. To set a path for the role, you need to use automation, such as AWS CLI commands or SDKs. For example, you might use an AWS CloudFormation template or a script that interacts with AWS APIs to create the role with the desired path.

Conclusion

By adopting IAM paths, you can implement security controls that scale with the growth of your organization. You can make these controls effective for IAM roles by applying them to a path rather than specific roles, thus minimizing policy updates as the environment changes. Well-crafted paths can reduce operational overhead by providing a structured framework that makes it simpler to add or modify roles and policies. This scalability can help streamline the administration of IAM and elevate your overall security posture within IAM.

If you have feedback about this post, submit comments in the Comments section below. If you have questions about this post, contact AWS Support.

Want more AWS Security news? Follow us on Twitter.

AWS Security Blog