Access Roles Reference

Documentation Index

Fetch the complete documentation index at: https://docs.quiverstone.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Access Role Types

​

Key Features

• Flexible Permissions: Choose from eight AWS managed policies (ReadOnly, Administrator, PowerUser, ViewOnly, SecurityAudit, SystemAdministrator, SupportUser, Billing)
• Multiple Deployment Methods: Deploy to individual accounts or across organizations using StackSets
• Security Controls: Support for External ID, specific principal trust, and role chaining
• Organization Inventory: All access roles include AWS Organizations read permissions for account discovery

​

Access Role Templates

​

Browser Access Role

• pRoleName (String, Default: QuiverstoneBrowserSession)
  • Name for the browser-accessible role
  • Must be unique within the account
  • Security Best Practice: Change the default role name to a custom value unique to your organization
• pTrustedAccountId (String, Required)
  • AWS Account ID you have access to that can assume this role via browser session
  • Must be a 12-digit account number
  • Important: Do NOT use any Quiverstone account IDs
• Permission Flags (yes/no for each):
  • pIsReadOnlyAccess (Default: yes): View resources across all AWS services
  • pIsAdministratorAccess (Default: no): Full access to all AWS services and resources
  • pIsPowerUserAccess (Default: no): Full access except IAM user/group management
  • pIsViewOnlyAccess (Default: no): View resources and basic metadata
  • pIsSecurityAudit (Default: no): View configuration data and logs
  • pIsSystemAdministrator (Default: no): Full access for application operations
  • pIsSupportUser (Default: no): Troubleshoot issues and manage AWS support cases
  • pIsBillingAccess (Default: no): View and manage billing and cost information

• oRoleArn: ARN of the created browser access role
• oRoleName: Name of the created role
• oTrustedAccountId: Account ID that can assume this role

• Does NOT support External ID authentication
• Trusts all principals in the specified trusted account
• Best for scenarios where you control both accounts
• Consider using direct or chained access for production environments requiring External ID

​

Direct Access Role

• pRoleName (String, Default: QuiverstoneDirectAccess)
  • Name for the federated access role
  • Must be unique within the account
  • Security Best Practice: Change the default role name to a custom value unique to your organization
• pQuiverstoneProductionAccountId (String, Default: 684035162433)
  • Quiverstone production account ID
  • DO NOT MODIFY this value
• pExternalId (String, Required for Production, Max: 1224 characters)
  • Security token for role assumption
  • Required for production environments — prevents confused deputy attacks
  • Generate a unique random string (minimum 32 characters)
  • Store securely — required when configuring Quiverstone
  • Never share or commit External IDs to version control
• Permission Flags (yes/no for each):
  • Same permission options as browser access role (see above)

• oRoleArn: ARN of the created direct access role
• oRoleExternalId: External ID for role assumption (if configured)
• oRoleName: Name of the created role

• Supports External ID for enhanced security (strongly recommended)
• Trusts only the Quiverstone production account
• Recommended for most production deployments
• External ID prevents confused deputy attacks

​

Chained Access Role

• pChainedAccessRoleName (String, Default: QuiverstoneChainedAccess, Required)
  • Name for the destination account access role
  • Must be unique within the account
  • Security Best Practice: Change the default role name to a custom value unique to your organization
• pExternalId (String, Required for Production, Max: 1224 characters)
  • External ID for role assumption
  • Can be different from intermediate role External ID
  • Required for production - use a different value than the intermediate role External ID
  • Generate a unique random string (minimum 32 characters)
  • Never share or commit External IDs to version control
• pIntermediateAccountId (String, Required)
  • AWS Account ID that serves as the intermediate hop
  • Must be a 12-digit account number
  • This is an account you own and have access to
• pTrustPrincipals (String, Default: All)
  • Controls which principals in intermediate account can assume this role
  • Options:
    • All: Trust all principals in the intermediate account
    • Named: Trust only the specific role named in pIntermediateRoleName
  • Recommended: Use Named for enhanced security
• pIntermediateRoleName (String, Default: QuiverstoneTrustedIntermediate)
  • Name of the role in the intermediate account
  • Required if pTrustPrincipals is set to Named
  • Populate for reference even if trusting entire account
  • Update this if you changed the intermediate role name
• pIntermediateRoleExternalId (String, Optional, Max: 1224 characters)
  • External ID for intermediate role assumption
  • Reference only - used when configuring Quiverstone
  • Should match the External ID configured on the intermediate role
• Permission Flags (yes/no for each):
  • Same permission options as browser access role (see above)

• oTargetRoleArn: ARN of the destination account access role
• oTargetRoleExternalId: External ID for target role assumption (if configured)
• oIntermediateRoleArn: ARN of the intermediate role (if name provided)
• oIntermediateRoleArnExcluded: Notice if intermediate role name not provided
• oIntermediateRoleExternalId: External ID for intermediate role (if configured)
• oTrustAllPrincipals: Notice if trusting all principals in intermediate account

• Requires intermediate role to be deployed first
• Provides additional security layer through role chaining
• Use Named trust for maximum security
• Both intermediate and destination roles can have separate External IDs
• Best for highly regulated environments or multi-organization scenarios

​

Browser Access Role StackSet

• pDeploymentOUs (CommaDelimitedList, Required)
  • Organization Unit IDs to deploy to (comma-separated)
  • Use root OU ID to deploy to all accounts
  • Example: ou-xxxx-yyyyyyyy,ou-xxxx-zzzzzzzz
• pDeploymentRegion (String, Default: us-east-1)
  • AWS Region to deploy the roles
  • Allowed values: us-east-1, us-east-2, us-west-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-southeast-2, ap-northeast-1
• All parameters from browser-access-role.yaml (see above)

• Permission Model: SERVICE_MANAGED (uses AWS Organizations integration)
• Auto Deployment: Enabled (automatically deploys to new accounts)
• Retain Stacks on Account Removal: Disabled (cleans up when accounts leave OUs)
• Concurrent Deployment: 100% (deploys to all accounts simultaneously)
• Failure Tolerance: 100% (continues deployment even if some accounts fail)

• oDeploymentOUs: List of OUs where roles are deployed
• oDeploymentRegion: Region where roles are deployed

​

Direct Access Role StackSet

• pDeploymentOUs (CommaDelimitedList, Required)
  • Organization Unit IDs to deploy to (comma-separated)
  • Use root OU ID to deploy to all accounts
• pDeploymentRegion (String, Default: us-east-1)
  • AWS Region to deploy the roles
  • Same allowed values as browser access StackSet
• All parameters from direct-access-role.yaml (see above)

• oDeploymentOUs: List of OUs where roles are deployed
• oDeploymentRegion: Region where roles are deployed

​

Chained Access Role StackSet

• pDeploymentOUs (CommaDelimitedList, Required)
  • Organization Unit IDs to deploy to (comma-separated)
  • Use root OU ID to deploy to all accounts
• pDeploymentRegion (String, Default: us-east-1)
  • AWS Region to deploy the roles
  • Same allowed values as other StackSets
• All parameters from chained-access-role.yaml (see above)

• oDeploymentOUs: List of OUs where roles are deployed
• oDeploymentRegion: Region where roles are deployed

​

Access Method Comparison

​

Browser-Based Access

• Interactive console operations requiring browser-based workflows
• Development and testing environments
• Scenarios where you’re already logged into an AWS account
• Quick access for troubleshooting and investigation
• Teams that prefer console-based workflows

• Simple setup with minimal configuration
• Familiar AWS console experience
• No additional authentication beyond your existing AWS login
• Easy role switching in the browser
• Good for ad-hoc access patterns

• Does NOT support External ID authentication
• Requires you to be logged into a trusted AWS account first
• Less suitable for automated or programmatic access
• Trusts all principals in the trusted account (broader trust scope)
• Not recommended for production environments requiring strict security controls

• Trust policy allows any principal in the trusted account to assume the role
• No External ID protection against confused deputy attacks
• Ensure the trusted account has appropriate access controls
• Consider using direct or chained access for production workloads
• Best suited for environments where you control both accounts

• You need interactive console access
• You’re already logged into an AWS account
• You’re working in development/test environments
• External ID is not a security requirement
• You control both the trusted and target accounts

​

Direct Access

• Standard production deployments
• Automated account access and management
• Organizations with straightforward security requirements
• Single AWS organization scenarios
• Most common deployment method for Quiverstone

• Simple architecture with direct trust relationship
• Supports External ID for enhanced security
• Suitable for both interactive and programmatic access
• Lower latency than chained access (one hop instead of two)
• Easier to troubleshoot than chained access
• Recommended for most production deployments

• Direct trust to Quiverstone production account
• No intermediate security layer
• May not meet requirements for highly regulated environments
• Cannot route through your own security controls

• External ID strongly recommended to prevent confused deputy attacks
• Trust policy specifically allows only Quiverstone production account
• External ID acts as a shared secret between you and Quiverstone
• Generate unique External IDs for each account or role
• Store External IDs securely (password manager, secrets manager)
• Rotate External IDs periodically according to your security policies

• You need standard production access
• External ID security is sufficient for your requirements
• You want the simplest production-ready deployment
• You don’t require an intermediate security layer
• You’re deploying in a single AWS organization

​

Chained Access

• Highly regulated environments requiring additional security controls
• Organizations with strict security policies
• Multi-organization deployments
• Scenarios requiring centralized access control
• Environments where direct trust to external accounts is prohibited
• Organizations wanting to audit all role assumptions through a central point

• Additional security layer through your controlled intermediate account
• Centralized access control and auditing
• Can implement custom security controls in intermediate account
• Supports separate External IDs for each hop
• Allows you to revoke Quiverstone access by modifying only the intermediate role
• Meets requirements for environments prohibiting direct external trust
• Can use specific role trust instead of account-level trust

• More complex setup requiring two role deployments
• Higher latency due to two-hop role assumption
• More components to manage and troubleshoot
• Requires maintaining intermediate role in addition to destination roles
• Slightly higher AWS API call costs (two AssumeRole calls per access)

• Intermediate role should use External ID for Quiverstone trust
• Destination roles can use External ID for intermediate account trust
• Use Named trust (specific role) instead of All (account-level) for maximum security
• Intermediate account becomes a critical security component - protect it accordingly
• Monitor intermediate role usage through CloudTrail
• Consider implementing additional controls in intermediate account (IP restrictions, time-based access, etc.)
• Both roles can have separate External IDs for defense in depth

• Your security policies require an intermediate security layer
• You need centralized access control and auditing
• You’re in a highly regulated environment
• You want to implement custom security controls
• You’re managing multiple AWS organizations
• Direct trust to external accounts is prohibited by policy
• You want the ability to quickly revoke access by modifying only one role

​

Access Method Decision Matrix

​

Deployment Type Comparison

​

Individual Account Deployment

• Small number of accounts (1-10)
• Accounts not in an AWS Organization
• Different configurations needed per account
• Testing and validation before organization-wide deployment
• Accounts requiring unique permission sets
• Standalone accounts or accounts in different organizations

1. Log into the target AWS account
2. Launch the CloudFormation template
3. Configure parameters specific to that account
4. Create the stack
5. Copy outputs for Quiverstone configuration
6. Repeat for each account

• Simple and straightforward process
• Full control over each deployment
• Easy to customize per account
• No AWS Organizations requirement
• Can deploy to accounts in different organizations
• Immediate feedback on deployment success/failure
• Easy to test and validate before wider deployment

• Manual process for each account
• Time-consuming for large numbers of accounts
• Potential for configuration drift between accounts
• No automatic deployment to new accounts
• Requires access to each individual account
• More operational overhead to maintain

• You have fewer than 10 accounts
• Accounts are not in an AWS Organization
• Each account needs different configurations
• You’re testing before organization-wide deployment
• You need maximum control over each deployment
• Accounts are in different organizations

​

StackSet Deployment

• Large number of accounts (10+)
• Organization-wide standardized deployments
• Automatic deployment to new accounts
• Consistent configuration across all accounts
• Centralized management and updates
• Organizations with mature AWS Organizations structure

1. Log into management account (or delegated admin account)
2. Launch the StackSet template
3. Specify target OUs (or root OU for all accounts)
4. Configure parameters (applied to all accounts)
5. StackSet automatically deploys to all accounts in specified OUs
6. New accounts added to OUs automatically receive the role

• Deploy to hundreds of accounts simultaneously
• Automatic deployment to new accounts (auto-deployment enabled)
• Consistent configuration across all accounts
• Centralized management from management account
• Easy updates across all accounts
• Automatic cleanup when accounts leave OUs
• Parallel deployment for faster completion
• Single point of configuration

• Requires AWS Organizations
• Must be deployed from management or delegated admin account
• Same configuration applied to all accounts in target OUs
• More complex troubleshooting (failures in individual accounts)
• Requires SERVICE_MANAGED permission model
• Cannot customize per-account without multiple StackSets
• Initial setup more complex than individual deployment

• Permission Model: SERVICE_MANAGED (uses AWS Organizations integration)
• Auto Deployment: Enabled by default
  • Automatically deploys to new accounts added to target OUs
  • Automatically removes stacks when accounts leave OUs
• Concurrent Deployment: 100% (deploys to all accounts simultaneously)
• Failure Tolerance: 100% (continues even if some accounts fail)
• Region Concurrency: PARALLEL (deploys to all regions simultaneously if multi-region)

• You have 10 or more accounts
• Accounts are in an AWS Organization
• You want consistent configuration across accounts
• You need automatic deployment to new accounts
• You want centralized management and updates
• You have a well-organized OU structure
• You want to minimize operational overhead

​

Deployment Type Decision Matrix

​

Hybrid Approach

1. StackSet for Standard Accounts + Individual for Special Cases
   • Use StackSet for most accounts with standard configuration
   • Use individual deployment for accounts needing custom permissions or configurations
2. Individual for Testing + StackSet for Production
   • Test and validate with individual deployments in dev/test accounts
   • Roll out to production using StackSets once validated
3. Multiple StackSets for Different OUs
   • Deploy different StackSets to different OUs with varying configurations
   • Example: Read-only for development OU, Administrator for production OU
4. StackSet for Organization + Individual for External Accounts
   • Use StackSet for accounts in your organization
   • Use individual deployment for accounts in partner organizations or standalone accounts

​

Configuration Guidance

​

Permission Levels

​

ReadOnlyAccess (pIsReadOnlyAccess)

• Account discovery and inventory
• Compliance auditing and reporting
• Cost analysis and optimization
• Security posture assessment
• Resource monitoring and alerting
• Read-only access for support teams

• List and describe operations for all AWS services
• Read configuration data
• View logs and metrics
• Access billing and cost information (read-only)

• Creating, modifying, or deleting resources
• Changing configurations
• Managing IAM users or policies
• Performing any write operations

​

AdministratorAccess (pIsAdministratorAccess)

• Full account management
• Infrastructure deployment and management
• Emergency access for incident response
• Complete administrative control

• All actions on all AWS services
• Full IAM management
• Billing and cost management
• Account settings modification

• Nothing - this is full administrative access

​

PowerUserAccess (pIsPowerUserAccess)

• Application deployment and management
• Infrastructure operations
• Development and testing
• Most operational tasks

• Full access to most AWS services
• Create, modify, and delete resources
• Configure services and applications
• Access to billing information

• Creating or managing IAM users
• Creating or managing IAM groups
• Modifying IAM policies
• Managing organization-level settings

​

ViewOnlyAccess (pIsViewOnlyAccess)

• Similar to ReadOnlyAccess but with job function focus
• Viewing resources without modification
• Monitoring and observability

​

SecurityAudit (pIsSecurityAudit)

• Security compliance auditing
• Security posture assessment
• Configuration review
• Log analysis for security events

• Read access to security-related configurations
• Access to CloudTrail logs
• Access to Config data
• Security group and network ACL inspection
• IAM policy and role inspection

• Modifying security configurations
• Creating or deleting resources
• Changing IAM policies

​

SystemAdministrator (pIsSystemAdministrator)

• System administration tasks
• Application infrastructure management
• Operational maintenance
• Resource provisioning

• Full access to most AWS services
• Resource creation and management
• Configuration changes
• Similar to PowerUserAccess with job function focus

• IAM user and group management
• Organization-level changes

​

SupportUser (pIsSupportUser)

• AWS Support case management
• Troubleshooting assistance
• Support ticket creation and tracking
• Working with AWS Support teams

• Create and manage AWS Support cases
• Access to Trusted Advisor
• Access to Health Dashboard
• Limited read access for troubleshooting

• Modifying resources
• Full read access to all services
• Administrative operations

​

Billing (pIsBillingAccess)

• Cost analysis and reporting
• Billing management
• Budget monitoring
• Cost optimization

• View and download bills
• Access to Cost Explorer
• Budget creation and management
• Cost and usage reports
• Payment method management

• Resource management
• Service configuration
• Non-billing operations

​

Combining Permission Levels

• ReadOnlyAccess + SecurityAudit: Comprehensive read access with enhanced security visibility
• ReadOnlyAccess + Billing: Full visibility including cost information
• PowerUserAccess + Billing: Operational access with cost management
• AdministratorAccess only: Full administrative control (use sparingly)

​

External ID Configuration

​

What is External ID?

​

Why Use External ID?

​

External ID Best Practices

• Generate a unique random string for each role or account
• Minimum length: 32 characters
• Use cryptographically secure random generation
• Include letters, numbers, and special characters
• Example tools: openssl rand -base64 32, password managers, AWS Secrets Manager

• Store External IDs securely (password manager, secrets manager, encrypted vault)
• Treat External IDs like passwords
• Do not commit External IDs to version control
• Limit access to External IDs to authorized personnel

• Rotate External IDs periodically according to your security policies
• Coordinate rotation with Quiverstone configuration updates
• Document rotation procedures
• Consider automated rotation for large deployments

• Use unique External IDs per account (recommended)
• Or use unique External IDs per role type
• Avoid reusing External IDs across multiple accounts
• Unique IDs limit blast radius if one is compromised

• Direct access roles: Strongly recommended
• Chained access roles: Recommended for both intermediate and destination roles
• Browser access roles: Not supported

​

Role Naming Best Practices

​

Naming Conventions

• Good: QuiverstoneDirectAccess, QuiverstoneChainedAccess, QuiverstoneBrowserSession
• Avoid: quiverstone-role, QS-Access, access-role-1

• QuiverstoneDirectAccess - clearly indicates direct access
• QuiverstoneChainedAccess - clearly indicates chained access
• QuiverstoneBrowserSession - clearly indicates browser access

• QuiverstoneDirectAccess-Prod
• QuiverstoneDirectAccess-Dev
• QuiverstoneDirectAccess-Test

• QuiverstoneDirectAccess-OrgA
• QuiverstoneDirectAccess-Finance

​

Role Name Constraints

• Maximum length: 64 characters
• Allowed characters: A-Z, a-z, 0-9, plus (+), equals (=), comma (,), period (.), at (@), underscore (_), hyphen (-)
• Must be unique within the account
• Case sensitive

​

Default Names

• Browser access: QuiverstoneBrowserSession
• Direct access: QuiverstoneDirectAccess
• Chained access: QuiverstoneChainedAccess
• Intermediate: QuiverstoneTrustedIntermediate

​

StackSet Configuration Options

​

Deployment Targets

• Specify one or more OU IDs (comma-separated)
• Use root OU ID to deploy to all accounts
• StackSet deploys to all accounts in specified OUs
• New accounts added to OUs automatically receive deployment

1. Open AWS Organizations console
2. Navigate to AWS accounts
3. Select an OU
4. Copy the OU ID (format: ou-xxxx-yyyyyyyy)

​

Deployment Region

• IAM roles are global, so single region deployment is sufficient
• Default: us-east-1
• Choose your organization’s home region

​

Auto-Deployment Settings

• When an account leaves a target OU, the stack is automatically deleted
• Ensures clean removal of roles when accounts move

​

Concurrent Deployment

• Deploys to all accounts simultaneously
• Fastest deployment time
• Can be reduced if you want more controlled rollout

• Continues deployment even if some accounts fail
• Allows successful deployments to complete
• Failed accounts can be retried individually

​

Region Concurrency

​

Deployment Scenarios

​

Small Organizations (1-10 Accounts)

• Template: direct-access-role.yaml
• Deployment: Individual to each account
• Permissions: ReadOnlyAccess (minimum), add others as needed
• External ID: Unique per account (recommended)

1. Generate unique External ID for each account
2. Deploy direct-access-role.yaml to each account individually
3. Configure ReadOnlyAccess and any additional permissions needed
4. Copy role ARN and External ID from each deployment
5. Configure each account in Quiverstone

• Simple and straightforward
• Full control over each account
• Easy to customize per account
• No AWS Organizations requirement

• Manual process for each account
• Manageable at this scale
• Consider StackSets if you plan to grow beyond 10 accounts

​

Medium Organizations (10-50 Accounts)

• Template: direct-access-role-stackset.yaml
• Deployment: StackSet from management account
• Permissions: ReadOnlyAccess + additional permissions per OU
• External ID: Single External ID for all accounts (or unique per OU)

1. Organize accounts into OUs by environment or team
2. Generate External ID(s)
3. Deploy direct-access-role-stackset.yaml from management account
4. Target root OU or specific OUs
5. Configure permissions appropriate for each OU
6. StackSet automatically deploys to all accounts
7. Configure organization in Quiverstone with role ARN pattern and External ID

• Automated deployment to all accounts
• Consistent configuration
• Auto-deployment to new accounts
• Centralized management

• Requires AWS Organizations
• Same configuration per StackSet (use multiple StackSets for different configurations)
• Consider different StackSets for different OUs with varying permission needs

• Deploy one StackSet to development OU with ReadOnlyAccess
• Deploy another StackSet to production OU with PowerUserAccess
• Allows different permission levels per environment

​

Large Organizations (50+ Accounts)

• Template: direct-access-role-stackset.yaml (multiple instances)
• Deployment: Multiple StackSets targeting different OUs
• Permissions: Vary by OU and business unit requirements
• External ID: Unique per StackSet or per OU

1. Design OU structure aligned with business units and environments
2. Define permission requirements per OU
3. Generate External IDs per StackSet
4. Deploy multiple StackSets:
   • Development OU: ReadOnlyAccess
   • Staging OU: PowerUserAccess
   • Production OU: ReadOnlyAccess + SecurityAudit
   • Infrastructure OU: SystemAdministrator
5. Configure organization in Quiverstone with role patterns

• Scales to hundreds of accounts
• Granular control per OU
• Automated deployment and updates
• Consistent within each OU

• Requires well-designed OU structure
• Multiple StackSets to manage
• Document which StackSet applies to which OU
• Consider automation for StackSet management

• Use consistent naming: QuiverstoneDirectAccess-Dev, QuiverstoneDirectAccess-Prod
• Document StackSet to OU mappings
• Implement change control for StackSet updates
• Monitor StackSet deployment status
• Use CloudFormation drift detection

​

Highly Regulated Environments

• Templates: trusted-intermediate-role.yaml + chained-access-role-stackset.yaml
• Deployment: Intermediate role in security account, StackSet for destination roles
• Permissions: Minimal required permissions (ReadOnlyAccess + specific additions)
• External ID: Unique External IDs for both intermediate and destination roles
• Trust: Named role trust (not account-level trust)

1. Designate or create a security/audit account as intermediate account
2. Deploy trusted-intermediate-role.yaml to intermediate account:
   • Use External ID
   • Use specific-role-any-account scope
   • Specify destination role name
3. Implement additional controls in intermediate account:
   • CloudTrail logging
   • CloudWatch alarms for role assumptions
   • Optional: IP restrictions, time-based access
4. Deploy chained-access-role-stackset.yaml to target accounts:
   • Use External ID (can be different from intermediate)
   • Use Named trust (specific role, not account)
   • Specify intermediate role name
   • Configure minimal required permissions
5. Configure chained access in Quiverstone

• Additional security layer through intermediate account
• Centralized access control and auditing
• Can implement custom security controls
• Meets requirements for environments prohibiting direct external trust
• Quick revocation by modifying only intermediate role

• Enable CloudTrail in intermediate account with log file validation
• Set up CloudWatch alarms for unusual role assumption patterns
• Implement IP-based restrictions in intermediate role trust policy
• Use time-based access controls if needed
• Regular audit of intermediate role usage
• Separate External IDs for defense in depth

• Document the role chain for auditors
• Maintain audit logs for all role assumptions
• Implement least privilege permissions
• Regular access reviews
• Automated compliance checks

​

Multi-Organization Deployment

• Templates: Multiple trusted-intermediate-role.yaml + chained-access-role-stackset.yaml per org
• Deployment: One intermediate role per organization, StackSets within each organization
• Permissions: Vary by organization requirements
• External ID: Unique per organization

1. For each organization:
   • Deploy intermediate role to a designated account in that organization
   • Deploy chained-access-role-stackset to target accounts in that organization
   • Use unique External IDs per organization
2. Configure each organization separately in Quiverstone
3. Maintain separate role chains per organization

• Isolation between organizations
• Independent security controls per organization
• Flexible permission models per organization
• Clear organizational boundaries

• More complex to manage multiple intermediate roles
• Document which intermediate role serves which organization
• Consider naming conventions to identify organization
• May need separate Quiverstone configurations per organization

​

Development and Testing Environments

• Template: browser-access-role.yaml or direct-access-role.yaml
• Deployment: Individual to each dev/test account
• Permissions: AdministratorAccess or PowerUserAccess (broader permissions acceptable in dev/test)
• External ID: Optional for dev/test (required for direct access)

1. For browser access:
   • Deploy browser-access-role.yaml
   • Specify your AWS account as trusted account
   • Enable broader permissions (PowerUserAccess or AdministratorAccess)
2. For direct access:
   • Deploy direct-access-role.yaml
   • Use External ID
   • Enable broader permissions

• Quick setup for development
• Broader permissions acceptable in non-production
• Easy to test and experiment
• Browser access provides familiar console experience

• Use different roles for dev/test vs production
• Don’t use browser access in production
• Consider separate External IDs for dev/test
• Document that these are non-production configurations

​

Disaster Recovery and Emergency Access

• Template: direct-access-role.yaml
• Deployment: Individual or StackSet to all critical accounts
• Permissions: AdministratorAccess
• External ID: Highly secure, stored in break-glass procedure
• Role Name: QuiverstoneEmergencyAccess (distinct from regular access)

1. Deploy separate emergency access roles to critical accounts
2. Configure with AdministratorAccess
3. Use highly secure External ID
4. Store External ID in secure break-glass procedure
5. Document emergency access procedures
6. Do NOT configure in Quiverstone for regular use

1. Emergency access roles are pre-deployed but not configured in Quiverstone
2. During emergency, retrieve External ID from secure storage
3. Configure emergency role in Quiverstone
4. Use for emergency operations
5. After emergency, remove configuration from Quiverstone
6. Audit all actions taken during emergency
7. Rotate External ID after use

• Pre-deployed for immediate use
• Full administrative access for emergency response
• Separate from regular access roles
• Clear audit trail

• Store External ID in highly secure location (physical safe, secure vault)
• Limit knowledge of External ID to authorized personnel
• Implement strict procedures for emergency use
• Mandatory audit after each use
• Rotate External ID after emergency use
• Consider time-based access controls

​

Troubleshooting

​

Common Issues and Solutions

​

Issue: “Access Denied” when assuming role

1. Incorrect Trust Policy
   • Check: Verify the trust policy allows the correct principal
   • Direct Access: Should trust Quiverstone production account (684035162433)
   • Chained Access: Should trust intermediate account or specific intermediate role
   • Browser Access: Should trust your AWS account
   • Solution: Update trust policy in IAM console or redeploy with correct parameters
2. External ID Mismatch
   • Check: Verify External ID in Quiverstone matches the role’s trust policy
   • Solution: Update External ID in Quiverstone or redeploy role with correct External ID
   • Note: External ID is case-sensitive
3. Role Name Mismatch
   • Check: Verify role ARN in Quiverstone matches the actual role ARN
   • Solution: Copy role ARN from CloudFormation outputs or IAM console
   • Note: Role names are case-sensitive
4. Intermediate Role Issues (Chained Access)
   • Check: Verify intermediate role exists and is configured correctly
   • Check: Verify intermediate role can assume destination role
   • Solution: Test intermediate role assumption separately
   • Solution: Verify destination role trusts intermediate role
5. Permission Boundary Restrictions
   • Check: Verify no permission boundaries are restricting role assumption
   • Solution: Review and adjust permission boundaries if present

​

Issue: CloudFormation stack creation fails

1. Role Name Already Exists
   • Error: “Role with name X already exists”
   • Solution: Choose a different role name or delete existing role
   • Check: Look in IAM console for existing roles
2. Insufficient Permissions
   • Error: “User is not authorized to perform iam:CreateRole”
   • Solution: Ensure you have IAM permissions to create roles
   • Required Permissions: iam:CreateRole, iam:PutRolePolicy, iam:AttachRolePolicy
3. Invalid Parameter Values
   • Error: “Parameter validation failed”
   • Solution: Review parameter values for correct format
   • Common Issues: Account IDs must be 12 digits, External ID max 1224 characters
4. StackSet Deployment Failures
   • Error: “StackSet operation failed in some accounts”
   • Solution: Check StackSet operations tab for per-account failures
   • Solution: Review CloudFormation events in failed accounts
   • Common Cause: Insufficient permissions in target accounts

​

Issue: Role exists but Quiverstone cannot discover accounts

1. Missing Organizations Permissions
   • Check: Verify role has Organizations read permissions
   • Solution: All access role templates include Organizations permissions by default
   • Solution: If using custom role, add Organizations read permissions
2. Role Deployed to Wrong Account
   • Check: For inventory, role should be in management account or delegated admin
   • Solution: Deploy inventory role to correct account
   • Note: Access roles can be in any account
3. Organizations Not Enabled
   • Check: Verify AWS Organizations is enabled in the account
   • Solution: Enable AWS Organizations if needed

​

Issue: StackSet not deploying to new accounts

1. Auto-Deployment Not Enabled
   • Check: Verify StackSet has auto-deployment enabled
   • Solution: Update StackSet to enable auto-deployment
   • Note: All templates enable auto-deployment by default
2. Account Not in Target OU
   • Check: Verify new account is in an OU targeted by the StackSet
   • Solution: Move account to target OU or update StackSet targets
3. StackSet Operation In Progress
   • Check: Check StackSet operations tab for in-progress operations
   • Solution: Wait for current operation to complete
   • Note: StackSets process one operation at a time
4. Service-Managed Permissions Issue
   • Check: Verify StackSet uses SERVICE_MANAGED permission model
   • Solution: Ensure CloudFormation has Organizations integration enabled
   • Solution: Check for service control policies blocking StackSet operations

​

Issue: Cannot update existing role

1. Role Name Change Not Allowed
   • Error: “Cannot update role name”
   • Solution: Role name changes require replacement (delete and recreate)
   • Workaround: Create new role with new name, update Quiverstone, delete old role
2. Managed Policy Conflicts
   • Error: “Cannot attach policy”
   • Solution: Check for policy attachment limits (10 managed policies per role)
   • Solution: Reduce number of enabled permissions
3. Trust Policy Update Issues
   • Check: Verify trust policy changes are valid
   • Solution: Review trust policy syntax
   • Solution: Ensure principal ARNs are correct

​

Issue: Chained access not working

1. Deployment Order
   • Check: Verify intermediate role was deployed before destination role
   • Solution: Deploy intermediate role first, then destination role
2. Trust Configuration Mismatch
   • Check: Verify destination role trusts intermediate role
   • Check: If using Named trust, verify intermediate role name matches
   • Solution: Update destination role trust policy
   • Solution: Redeploy with correct intermediate role name
3. External ID Mismatch
   • Check: Verify both External IDs are configured correctly in Quiverstone
   • Solution: Update Quiverstone configuration with correct External IDs
   • Note: Intermediate and destination can have different External IDs
4. Intermediate Role Permissions
   • Check: Verify intermediate role has permission to assume destination role
   • Solution: Check intermediate role’s assume role scope configuration
   • Solution: Ensure scope allows assuming the destination role

​

Validation Steps

​

Step 1: Verify Role Exists

# Using AWS CLI
aws iam get-role --role-name QuiverstoneDirectAccess

# Expected: Role details returned
# If error: Role doesn't exist or you don't have permissions

​

Step 2: Verify Trust Policy

# Get role trust policy
aws iam get-role --role-name QuiverstoneDirectAccess --query 'Role.AssumeRolePolicyDocument'

# Check:
# - Correct principal (Quiverstone account, intermediate account, or your account)
# - External ID present (if configured)
# - Correct External ID value

​

Step 3: Verify Attached Policies

# List attached managed policies
aws iam list-attached-role-policies --role-name QuiverstoneDirectAccess

# Expected: See enabled permission policies (ReadOnlyAccess, etc.)

​

Step 4: Test Role Assumption (Direct Access)

# Attempt to assume role (requires Quiverstone credentials)
aws sts assume-role \
  --role-arn arn:aws:iam::ACCOUNT_ID:role/QuiverstoneDirectAccess \
  --role-session-name test \
  --external-id YOUR_EXTERNAL_ID

# Expected: Temporary credentials returned
# If error: Check trust policy and External ID

​

Step 5: Verify Organizations Permissions

# Test Organizations access (using assumed role credentials)
aws organizations describe-organization

# Expected: Organization details returned
# If error: Missing Organizations permissions

​

Step 6: Verify StackSet Deployment

# List StackSet instances
aws cloudformation list-stack-instances \
  --stack-set-name quiverstone-direct-access-role

# Expected: List of accounts where role is deployed
# Check: Verify all expected accounts are present

​

Step 7: Check StackSet Operation Status

# List StackSet operations
aws cloudformation list-stack-set-operations \
  --stack-set-name quiverstone-direct-access-role

# Check: Verify latest operation succeeded
# If failed: Check operation details for error messages

​

Debug Checklist

• Role exists in the correct AWS account
• Role name matches configuration in Quiverstone
• Role ARN is correct in Quiverstone

• Trust policy allows correct principal
• External ID is present in trust policy (if using External ID)
• External ID matches Quiverstone configuration
• External ID is case-sensitive match

• At least one permission level is enabled
• Required permissions are attached (ReadOnlyAccess minimum)
• Organizations permissions are present
• No permission boundaries restricting access

• Intermediate role exists and is configured
• Intermediate role was deployed before destination role
• Destination role trusts intermediate role (or account)
• Intermediate role name matches in destination trust policy
• Both External IDs are configured in Quiverstone
• Intermediate role has permission to assume destination role

• StackSet deployed from management account
• Target OUs are correct
• Auto-deployment is enabled
• Latest StackSet operation succeeded
• All expected accounts have stack instances
• No service control policies blocking deployment

• Quiverstone has correct role ARN
• Quiverstone has correct External ID(s)
• Account ID is correct in Quiverstone
• Configuration saved in Quiverstone

​

Getting Help

1. Gather Information:
   • Role ARN
   • Error messages (exact text)
   • CloudFormation stack events
   • CloudTrail logs for AssumeRole attempts
   • StackSet operation details (if applicable)
2. Check CloudTrail:
   • Look for AssumeRole events
   • Check for AccessDenied errors
   • Review error messages for specific causes
3. Review CloudFormation Events:
   • Check stack events for deployment errors
   • Review StackSet operation details
   • Look for per-account failure reasons
4. Contact Support:
   • Provide gathered information
   • Include role configuration details
   • Describe steps already attempted
   • Include relevant CloudTrail or CloudFormation logs

​

Security Best Practices

​

Custom Role Names

• Use organization-specific prefixes: MyCompany-Access-Production
• Include environment indicators: CustomAccess-Prod, CustomAccess-Dev
• Avoid predictable patterns
• Document your naming convention securely
• Use consistent naming across all accounts

​

External ID Requirements

• Generate cryptographically secure random strings (minimum 32 characters)
• Use unique External IDs per role or per account
• Store External IDs in a secure password manager or secrets management system
• Never commit External IDs to version control
• Rotate External IDs periodically (quarterly or annually)
• Use different External IDs for intermediate and destination roles in chained access

# Using OpenSSL
openssl rand -base64 32

# Using Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Using AWS Secrets Manager
aws secretsmanager get-random-password --password-length 32

​

Protecting Role Configurations from Inspection

​

Example Deny Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenyRoleInspection",
      "Effect": "Deny",
      "Action": [
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListRolePolicies",
        "iam:ListAttachedRolePolicies"
      ],
      "Resource": [
        "arn:aws:iam::*:role/*Access*",
        "arn:aws:iam::*:role/*Support*",
        "arn:aws:iam::*:role/*Inventory*",
        "arn:aws:iam::*:role/*Intermediate*"
      ]
    }
  ]
}

DenyRoleInspectionPolicy:
  Type: AWS::IAM::Policy
  Properties:
    PolicyName: DenyRoleInspection
    PolicyDocument:
      Version: '2012-10-17'
      Statement:
        - Sid: DenyRoleInspection
          Effect: Deny
          Action:
            - iam:GetRole
            - iam:GetRolePolicy
            - iam:ListRolePolicies
            - iam:ListAttachedRolePolicies
          Resource:
            - arn:aws:iam::*:role/*Access*
            - arn:aws:iam::*:role/*Support*
            - arn:aws:iam::*:role/*Inventory*
            - arn:aws:iam::*:role/*Intermediate*
    Roles:
      - TieredSupportRole
      - OperationsRole
      - DeveloperRole

​

Policy Explanation

• DenyRoleInspection: Prevents viewing role details, trust policies, and attached policies
• Resource Patterns: Adjust the patterns to match your custom role names
  • *Access*: Matches roles containing “Access”
  • *Support*: Matches roles containing “Support”
  • *Inventory*: Matches roles containing “Inventory”
  • *Intermediate*: Matches roles containing “Intermediate”
• Actions Denied:
  • iam:GetRole: Prevents viewing role details including trust policy (where External ID is visible)
  • iam:GetRolePolicy: Prevents viewing inline policies
  • iam:ListRolePolicies: Prevents listing inline policies
  • iam:ListAttachedRolePolicies: Prevents listing managed policies

​

Implementation Recommendations

1. Apply to Support Roles: Attach this deny policy to all tiered support and operational roles that don’t need to manage IAM
2. Customize Resource Patterns: Update the resource ARN patterns to match your custom role names
3. Exclude Administrative Roles: Do NOT apply this policy to roles that legitimately need to manage IAM (security admins, IAM admins)
4. Test Thoroughly: Verify the policy doesn’t block legitimate operations before deploying to production
5. Document Exceptions: Clearly document which roles are exempt from this policy and why
6. Use with StackSets: Deploy this policy organization-wide using CloudFormation StackSets

​

Additional Security Controls

• Enable CloudTrail in all accounts
• Set up CloudWatch alarms for unusual role assumption patterns
• Monitor for failed AssumeRole attempts
• Alert on role assumption from unexpected IP addresses

• Use SCPs to enforce External ID requirements at the organization level
• Restrict role creation to approved patterns
• Prevent modification of critical security roles

• Quarterly review of who has access to view IAM roles
• Annual review of all External IDs and role configurations
• Audit role assumption patterns for anomalies
• Review and update role permissions based on least privilege

• Start with ReadOnlyAccess and add permissions as needed
• Avoid AdministratorAccess unless absolutely required
• Use PowerUserAccess or SystemAdministrator for operational needs
• Regularly review and remove unused permissions

• Add IP-based conditions to role trust policies
• Restrict role assumptions to known IP ranges
• Use VPC endpoints for API calls
• Implement time-based access controls

​

Security Checklist

• Changed default role name to custom value
• Generated cryptographically secure External ID (32+ characters)
• Stored External ID in secure password manager or secrets system
• Configured External ID in CloudFormation template
• Verified External ID is not committed to version control
• Applied deny policy to prevent role inspection by non-admin roles
• Enabled CloudTrail logging in all accounts
• Set up CloudWatch alarms for unusual role assumptions
• Documented role naming convention securely
• Scheduled External ID rotation (quarterly/annually)
• Reviewed and minimized permissions (least privilege)
• Tested role assumption with correct External ID
• Verified deny policy doesn’t block legitimate operations
• Documented which roles are exempt from inspection restrictions