Authenticating end-user client applications for Amazon Chime SDK messaging

You can also run Amazon Chime SDK messaging from end-user client applications. Making SDK calls from a back-end service for Amazon Chime SDK messaging explains how to make API calls such as create-channel, send-channel-message, and list-channel-messages. End user client applications such as browsers and mobile applications make these same API calls. Client applications can also connect via WebSocket to receive real time updates on messages and events to channels they are members of. This section covers how to give IAM credentials to a client application scoped to a specific app instance user. Once the end users have these credentials, they can make the API calls shown in Making SDK calls from a back-end service for Amazon Chime SDK messaging. To see a full demo of a client application, see https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat. For more information about receiving real-time messages from the channels that a client app belongs to, see Using WebSockets to receive messages in Amazon Chime SDK messaging.

Providing IAM credentials to end users

Amazon Chime SDK messaging integrates natively with AWS Identity and Access Management (IAM) policies to authenticate incoming requests. The IAM policy defines what an individual user can do. IAM policies can be crafted to provide scoped-down limited credentials for your use case. For more information on creating policies for Amazon Chime SDK messaging users, see Example IAM roles for Amazon Chime SDK messaging.

If you have an existing identity provider, you have the following options for integrating your existing identity with Amazon Chime SDK messaging.

If you do not have an identity provider, you can get started with Amazon Cognito User Pools. For an example of how to use Amazon Cognito with the Amazon Chime SDK messaging features, see Build chat features into your application with Amazon Chime SDK messaging.

Alternately, you can use the AWS STS to create your own credential vending service or build your own identity provider.

Using STS to vend credentials

If you already have an IDP such as ActiveDirectory LDAP, and you want to implement a custom credential vending service, or grant access to chat for non-authenticated meeting attendees, you can use the AWS STS AssumeRole API. To do this, you first create an Amazon Chime SDK messaging SDK Role. For more information about creating that role, see Creating a role to delegate permissions to an IAM user .

The IAM role would have permissions to the Amazon Chime SDK messaging action your application would use, similar to the following:

{
    "Version": "2012-10-17",
    "Statement": [
         {
            "Effect": "Allow",
            "Action": [
                "chime:GetMessagingSessionEndpoint"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "chime:SendChannelMessage",
                "chime:ListChannelMessages",
                "chime:CreateChannelMembership",
                "chime:ListChannelMemberships",
                "chime:DeleteChannelMembership",
                "chime:CreateChannelModerator",
                "chime:ListChannelModerators",
                "chime:DescribeChannelModerator",
                "chime:CreateChannel",
                "chime:DescribeChannel",
                "chime:ListChannels",
                "chime:DeleteChannel",
                "chime:RedactChannelMessage",
                "chime:UpdateChannelMessage",
                "chime:Connect",
                "chime:ListChannelBans",
                "chime:CreateChannelBan",
                "chime:DeleteChannelBan",
                "chime:ListChannelMembershipsForAppInstanceUser"
                "chime:AssociateChannelFlow",
                "chime:DisassociateChannelFlow",
                "chime:GetChannelMessageStatus"
            ],
            "Resource": [
                "{chime_app_instance_arn}/user/${aws:PrincipalTag/my_applications_user_id}",
                "{chime_app_instance_arn}/channel/*"
            ]
        }
    ]
}

For this example, call this role the ChimeMessagingSampleAppUserRole.

Note the session tag in the ChimeMessagingSampleAppUserRole policy ${my_application_user_id} in the user ARN resource. This session tag is parameterized in the AssumeRole API call to limit the credentials returned to permissions for a single user.

The AssumeRole and TagSession APIs are called using an already credentialed IAM entity, such as an IAM user. The APIs can also be called by a different IAM role such as an AWS Lambda run role. That IAM identity must have permissions to call AssumeRole and TagSession on the ChimeMessagingSampleAppUserRole.

{
    "Version": "2012-10-17",
    "Statement": [
         {
            "Effect": "Allow",
            "Action": [ 
                "sts:AssumeRole",
                "sts:TagSession"
                ],
            "Resource": "arn:aws:iam::my_aws_account_id:role/ChimeMessagingSampleAppUserRole"
        }
    ]
}

For this example, call this role the ChimeSampleAppServerRole.

You need to set up the ChimeMessagingSampleAppUserRole with a trust policy that allows the ChimeMessagingSampleAppServerRole to call the STS AssumeRole API on it. For more information about using trust policies with IAM roles, see How to use trust policies with IAM roles . You can use the AWS IAM Roles Console to add this policy to the ChimeMessagingSampleAppUserRole. The following example shows a typical trust relationship.

{
    "Version": "2012-10-17",
    "Statement": [
         {
            "Effect": "Allow",
            "Principal": {
               "AWS":"arn:aws:iam::my_aws_account_id:role/ChimeMessagingSampleAppServerRole"
            }
            "Action": "sts:AssumeRole"
        }
    ]
}  

In a sample deployment, an Amazon EC2 instance, or an AWS Lambda is launched with the ChimeMessagingSampleAppServerRole. The server then:

The following example shows CLI command for assuming a role for step 2:

aws sts assume-role --role-arn arn:aws:iam::my_aws_account_id:role/ChimeMessagingSampleAppUserRole --role-session-name demo --tags Key=my_applications_user_id,Value=123456789