Update CloudFormation service role and documentation

Author: mbellaga

iam-roles/cloudformation-management/README.md

@@ -1,32 +1,45 @@
-# Secure All-Patterns Deployer Role for GenAI IDP Accelerator
+# CloudFormation Service Role for GenAI IDP Accelerator
 
-This directory contains the `all-patterns-deployer-role-secure.yaml` CloudFormation template that creates a secure IAM role for deploying, managing and modifying all GenAI IDP Accelerator patterns deployments.
+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.
 
 ## What This Role Does
 
-The **AllPatternsDeployerRole** provides comprehensive permissions to deploy, update, and manage GenAI IDP Accelerator CloudFormation stacks across all patterns (Pattern 1: BDA, Pattern 2: Textract+Bedrock, Pattern 3: Textract+UDOP+Bedrock).
+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.
 
 ### Key Capabilities
-- **Full CloudFormation Management**: Create, update, delete IDP stacks
+- **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).
 - **All Pattern Support**: Works with Pattern 1 (BDA), Pattern 2 (Textract+Bedrock), and Pattern 3 (UDOP)
 - **Comprehensive AWS Service Access**: All services required by IDP Accelerator
 
 
 ## Security Features
 
 ### Region Restrictions
-- **Deployment Regions**: Limited to `us-east-1` and `us-west-2` only
-- **Cross-Region Prevention**: Denies all actions outside approved regions
-- **Same-Region Assumption**: Role can only be assumed in the region where it's deployed
+- **Same-Region Operations**: Only allows the role to be assumed in the region where the master/existing deployment stack already exists
+- **Cross-Region Prevention**: Denies all actions outside the deployment region
+- **Regional Isolation**: Ensures all operations remain within the same region as the existing IDP infrastructure
 
 ### Session Management
 - **Session Duration**: Maximum 1 hour (3600 seconds)
 - **Forced Re-authentication**: Requires frequent credential refresh
+- **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:
+
+  ```json
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Action": "iam:PassRole",
+        "Resource": "arn:aws:iam::*:role/IDP-AllPatterns-Deployer-Secure"
+      }
+    ]
+  }
+  ```
 
 ### Access Control
 - **Account-Scoped**: Only IAM entities within the same AWS account can assume the role
-- **Permission-Based**: roles/users need individual `sts:AssumeRole` permissions
-- **CloudFormation Service**: AWS CloudFormation service can also assume the role
+
 
 ## Files in this Directory
 
@@ -36,43 +49,27 @@ The **AllPatternsDeployerRole** provides comprehensive permissions to deploy, up
 
 ## Parameters
 
-- **MasterStackName**: Name of the master GenAI IDP stack (used in role naming)
-- Must follow CloudFormation stack naming pattern: `^[a-zA-Z][a-zA-Z0-9-]*$`
+- **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.
+- Must follow CloudFormation stack naming pattern: `^[Ii][Dd][Pp][a-zA-Z0-9-]*$`
 
 ## Quick Start
 
 1. **Deploy the IAM Role** *(Administrator Required)*:
    ```bash
    aws cloudformation deploy \
-     --template-file all-patterns-deployer-role-secure.yaml \
+     --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)
      --stack-name idp-deployer-role \
-     --parameter-overrides MasterStackName=my-idp-project \
+     --parameter-overrides ExistingIDPStackName=my-existing-idp-stack \ (the name of your existing IDP stack)
      --capabilities CAPABILITY_NAMED_IAM
    ```
 
-2. **Grant Assumption Permissions** (to your user/role) *(Administrator Required)* :
-   ```bash
-   # Add this policy to your user/role
-   {
-     "Effect": "Allow",
-     "Action": "sts:AssumeRole",
-     "Resource": "arn:aws:iam::ACCOUNT:role/my-idp-project-AllPatterns-Deployer-Secure"
-   }
-   ```
-
-3. **Assume the Role**:
-   ```bash
-   aws sts assume-role \
-     --role-arn arn:aws:iam::123456789012:role/my-idp-project-AllPatterns-Deployer-Secure \
-     --role-session-name idp-deployment
-   ```
-
-4. **Deploy IDP Accelerator**:
+2. **Deploy IDP Accelerator**:
    ```bash
-   # Export the assumed role credentials first, then:
    aws cloudformation deploy \
-     --template-file ../../template.yaml \
-     --stack-name my-idp-stack \
+     --template-file ../../template.yaml \ (path to your template.yaml file)
+     --stack-name my-idp-stack \ (Name of your stack, starting with prefix IDP or idp)
+     --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)
+     --region us-east-1 \ (your selected region)
      --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
    ```
 
@@ -138,10 +135,11 @@ The role provides comprehensive access to AWS services required by all IDP patte
 
 ### Common Issues
 
-1. **Access Denied when Assuming Role**:
-   - Verify your user/role has `sts:AssumeRole` permission for this specific role ARN
+1. **Access Denied when Using Role**:
+   - Verify your user/role has `iam:PassRole` permission for this specific role ARN
    - Check you're in the correct AWS region (must match role deployment region)
    - Ensure the role exists and is in the same account
+   - Remember: Users cannot assume this role directly - only CloudFormation service can
 
 2. **Region Restriction Errors**:
    - All operations must be in `us-east-1` or `us-west-2`
@@ -157,12 +155,7 @@ The role provides comprehensive access to AWS services required by all IDP patte
    - Ensure you're using `CAPABILITY_IAM` and `CAPABILITY_NAMED_IAM`
    - Check CloudWatch logs for specific service errors
 
-### Getting Help
 
-For additional support:
-1. Review the `testing-guide.md` for validation procedures
-2. Check the main IDP Accelerator documentation
-3. Consult AWS IAM best practices documentation
 
 ## Best Practices
 

iam-roles/cloudformation-management/all-patterns-deployer-role-secure.yaml

@@ -1,45 +1,56 @@
 AWSTemplateFormatVersion: '2010-09-09'
-Description: 'Least Privileges Secure IAM role for deploying GenAI IDP patterns'
+Description: >
+  This template creates a dedicated IAM Service Role for CloudFormation.
+  This role grants permissions to create, update, and delete CloudFormation
+  stacks and their resources. It follows the principle of least privilege
+  by allowing only the necessary actions for stack management.
+  This role requires an existing master/IDP stack to be already deployed
+  as it only operates on stacks with the IDP prefix.
 
 Parameters:
-  MasterStackName:
+  ExistingIDPStackName:
     Type: String
-    Description: Name of the master GenAI IDP stack
-    Default: 'IDP'
-    AllowedPattern: '^[a-zA-Z][a-zA-Z0-9-]*$'
-    ConstraintDescription: Must be a valid CloudFormation stack name
+    Description: 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.
+    AllowedPattern: '^[Ii][Dd][Pp][a-zA-Z0-9-]*$'
+    ConstraintDescription: Must be an existing stack name starting with IDP or idp
 
 Resources:
   AllPatternsDeployerRole:
     Type: AWS::IAM::Role
     Properties:
-      RoleName: !Sub '${MasterStackName}-AllPatterns-Deployer-Secure'
+      RoleName: 'All-Patterns-Deployer-Role-Secure'
       Description: 'Minimal secure role for deploying all GenAI IDP patterns'
       MaxSessionDuration: 3600
       AssumeRolePolicyDocument:
         Version: '2012-10-17'
         Statement:
-          - Effect: Allow
-            Principal:
-              AWS: !Sub 'arn:aws:iam::${AWS::AccountId}:root'
-            Action: 'sts:AssumeRole'
-            Condition:
-              StringEquals:
-                'aws:RequestedRegion': !Ref 'AWS::Region'
           - Effect: Allow
             Principal:
               Service: 'cloudformation.amazonaws.com'
             Action: 'sts:AssumeRole'
-      ManagedPolicyArns:
-        - 'arn:aws:iam::aws:policy/ReadOnlyAccess'
       Policies:
-        - PolicyName: CorePermissions
+        - PolicyName: CloudFormationPermissions
           PolicyDocument:
             Version: '2012-10-17'
             Statement:
               - Effect: Allow
                 Action:
                   - 'cloudformation:*'
+                Resource: !Sub 'arn:aws:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/*/*'
+                Condition:
+                  StringLike:
+                    'cloudformation:StackName': 
+                      - !Sub '${ExistingIDPStackName}*'
+                      - 'IDP*'
+                      - 'idp*'
+              - Effect: Allow
+                Action:
+                  - 'cloudformation:CreateChangeSet'
+                Resource: 
+                  - 'arn:aws:cloudformation:*:aws:transform/Serverless-2016-10-31'
+                  - 'arn:aws:cloudformation:*:aws:transform/Serverless-2016-10-31-*'
+              - Effect: Allow
+                Action:
                   - 'iam:GetRole'
                   - 'iam:GetRolePolicy'
                   - 'iam:ListRolePolicies'
@@ -54,7 +65,6 @@ Resources:
                   - 'iam:UpdateRoleDescription'
                   - 'iam:UpdateAssumeRolePolicy'
                   - 'iam:TagRole'
-                  - 'iam:PassRole'
                   - 'iam:CreateServiceLinkedRole'
                   - 'lambda:*'
                   - 'kms:*'
@@ -76,9 +86,7 @@ Resources:
                 Resource: '*'
                 Condition:
                   StringNotEquals:
-                    'aws:RequestedRegion':
-                      - 'us-east-1'
-                      - 'us-west-2'
+                    'aws:RequestedRegion': !Ref 'AWS::Region'
         - PolicyName: ServicesPermissions
           PolicyDocument:
             Version: '2012-10-17'
@@ -89,6 +97,7 @@ Resources:
                   - 'textract:*'
                   - 'sagemaker:*'
                   - 'states:*'
+                  - 'apigateway:*'
                   - 'appsync:*'
                   - 'cognito-idp:*'
                   - 'cognito-identity:*'
@@ -126,6 +135,6 @@ Resources:
 
 
 Outputs:
-  AllPatternsDeployerRoleArn:
-    Description: ARN of the secure all-patterns deployer role
+  AllPatternsDeployerRoleSecureArn:
+    Description: ARN of the All-Patterns-Deployer-Role-Secure
     Value: !GetAtt AllPatternsDeployerRole.Arn