Skip to content

Commit 42957d7

Browse files
mbellagambellaga
committed
Add CloudFormation service role template and documentation
- Add IDP-Cloudformation-Service-Role.yaml: CloudFormation service role template - Add README.md: Complete documentation with deployment instructions - Add testing-guide.md: Testing procedures and validation steps
1 parent b55fc6c commit 42957d7

File tree

3 files changed

+283
-372
lines changed

3 files changed

+283
-372
lines changed

‎iam-roles/cloudformation-management/IDP-Cloudformation-Service-Role.yaml‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
AWSTemplateFormatVersion: '2010-09-09'
2+
Description: >
3+
This template creates a CloudFormation Service Role for the IDP Accelerator solution.
4+
This role grants permissions to create, update, and delete IDP CloudFormation
5+
stacks and their resources. It follows the principle of least privilege
6+
by allowing only the necessary actions for stack management. This template also
7+
creates a user permission policy that allows users to pass the CloudFormation
8+
service role to CloudFormation. The iam:PassRole policy must be attached to
9+
the user or role that will be using the CloudFormation Service Role in order
10+
to successfully pass the role.
11+
12+
Resources:
13+
CloudFormationServiceRole:
14+
Type: AWS::IAM::Role
15+
Properties:
16+
RoleName: IDPAcceleratorCloudFormationServiceRole
17+
AssumeRolePolicyDocument:
18+
Version: '2012-10-17'
19+
Statement:
20+
- Effect: Allow
21+
Principal:
22+
Service: !Sub 'cloudformation.${AWS::URLSuffix}'
23+
Action: sts:AssumeRole
24+
Policies:
25+
- PolicyName: CloudFormationPermissions
26+
PolicyDocument:
27+
Version: '2012-10-17'
28+
Statement:
29+
- Effect: Allow
30+
Action:
31+
- cloudformation:*
32+
Resource: '*'
33+
- Effect: Allow
34+
Action:
35+
- iam:CreateRole
36+
- iam:DeleteRole
37+
- iam:UpdateRole
38+
- iam:GetRole
39+
- iam:ListRoles
40+
- iam:CreatePolicy
41+
- iam:DeletePolicy
42+
- iam:GetPolicy
43+
- iam:ListPolicies
44+
- iam:AttachRolePolicy
45+
- iam:DetachRolePolicy
46+
- iam:PutRolePolicy
47+
- iam:DeleteRolePolicy
48+
- iam:GetRolePolicy
49+
- iam:ListRolePolicies
50+
- iam:ListAttachedRolePolicies
51+
- iam:CreateServiceLinkedRole
52+
- iam:DeleteServiceLinkedRole
53+
- iam:TagRole
54+
- iam:UntagRole
55+
- iam:ListRoleTags
56+
- iam:PassRole
57+
Resource: '*'
58+
- PolicyName: IDPAcceleratorPermissions
59+
PolicyDocument:
60+
Version: '2012-10-17'
61+
Statement:
62+
- Effect: Allow
63+
Action:
64+
- lambda:*
65+
- kms:*
66+
- logs:*
67+
- cloudwatch:*
68+
- events:*
69+
- s3:*
70+
- dynamodb:*
71+
- bedrock:*
72+
- textract:*
73+
- sagemaker:*
74+
- states:*
75+
- apigateway:*
76+
- appsync:*
77+
- cognito-idp:*
78+
- cognito-identity:*
79+
- glue:*
80+
- aoss:*
81+
- cloudfront:*
82+
- wafv2:*
83+
- sns:*
84+
- sqs:*
85+
- ssm:*
86+
- secretsmanager:*
87+
- codebuild:*
88+
- application-autoscaling:*
89+
- scheduler:*
90+
- ec2:CreateVpc
91+
- ec2:DeleteVpc
92+
- ec2:DescribeVpcs
93+
- ec2:CreateSubnet
94+
- ec2:DeleteSubnet
95+
- ec2:DescribeSubnets
96+
- ec2:CreateSecurityGroup
97+
- ec2:DeleteSecurityGroup
98+
- ec2:DescribeSecurityGroups
99+
- ec2:AuthorizeSecurityGroupIngress
100+
- ec2:AuthorizeSecurityGroupEgress
101+
- ec2:RevokeSecurityGroupIngress
102+
- ec2:RevokeSecurityGroupEgress
103+
- ec2:CreateTags
104+
- ec2:DeleteTags
105+
- ec2:DescribeTags
106+
- ec2:DescribeAvailabilityZones
107+
Resource: '*'
108+
109+
PassRolePolicy:
110+
Type: AWS::IAM::ManagedPolicy
111+
Properties:
112+
ManagedPolicyName: IDP-PassRolePolicy
113+
Description: Policy to allow passing the IDP CloudFormation service role
114+
PolicyDocument:
115+
Version: '2012-10-17'
116+
Statement:
117+
- Effect: Allow
118+
Action:
119+
- iam:PassRole
120+
Resource: !GetAtt CloudFormationServiceRole.Arn
121+
122+
Outputs:
123+
ServiceRoleArn:
124+
Description: ARN of the CloudFormation service role
125+
Value: !GetAtt CloudFormationServiceRole.Arn
126+
Export:
127+
Name: !Sub '${AWS::StackName}-ServiceRoleArn'
128+
PassRolePolicyArn:
129+
Description: ARN of the PassRole policy for admins to assign to users
130+
Value: !Ref PassRolePolicy
131+
Export:
132+
Name: !Sub '${AWS::StackName}-PassRolePolicyArn'

‎iam-roles/cloudformation-management/README.md‎

Lines changed: 77 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,98 @@
11
# CloudFormation Service Role for GenAI IDP Accelerator
22

3-
This directory contains the `all-patterns-deployer-role-secure.yaml` CloudFormation template that creates a dedicated IAM service role for CloudFormation to deploy, manage and modify all GenAI IDP Accelerator patterns deployments.
3+
This directory contains the `IDP-Cloudformation-Service-Role.yaml` CloudFormation template that creates a dedicated IAM Cloudformation service role for CloudFormation to deploy, manage and modify all GenAI IDP Accelerator patterns deployments.
44

5-
## What This Role Does
5+
## <span style="color: blue;">What This Role Does</span>
66

7-
The **AllPatternsDeployerRole** is a CloudFormation service role that provides the necessary permissions for AWS CloudFormation to deploy, update, and manage GenAI IDP Accelerator stacks across all patterns (Pattern 1: BDA, Pattern 2: Textract+Bedrock, Pattern 3: Textract+UDOP+Bedrock). This role can only be assumed by the CloudFormation service, not by users directly.
7+
The **IDPAcceleratorCloudFormationServiceRole** is a CloudFormation service role that provides the necessary permissions for AWS CloudFormation to deploy, update, and manage GenAI IDP Accelerator stacks across all patterns (Pattern 1: BDA, Pattern 2: Textract+Bedrock, Pattern 3: Textract+UDOP+Bedrock). This role can only be assumed by the CloudFormation service, not by users directly.
88

99
### Key Capabilities
10-
- **Full CloudFormation Management**: Create, update, delete IDP stacks - This IAM role (which CloudFormation assumes) gives necessary privileges to create/update/delete the stack which is helpful in development and sandbox environments. In production environments, admins can further limit these permissions to their discretion (e.g. disabling stack deletion).
10+
- **Full CloudFormation Management**: Create, update, delete IDP stacks - This IAM service role (which CloudFormation assumes) gives necessary privileges to create/update/delete the stack which is helpful in development and sandbox environments. In production environments, admins can further limit these permissions to their discretion (e.g. disabling stack deletion).
11+
1112
- **All Pattern Support**: Works with Pattern 1 (BDA), Pattern 2 (Textract+Bedrock), and Pattern 3 (UDOP)
12-
- **Comprehensive AWS Service Access**: All services required by IDP Accelerator
1313

14+
- **Comprehensive AWS Service Access**: Supports all services required by IDP Accelerator
1415

15-
## Security Features
1616

17-
### Region Restrictions
18-
- **Same-Region Operations**: Only allows the role to be assumed in the region where the master/existing deployment stack already exists
19-
- **Cross-Region Prevention**: Denies all actions outside the deployment region
20-
- **Regional Isolation**: Ensures all operations remain within the same region as the existing IDP infrastructure
17+
## <span style="color: blue;">Security Features</span>
2118

2219
### Session Management
23-
- **Session Duration**: Maximum 1 hour (3600 seconds)
24-
- **Forced Re-authentication**: Requires frequent credential refresh
25-
- **Administrator Note**: Administrators must add an inline IAM policy to users wanting to deploy CloudFormation stacks with this service role, allowing them to pass the `IDP-AllPatterns-Deployer-Secure` role to the CloudFormation principal:
26-
27-
```json
28-
{
29-
"Version": "2012-10-17",
30-
"Statement": [
31-
{
32-
"Effect": "Allow",
33-
"Action": "iam:PassRole",
34-
"Resource": "arn:aws:iam::*:role/IDP-AllPatterns-Deployer-Secure"
35-
}
36-
]
37-
}
20+
- **Administrator Note**: This role also creates an IAM Managed Policy to allow passing the Cloudformation service role. Administrators must add the inline IAM policy to users wanting to deploy or modify CloudFormation IDP stacks with this service role, allowing them to pass the `IDPAcceleratorCloudFormationServiceRole` role to the CloudFormation principal:
21+
22+
```yaml
23+
PassRolePolicy:
24+
Type: AWS::IAM::ManagedPolicy
25+
Properties:
26+
ManagedPolicyName: IDP-PassRolePolicy
27+
Description: Policy to allow passing the IDP CloudFormation service role
28+
PolicyDocument:
29+
Version: '2012-10-17'
30+
Statement:
31+
- Effect: Allow
32+
Action:
33+
- iam:PassRole
34+
Resource: !GetAtt CloudFormationServiceRole.Arn
3835
```
3936
4037
### Access Control
4138
- **Account-Scoped**: Only IAM entities within the same AWS account can assume the role
4239
4340
44-
## Files in this Directory
41+
## <span style="color: blue;">Files in this Directory</span>
4542
46-
- `all-patterns-deployer-role-secure.yaml` - CloudFormation template for the secure IAM role
43+
- `IDP-Cloudformation-Service-Role.yaml` - CloudFormation service role template
4744
- `README.md` - This documentation file
4845
- `testing-guide.md` - Testing procedures and validation steps
4946

50-
## Parameters
47+
## <span style="color: blue;">Console Deployment Steps</span>
48+
49+
### Prerequisites
50+
- AWS Administrator access or IAM permissions to create roles and policies
51+
52+
### Step-by-Step Deployment
53+
54+
1. **Navigate to CloudFormation Console**
55+
- Open the AWS Management Console
56+
- Go to **CloudFormation** service
57+
- Select your preferred region
58+
59+
2. **Create New Stack**
60+
- Click **"Create stack"** → **"With new resources (standard)"**
5161

52-
- **ExistingIDPStackName**: Name of an existing IDP stack (must start with IDP or idp). It is assumed that the administrator has deployed the first IDP solution deployment.
53-
- Must follow CloudFormation stack naming pattern: `^[Ii][Dd][Pp][a-zA-Z0-9-]*$`
62+
3. **Specify Template**
63+
- Select **"Upload a template file"**
64+
- Click **"Choose file"** and select `IDP-Cloudformation-Service-Role.yaml`
65+
- Click **"Next"**
5466

55-
## Quick Start
67+
4. **Stack Details**
68+
- **Stack name**: Enter your stack a name
69+
- **Parameters**: No parameters required
70+
- Click **"Next"**
5671

57-
1. **Deploy the IAM Role** *(Administrator Required)*:
58-
```bash
59-
aws cloudformation deploy \
60-
--template-file all-patterns-deployer-role-secure.yaml \ # (Note: Ensure the template file is in your current directory or provide the full path to your template file location)
61-
--stack-name idp-deployer-role \
62-
--parameter-overrides ExistingIDPStackName=my-existing-idp-stack \ (the name of your existing IDP stack)
63-
--capabilities CAPABILITY_NAMED_IAM
64-
```
72+
5. **Configure Stack Options**
73+
- **Tags** (optional): Add any desired tags
74+
- **Permissions**: Leave as default
75+
- **Stack failure options**: Leave as default
76+
- Click **"Next"**
6577

66-
2. **Deploy IDP Accelerator**:
67-
```bash
68-
aws cloudformation deploy \
69-
--template-file ../../template.yaml \ (path to your template.yaml file)
70-
--stack-name my-idp-stack \ (Name of your stack, starting with prefix IDP or idp)
71-
--role-arn arn:aws:iam::123456789012:role/All-Patterns-Deployer-Role-Secure \ (The ARN of the idp-deployer-role provided in the Output tab of the deployed role stack)
72-
--region us-east-1 \ (your selected region)
73-
--capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
74-
```
78+
6. **Review and Create**
79+
- Review all settings
80+
- **Capabilities**: Check **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"**
81+
- Click **"Submit"**
7582

76-
## AWS Service Permissions
83+
7. **Monitor Deployment**
84+
- Wait for stack status to show **"CREATE_COMPLETE"**
85+
- Check the **Events** tab for any issues
86+
87+
8. **Retrieve Role ARN**
88+
- Go to the **Outputs** tab
89+
- Copy the **CloudFormationServiceRoleArn** value for future use
90+
91+
### Post-Deployment
92+
- The role is now ready to be used with `--role-arn` parameter in CloudFormation deployments via CLI or as a "an existing AWS Identity and Access Management (IAM) service role that CloudFormation can assume" from the Permissions-Optional section in the Cloudformation Console.
93+
- Users will need `iam:PassRole` permission to use this role
94+
95+
## <span style="color: blue;">AWS Service Permissions</span>
7796

7897
The role provides comprehensive access to AWS services required by all IDP patterns:
7998

@@ -88,6 +107,7 @@ The role provides comprehensive access to AWS services required by all IDP patte
88107
- **EventBridge**: `events:*` - Event rule configuration
89108
- **KMS**: `kms:*` - Encryption key management
90109
- **CloudWatch**: `logs:*`, `cloudwatch:*` - Monitoring and logging
110+
- **Secrets Manager**: `secretsmanager:*` - Secure credential storage and retrieval
91111

92112
### AI/ML Services
93113
- **Amazon Bedrock**: `bedrock:*` - All foundation models and features
@@ -111,53 +131,46 @@ The role provides comprehensive access to AWS services required by all IDP patte
111131
- **EventBridge Scheduler**: `scheduler:*`
112132

113133
### Additional Permissions
114-
- **ReadOnlyAccess**: AWS managed policy for read operations
115134
- **STS**: `sts:AssumeRole` for service integrations
116135

117-
## Security Considerations
136+
## <span style="color: blue;">Security Considerations</span>
118137

119138
### Regional Restrictions
120-
- **Hard Limit**: All actions denied outside `us-east-1` and `us-west-2`
121139
- **Deployment Region**: Role assumption restricted to deployment region
122140
- **Compliance**: Helps meet data residency requirements
123141

124142
### Session Security
125-
- **Short Sessions**: 1-hour maximum reduces credential exposure
126-
- **Account Isolation**: Cannot be assumed cross-account
143+
- **Account Isolation**: Cannot be assumed cross-account with the current trust policy
127144

128145
### Permission Scope
129-
- **Broad Service Access**: Full service permissions for comprehensive IDP deployment
146+
- **Broad Service Access**: Full service permissions for comprehensive IDP deployment services
130147
- **No Resource Restrictions**: Allows flexibility but requires careful usage
131148
- **Service Trust**: CloudFormation service can assume role for stack operations
132149
- **Compliance Note**: Organizations may need to refine and make more granular the service action permissions based on their specific security compliance guidelines and least privilege requirements
133150

134-
## Troubleshooting
151+
## <span style="color: blue;">Troubleshooting</span>
135152

136153
### Common Issues
137154

138155
1. **Access Denied when Using Role**:
139156
- Verify your user/role has `iam:PassRole` permission for this specific role ARN
140-
- Check you're in the correct AWS region (must match role deployment region)
157+
141158
- Ensure the role exists and is in the same account
142159
- Remember: Users cannot assume this role directly - only CloudFormation service can
143160

144161
2. **Region Restriction Errors**:
145-
- All operations must be in `us-east-1` or `us-west-2`
146-
- Deploy the role in your target deployment region
147-
- Check AWS CLI region configuration
162+
- Role should be deployed in same region where IDP stacks are deployed
148163

149164
3. **Session Timeout**:
150-
- Sessions expire after 1 hour maximum
151165
- Re-assume the role to get fresh credentials
152-
- Consider automation for long-running deployments
153166

154167
4. **CloudFormation Deployment Failures**:
155-
- Ensure you're using `CAPABILITY_IAM` and `CAPABILITY_NAMED_IAM`
168+
- If using the CLI, ensure you're using `CAPABILITY_IAM` and `CAPABILITY_NAMED_IAM`
156169
- Check CloudWatch logs for specific service errors
157170

158171

159172

160-
## Best Practices
173+
## <span style="color: blue;">Best Practices</span>
161174

162175
1. **Regular Auditing**: Periodically review who has access to assume this role
163176
2. **Least Privilege**: Only grant this role to users who need to manage IDP stacks

0 commit comments

Comments
 (0)