Guides
Go To Operata
Start typing to search…

IAM Role & Policies

IAM Role & Policies for service execution

👍

Default Deployment

The IAM roles and policies required to deploy and operate the integration are included in the CloudFormation template by default.

Required IAM Roles and Policies Overview

The Operata Cloud Collector v3 requires two primary IAM roles with their associated policies:

  1. EventBridge Pipe Role - Enables the EventBridge Pipe to read from Kinesis, invoke the Lambda function, and send data to the API destination
  2. Lambda Service Role - Enables the Lambda function to execute, access secrets, and optionally read from S3

1. EventBridge Pipe Role

Trust Policy

The EventBridge Pipe Role must allow the EventBridge Pipes service to assume the role with proper security conditions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "pipes.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "{AWS Account ID}",
                    "aws:SourceArn": "arn:aws:pipes:{AWS Region}:{AWS Account ID}:pipe/operataEventsPipe-{Instance Name}-amazonConnect"
                }
            }
        }
    ]
}

Required Policies for EventBridge Pipe Role

A. Kinesis Source Policy

Purpose: Allows EventBridge Pipes to read Contact Trace Records from the Amazon Connect Kinesis stream

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kinesis:DescribeStream",
                "kinesis:DescribeStreamSummary",
                "kinesis:GetRecords",
                "kinesis:GetShardIterator",
                "kinesis:ListShards",
                "kinesis:ListStreams"
            ],
            "Resource": "{CTR Kinesis Stream ARN}"
        }
    ]
}

B. Lambda Invocation Policy

Purpose: Allows EventBridge Pipes to invoke the Lambda function for data enrichment and redaction

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction",
                "lambda:InvokeFunctionUrl"
            ],
            "Resource": "arn:aws:lambda:{AWS Region}:{AWS Account ID}:function:CloudCollectorV3Stack-cloudcollectorv3redactor*"
        }
    ]
}

C. API Destination Policy

Purpose: Allows EventBridge Pipes to send processed events to the Operata API endpoint

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "events:InvokeApiDestination",
            "Resource": "{API Destination ARN}"
        }
    ]
}

Note: The API Destination ARN is dynamically created by CloudFormation with the name operataEndpointGroup-{Operata-Group-ID}.

2. Lambda Service Role

Trust Policy

The Lambda Service Role must allow the Lambda service to assume the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Required Policies for Lambda Service Role

A. AWS Managed Policy

  • AWSLambdaBasicExecutionRole: Provides CloudWatch Logs permissions for Lambda function logging

B. Secrets Manager Access Policy

Purpose: Allows Lambda to retrieve the Operata API key from AWS Secrets Manager

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "arn:aws:secretsmanager:{AWS Region}:{AWS Account ID}:secret:cloud-collector-v3/ctr/{Operata Group ID}/apiToken-*"
        }
    ]
}

C. EC2 Network Interface Policy (Required for VPC deployment)

Purpose: Allows Lambda to create and manage network interfaces when deployed in a VPC

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:AttachNetworkInterface",
                "ec2:CreateNetworkInterface",
                "ec2:DeleteNetworkInterface",
                "ec2:DescribeInstances",
                "ec2:DescribeNetworkInterfaces"
            ],
            "Resource": "*"
        }
    ]
}

D. S3 Access Policy (Optional - for Agent Data enrichment)

Purpose: Allows Lambda to read agent data files from S3 for data enrichment Note: This policy is only created when an S3 bucket is specified for agent data

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::{Agent Data Bucket Name}/*"
        },
        {
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::{Agent Data Bucket Name}"
        }
    ]
}

Security Best Practices

  1. Least Privilege: All policies follow the principle of least privilege, granting only the minimum permissions necessary
  2. Resource Restrictions: Policies specify exact resource ARNs where possible to prevent unauthorized access
  3. Condition Statements: Trust policies include condition statements to ensure roles can only be assumed by the intended services and accounts
  4. Secrets Management: API keys are stored in AWS Secrets Manager, not in environment variables or code
  5. No Wildcards: Avoid using wildcard (*) permissions except where absolutely necessary (EC2 network interfaces)

Deployment Notes

  • All these roles and policies are automatically created when deploying the CloudFormation template
  • The template uses dynamic references to ensure proper resource naming and ARN construction
  • Conditional logic in the template ensures optional policies (like S3 access) are only created when needed
  • Policy names include the Operata Group ID for easy identification when multiple integrations exist

IAM Deployment Policy for Manual Installation

If you need to deploy the Operata Cloud Collector resources outside of CloudFormation (due to organizational policies, compliance requirements, or existing IAM workflows), you'll need an IAM policy that grants permissions to create and manage all required resources.

Administrator Deployment Policy

This policy grants the minimum permissions required to deploy all Operata Cloud Collector components manually:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "IAMRoleAndPolicyManagement",
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:CreatePolicy",
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:GetRole",
                "iam:GetPolicy",
                "iam:GetPolicyVersion",
                "iam:ListRolePolicies",
                "iam:ListAttachedRolePolicies",
                "iam:PassRole",
                "iam:TagRole",
                "iam:UpdateAssumeRolePolicy"
            ],
            "Resource": [
                "arn:aws:iam::*:role/CloudCollectorV3Stack-*",
                "arn:aws:iam::*:role/operataEventBridgePipeRole*",
                "arn:aws:iam::*:policy/*-Operata-GroupId-*",
                "arn:aws:iam::*:policy/cloudcollectorv3*",
                "arn:aws:iam::*:policy/AgentDataS3Access"
            ]
        },
        {
            "Sid": "SecretsManagerManagement",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:CreateSecret",
                "secretsmanager:PutSecretValue",
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret",
                "secretsmanager:TagResource"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:cloud-collector-v3/ctr/*/apiToken-*"
        },
        {
            "Sid": "EventBridgeManagement",
            "Effect": "Allow",
            "Action": [
                "events:CreateConnection",
                "events:CreateApiDestination",
                "events:UpdateConnection",
                "events:UpdateApiDestination",
                "events:DescribeConnection",
                "events:DescribeApiDestination",
                "events:ListConnections",
                "events:ListApiDestinations",
                "events:TagResource"
            ],
            "Resource": [
                "arn:aws:events:*:*:connection/operataAPIgroup-*",
                "arn:aws:events:*:*:destination/operataEndpointGroup-*"
            ]
        },
        {
            "Sid": "EventBridgePipeManagement",
            "Effect": "Allow",
            "Action": [
                "pipes:CreatePipe",
                "pipes:UpdatePipe",
                "pipes:StartPipe",
                "pipes:StopPipe",
                "pipes:DescribePipe",
                "pipes:ListPipes",
                "pipes:TagResource"
            ],
            "Resource": "arn:aws:pipes:*:*:pipe/operataEventsPipe-*"
        },
        {
            "Sid": "LambdaFunctionManagement",
            "Effect": "Allow",
            "Action": [
                "lambda:CreateFunction",
                "lambda:UpdateFunctionCode",
                "lambda:UpdateFunctionConfiguration",
                "lambda:GetFunction",
                "lambda:GetFunctionConfiguration",
                "lambda:AddPermission",
                "lambda:RemovePermission",
                "lambda:TagResource",
                "lambda:ListVersionsByFunction"
            ],
            "Resource": "arn:aws:lambda:*:*:function:CloudCollectorV3Stack-cloudcollectorv3redactor*"
        },
        {
            "Sid": "LambdaS3CodeAccess",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:GetObjectVersion"
            ],
            "Resource": "arn:aws:s3:::*-operata-shared-assets-prod/redactor-*.zip"
        },
        {
            "Sid": "KinesisReadAccess",
            "Effect": "Allow",
            "Action": [
                "kinesis:DescribeStream",
                "kinesis:ListStreams"
            ],
            "Resource": "*"
        },
        {
            "Sid": "CloudFormationAccess",
            "Effect": "Allow",
            "Action": [
                "cloudformation:DescribeStacks",
                "cloudformation:ListStacks"
            ],
            "Resource": "*"
        }
    ]
}

Minimum Required Permissions by Service

IAM Service Permissions

  • CreateRole: Create the EventBridge Pipe and Lambda service roles
  • CreatePolicy: Create custom policies for Kinesis, Lambda, API destination, Secrets Manager, and S3 access
  • AttachRolePolicy: Attach AWS managed and custom policies to roles
  • PassRole: Allow services to assume the created roles
  • TagRole: Add tags for resource management and cost tracking

Secrets Manager Permissions

  • CreateSecret: Create secret to store Operata API key
  • PutSecretValue: Update the API key value
  • GetSecretValue: Verify secret creation (Lambda will also need this)

EventBridge Permissions

  • CreateConnection: Create connection with API key authentication
  • CreateApiDestination: Create destination pointing to Operata API endpoint
  • CreatePipe: Create pipe to process Kinesis stream data
  • StartPipe/StopPipe: Manage pipe lifecycle

Lambda Permissions

  • CreateFunction: Deploy the redactor Lambda function
  • UpdateFunctionConfiguration: Set environment variables
  • AddPermission: Grant EventBridge Pipes permission to invoke

Security Considerations for Manual Deployment

  1. Resource Naming Convention

    • Always include the Operata Group ID in resource names
    • Use consistent prefixes: CloudCollectorV3Stack- for Lambda resources
    • Follow the pattern: operata{ResourceType}-{GroupId} for EventBridge resources

  2. Resource Tagging

    {
    "Environment": "{Dev/Staging/Prod}",
    "ManagedBy": "Operata-CloudCollector",
    "OperataGroupId": "{Group ID}",
    "Version": "v3",
    "CreatedBy": "{Administrator}"
}

  3. Audit and Compliance

    • Enable CloudTrail logging for all API calls
    • Use AWS Config to track resource configuration changes
    • Implement SCPs (Service Control Policies) if using AWS Organizations
    • Regular review of IAM permissions using Access Analyzer

  4. Secret Management

    • Never store API keys in Lambda environment variables directly
    • Always use Secrets Manager with automatic rotation where possible
    • Restrict secret access to only the Lambda function role

Manual Deployment Checklist

Follow this order when manually deploying resources:

  1. Create Secrets Manager Secret

    • Name: cloud-collector-v3/ctr/{operataGroupId}/apiToken
    • Store the Operata API key value

  2. Create IAM Roles

    • Create Lambda Service Role with trust policy for lambda.amazonaws.com
    • Create EventBridge Pipe Role with trust policy for pipes.amazonaws.com

  3. Create and Attach IAM Policies

    • Attach AWSLambdaBasicExecutionRole managed policy to Lambda role
    • Create and attach Secrets Manager access policy to Lambda role
    • Create and attach EC2 network interface policy to Lambda role (if using VPC)
    • Create and attach S3 access policy to Lambda role (if using agent data)
    • Create and attach Kinesis source policy to EventBridge Pipe role
    • Create and attach Lambda invocation policy to EventBridge Pipe role
    • Create and attach API destination policy to EventBridge Pipe role

  4. Deploy Lambda Function

    • Function name: CloudCollectorV3Stack-cloudcollectorv3redactor-{unique-id}
    • Runtime: provided.al2
    • Handler: bootstrap
    • Timeout: 60 seconds
    • Set environment variables (OPERATA_API_KEY, OPERATA_GROUP_ID, etc.)

  5. Create EventBridge Connection

    • Name: operataAPIgroup-{operataGroupId}
    • Authentication: API_KEY with header Operata-API-Key

  6. Create EventBridge API Destination

    • Name: operataEndpointGroup-{operataGroupId}
    • Endpoint: https://api.operata.io/v2/aws/events/contact-record
    • HTTP Method: POST

  7. Create EventBridge Pipe

    • Name: operataEventsPipe-{instanceName}-amazonConnect
    • Source: Kinesis stream ARN
    • Enrichment: Lambda function ARN
    • Target: API destination ARN
    • Filter: { "data": {"Channel": ["VOICE"] } }

  8. Verify Deployment

    • Check pipe status is RUNNING
    • Verify Lambda function can access Secrets Manager
    • Test with sample CTR record if available
    • Monitor CloudWatch Logs for any errors

Troubleshooting Permissions

If deployment fails, check CloudTrail for specific permission errors. Common issues:

  • AccessDenied on PassRole: Ensure the deployment role has iam:PassRole for the service roles
  • InvalidParameterException on Pipes: Verify the Kinesis stream ARN is correct and accessible
  • ResourceNotFoundException: Ensure resources are created in the correct order
  • Connection timeout: Check VPC settings if Lambda is deployed in a VPC

Updated 6 months ago