Step 3: Authenticate and Authorize Chat Clients - Amazon Interactive Video Service

Step 3: Authenticate and Authorize Chat Clients

                Authenticate and authorize your clients for your newly created chat

Before you can start sending and receiving messages, you will need to authenticate and authorize your clients for your newly created chat room. Follow the steps below to generate an Amazon IVS Chat auth token.

Important: Tokens need to be generated by a server-side application using the AWS CLI, AWS SDK, or SigV4 signed requests. For security reasons, avoid generating tokens in client-side applications.

Token Expiration and Session Duration

Token expiration refers to how long a token is valid for use, to establish a connection with the Amazon IVS Chat Messaging API. If a token is not used to establish a connection before this time lapses, the token becomes invalid. Tokens are valid for one minute from the time of creation.

Session duration refers to how long an established session can remain active before it is automatically terminated by the Amazon IVS Chat Messaging API. That is, the session duration is how long the client can remain connected to the chat room before a new token must be generated and a new connection must be established. During token creation, you can specify session duration.

Design note: Tokens can expire at any time, not just when the session duration period ends; e.g., if the WebSocket connection breaks. So, make your application resilient enough to generate and create new tokens for clients on demand. This is an important up-front design consideration for your application.

Important: An Amazon IVS chat token can be used only once to establish a connection. If a connection is terminated at any point after an initial connection is established, a new chat token must be generated before a connection can be re-established.

AWS SDK Instructions

Creating a chat room with the AWS SDK is an advanced option and requires that you first download and configure the SDK on your application. Below are instructions for the AWS SDK using JavaScript.

Important: This code must be executed on the server side and its output passed to the client.

Prerequisite: To use the code sample below, you need to load the AWS JavaScript SDK into your application. For details, see Getting started with the AWS SDK for JavaScript.

/* Function to create a chat token repeatedly, to keep a valid token at all times so the client is not disconnected. */ async function createChatToken(params) { const ivs = new AWS.Ivschat(); const result = await ivs.createChatToken(params).promise(); console.log("New token created", result.token); /* If the duration is 60 seconds or less (minimum allowed), generate a new token every 30 seconds. Otherwise, generate a new token every duration minus 60 seconds. */ const regenerateFrequencyInSeconds = params.duration <= 60 ? 30 : params.duration - 60; setTimeout(() => createChatToken(params), regenerateFrequencyInSeconds*1000); } /* Create a token with provided inputs. Values for user ID and display name are from your application and refer to the user connected to this chat session. */ const params = { "attributes": { "displayName": "DemoUser", }", "capabilities": ["SEND_MESSAGE"], "roomIdentifier": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6", "userId": 11231234 }; createChatToken(params);

CLI Instructions

Creating a chat token with the AWS CLI is an advanced option and requires that you first download and configure the CLI on your machine. For details, see the AWS Command Line Interface User Guide. Note: generating tokens with the AWS CLI is good for testing purposes, but for production use, we recommend that you generate tokens on the server side with the AWS SDK (see instructions above).

  1. Run the create-chat-token command along with room identifier and user ID for the client. Include any of the following capabilities: "SEND_MESSAGE", "DELETE_MESSAGE", "DISCONNECT_USER". (Optionally, include session duration (in minutes) and/or custom attributes (metadata) about this chat session. These fields are not shown below.)

    aws ivschat create-chat-token --room-identifier "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6" --user-id "11231234" --capabilities "SEND_MESSAGE"
  2. This returns a client token:

    { "token": "abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234.abcd12345EFGHI67890_jklmno123PQRS567890uvwxyz1234abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234abcde", "sessionExpirationTime": "2022-03-16T04:44:09+00:00", "token Expiration Time": "2022-03-16T03:45:09+00:00" }
  3. Save this token. You will need this to connect to the chat room and send or receive messages. You will need to generate another chat token before your session ends (as indicated by sessionExpirationTime).