Understanding AWS Chatbot permissions - AWS Chatbot

Understanding AWS Chatbot permissions

AWS Chatbot requires an AWS Identity and Access Management (IAM) role to perform actions. Actions you can perform in your chat channels include running commands and responding to interactive messages. AWS Chatbot uses channel roles, user roles, and channel guardrail policies to control the actions channel members can take. What your users can do is the intersection of your guardrail policies and what is allowed by their roles.

Role setting

Channel role

A channel role gives all channel members the same permissions. This is useful if your channel members are similar users or they typically perform the same actions. You can use an existing role as your channel role or you can create a new role using templates. If you use a channel role, your channel members can still choose their own user roles. Your channel role is restricted by your guardrail policies. You can set your channel role in channel configurations from the AWS Chatbot console.

Channel role templates

There are six templates that can be used to create a channel role:

  • Notification permissions

  • Read-only command permissions

  • Lambda-invoke command permissions

  • AWS Support command permissions

  • Incident Manager permissions

  • Resource Explorer permissions

You can use any and all combinations of these templates to suit your needs. For example, if you want to create a configuration that only delivers notifications, choose Notification permissions as your policy template. If you want your channel members to run read-only commands exclusively and you want notifications to be delivered, choose Read-only command permissions and Notification permissions as your policy templates.

User roles

User roles require channel members to choose their own roles. As a result, different users in your channel can have different permissions. If you have a diverse set of channel members or you don't want new channel members to perform actions as soon as they join your channel, user roles are appropriate. Under this schema, your channel members must have applied a user role to perform actions. When channel members apply a user role, it is mapped to their chat client ID. Administrators can unmap user roles from chat client IDs in the AWS Chatbot console. Your channel member's actions are limited by your guardrail policies, despite what user roles they may have applied. For more information on managing user roles, see Managing user roles.

User role requirement

Administrators can require user roles for all current channel members and channels and all channels created in the future by enabling a user role requirement in the AWS Chatbot console. Individual channels can't override this requirement. This can be done at the account level in User permissions, if you want to require every workspace and channel to use user roles. It can also be done at the channel configuration level wherein a channel level administrator can enable the user role requirement.


This feature is enforced at the account level.

Channel guardrail policies

Guardrail policies provide detailed control over what actions are available to your channel members and what actions AWS Chatbot can perform on your behalf. They constrain and take precedence over both user roles and channel roles. For example, if a user has a user role that allows administrator access, and they belong to a channel where the channel role or the guardrail policies limit permissions on one or more services, the user will have less than administrator-level access. You can set, view, and edit your guardrail policies in the AWS Chatbot console. If you had an AWS Chatbot configuration before the expansion of available commands on 11/28/2021, you may have a protection policy applied as one of your guardrail policies.


AWS Service Roles IAM policies can't be used as guardrail policies.

Non-supported operations

AWS Chatbot doesn't support running commands for operations in the following JSON policy:

{ "Statement": [ { "Action": [ "appsync:ListApiKeys", "chatbot:*", "codecommit:GetFile", "codecommit:GetCommit", "codecommit:GetDifferences", "cognito-idp:*", "cognito-identity:*", "connect:GetFederationToken", "dynamodb:BatchGetItem", "dynamodb:GetItem", "ec2:GetPasswordData", "ecr:GetAuthorizationToken", "ecr:GetLogin", "gamelift:RequestUploadCredentials", "gamelift:GetInstanceAccess", "identitystore:*", "lightsail:DownloadDefaultKeyPair", "lightsail:GetInstanceAccessDetail", "lightsail:GetKeyPair", "lightsail:GetKeyPairs", "lightsail:UpdateRelationalDatabase", "iam:*", "kms:*", "redshift:GetClusterCredentials", "sdb:*", "secretsmanager:*", "sso:*", "sso-admin:*", "sso-oidc:*", "storagegateway:DescribeChapCredentials", "sts:*", "s3:GetObject", "s3:HeadObject", "s3:PutObject", "s3:GetBucketPolicy", "snowball:GetJobUnlockCode" ], "Effect": "Deny", "Resource": "*" } ], "Version": "2012-10-17" }

Editing an IAM role for AWS Chatbot

You can create new IAM roles in the AWS Chatbot console, which provides a convenient way to deploy the AWS Chatbot service. You associate these roles with your chat channels or Amazon Chime webhooks. The AWS Chatbot console does not allow editing of IAM roles, including any roles that you've already created in the AWS Chatbot console.


AWS requires that you use the IAM console to edit IAM roles. If you create roles in the AWS Chatbot console, you must use the IAM console to edit them. This might happen, for example, when you are using the AWS Chatbot service and a new release comes out that supports new features.

Use the IAM console to edit AWS Chatbot roles. You can use the entire set of IAM console features to specify permissions for your AWS Chatbot users.

To edit roles

  1. Open the AWS Chatbot console at https://console.aws.amazon.com/chatbot/.

  2. Choose the configured client, and choose the name of the configured channel or webhook.

  3. Choose a role to edit:

    Channel role
    1. Choose the role you want to edit. When you choose a role, the IAM console opens, automatically showing role configuration page, with the Permissions tab displaying the selected role.


      You can attach AWS managed policies and customer managed policies. AWS Chatbot roles support both types of IAM policies.

    2. Choose Add permissions and then select Attach Policies.

    User roles
    1. Choose the User role tab.

    2. Choose Edit.


      You can attach AWS managed policies and customer managed policies. AWS Chatbot roles support both types of IAM policies.

    3. Choose Selected role information then choose a role. When you choose a role, the IAM console opens automatically showing role configuration page.

    4. Choose Add permissions and then select Attach Policies.

  4. Choose the name of the policy that you want. You can use the Search box to search for the policy by name or by a partial string of characters. For example, all IAM policies associated with AWS Chatbot include the character string Chatbot as part of the policy name. If you want your users to be able to use Amazon Q, attach the AmazonQFullAccess policy.

  5. You can attach any of three AWS managed policies to any role. You can use these policies as templates to create your own policies.

    • ReadOnlyAccess

    • CloudWatchReadOnlyAccess

    • AWSSupportAccess

    The ReadOnlyAccess policy is automatically attached to any role that you create in the AWS Chatbot console.

    The AWSSupportAccess policy is the only AWS managed policy that appears in the AWS Chatbot console when you configure new roles there.

    You can use these policies to create your own policies that are less permissive and specify the resources their users can access. You can substitute these custom policies for the ones listed here.

  6. Choose each of the policies that you want to attach to the role and choose Attach policy. If needed, use the Search box to locate the policies you're looking for.

    After you click Attach policy, the role's Permissions page opens and shows the change in the Permissions list.


For more information about the customer managed policies and AWS managed policies described in this section, see IAM Policies for AWS Chatbot.

For more information about editing IAM policies, see Editing IAM Policies. Exercise caution at all times when editing policies, and avoid overwriting existing customer managed policies.

Managing IAM role permissions for running commands

With AWS Identity and Access Management (IAM), you can use identity-based policies, which are JSON permissions policy documents, and attach them to an identity, such as a user, role, or group. These policies work with your guardrail policies to control what actions a user can perform. AWS Chatbot provides three IAM policies in the AWS Chatbot console that you can use to set up AWS CLI commands support for chat channels. Those policies include:

  • ReadOnly Command Permissions

  • Lambda-Invoke Command Permissions

  • AWS Support Command Permissions

You can use any or all of these policies, based on your organization's requirements. To use them, create a new channel IAM role in your channel configuration using the AWS Chatbot console, and attach the policies there. You can also attach the policies to the AWS Chatbot IAM roles using the IAM console. The policies simplify AWS Chatbot role configuration and enable you to set up quickly.

You can use these IAM policies as templates to define your own policies. For example, all policies described here use a wildcard ("*") to apply the policy's permissions to all resources:

"Resource": [ "*" ]

You can define custom permissions in a policy to limit actions to specific resources in your AWS account. These are called resource-based permissions. For more information on defining resources in a policy, see the section IAM JSON Policy Elements: Resource in the IAM User Guide.

For more information on these policies, see Configuring an IAM Role for AWS Chatbot.

Using the AWS Chatbot read-only command permissions policy

The AWS Chatbot ReadOnly Command Permissions policy controls access to several important AWS services, including IAM, AWS Security Token Service (AWS STS), AWS Key Management Service (AWS KMS), and Amazon S3. It disallows all IAM operations when using AWS commands in Microsoft Teams and Slack. When you use the ReadOnly Command Permissions policy, you allow or deny the following permissions to users who run commands in chat channels:

  • IAM (Deny All)

  • AWS KMS (Deny All)

  • AWS STS (Deny All)

  • Amazon Cognito (allows Read-Only, denies GetSigningCertificate commands)

  • Amazon EC2 (allows Read-Only, denies GetPasswordData commands)

  • Amazon Elastic Container Registry (Amazon ECR) (allows Read-Only, denies GetAuthorizationToken commands)

  • Amazon GameLift (allows Read-Only, denies requests for credentials and GetInstanceAccess commands)

  • Amazon Lightsail (allows List, Read, denies several key pair operations and GetInstanceAccess)

  • Amazon Redshift (denies GetClusterCredentials commands)

  • Amazon S3 (allows Read-Only commands, denies GetBucketPolicy commands)

  • AWS Storage Gateway (allows Read-Only, denies DescribeChapCredentials commands)

The ReadOnly Command Permissions policy JSON code is shown following:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "iam:*", "kms:*", "sts:*", "cognito-idp:GetSigningCertificate", "ec2:GetPasswordData", "ecr:GetAuthorizationToken", "gamelift:RequestUploadCredentials", "gamelift:GetInstanceAccess", "lightsail:DownloadDefaultKeyPair", "lightsail:GetInstanceAccessDetails", "lightsail:GetKeyPair", "lightsail:GetKeyPairs", "redshift:GetClusterCredentials", "s3:GetBucketPolicy", "storagegateway:DescribeChapCredentials" ], "Resource": [ "*" ] } ] }

Using the AWS Chatbot Lambda-Invoke policy

The AWS Chatbot Lambda-Invoke Command Permissions policy allows users to invoke AWS Lambda functions in chat channels. This policy is an AWS managed policy that is not specific to AWS Chatbot, though it appears in the AWS Chatbot console.

By default, invoked Lambda functions can perform any operation. You might need to define a more restrictive inline IAM policy that allows permissions to invoke specific Lambda functions, such as functions specifically developed for your DevOps team that only they should be able to invoke, and deny permissions to invoke Lambda functions for any other purpose.

The following example shows the Lambda-Invoke Command Permissions policy:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "lambda:invokeAsync", "lambda:invokeFunction" ], "Resource": [ "*" ] } ] }

You can also define resource-based permissions to allow invoking of Lambda functions only against specific resources, instead of the "*" wildcard that applies the policy to all resources. Always follow the IAM practice of granting only the permissions required for your users to do their jobs.

Protection policy

The expansion of usable CLI commands occurred on 11/28/2021. This expansion can allow channel members to create, read, update, and delete your AWS resources. To prevent this, a protection policy is applied as a guardrail policy to existing AWS Chatbot configurations by default. Specifically, the protection policy restricts permissions and actions to what was available before all CLI commands were usable. This policy is detachable, but we strongly recommend it stay in place until you’ve verified that all your guardrails, channel IAM roles, and user-level roles align with your governance policy or channel requirements. You can detach this policy from:

  • Individual workspaces.

  • Individual channels in the channel configurations page.

  • A selection of channels using the Set guardrails button.

  • All channel configurations in the User permissions page of the AWS Chatbot console.

The protection policy contains the ReadOnlyAccess policy and the following JSON code:

{ "Statement": [ { "Effect": "Allow", "Action": [ "lambda:Invoke*", "support:*", "ssm-incidents:*" ], "Resource": "*" } ] }