Set up Amplify PubSub

The AWS Amplify PubSub category provides connectivity with cloud-based message-oriented middleware. You can use PubSub to pass messages between your app instances and your app's backend creating real-time interactive experiences.

PubSub is available with AWS IoT and Generic MQTT Over WebSocket Providers.

AWS IoT

When used with AWSIoTProvider, PubSub is capable of signing request according to Signature Version 4.

To use in your app, import AWSIoTProvider:

1import { Amplify, PubSub } from 'aws-amplify';
2import { AWSIoTProvider } from '@aws-amplify/pubsub';

Define your endpoint and region in your configuration:

1// Apply plugin with configuration
2Amplify.addPluggable(
3  new AWSIoTProvider({
4    aws_pubsub_region: '<YOUR-IOT-REGION>',
5    aws_pubsub_endpoint:
6      'wss://xxxxxxxxxxxxx.iot.<YOUR-IOT-REGION>.amazonaws.com/mqtt'
7  })
8);

Find your aws_pubsub_endpoint by logging onto your AWS Console, choosing IoT Core from the list of services and then choosing Settings from the left navigation pane.

Step 1: Create IAM policies for AWS IoT

To use PubSub with AWS IoT, you will need to create the necessary IAM policies in the AWS IoT Console, and attach them to your Amazon Cognito Identity.

Go to IoT Core and choose Security from the left navigation pane, and then Policies from the dropdown menu. Next, click Create. The following myIoTPolicy policy will allow full access to all the topics.

Step 2: Attach your policy to your Amazon Cognito Identity

The next step is attaching the policy to your Cognito Identity.

You can retrieve the Cognito Identity Id of a logged in user with Auth Module:

1Auth.currentCredentials().then((info) => {
2  const cognitoIdentityId = info.identityId;
3});

Then, you need to send your Cognito Identity Id to the AWS backend and attach myIoTPolicy. You can do this with the following AWS CLI command:

1aws iot attach-policy --policy-name 'myIoTPolicy' --target '<YOUR_COGNITO_IDENTITY_ID>'

Step 3: Allow the Amazon Cognito Authenticated Role to access IoT Services

For your Cognito Authenticated Role to be able to interact with AWS IoT it may be necessary to update its permissions, if you haven't done this before.
One way of doing this is to log to your AWS Console, select CloudFormation from the available services. Locate the parent stack of your solution: it is usually named <SERVICE-NAME>-<CREATION_TIMESTAMP>.
Select the Resources tab and tap on AuthRole Physical ID.
The IAM console will be opened in a new tab. Once there, tap on the button Attach Policies, then search AWSIoTDataAccess and AWSIoTConfigAccess, select them and tap on Attach policy.

If you are using Cognito Groups, the IAM role associated with that group also need the AWSIoTDataAccess and AWSIoTConfigAccess policies attached to it.

Failing to grant IoT related permissions to the Cognito Authenticated Role will result in errors similar to the following in your browser console: errorCode: 8, errorMessage: AMQJS0008I Socket closed.

Third Party MQTT Providers

Import PubSub module and related service provider plugin to your app:

1import { PubSub } from 'aws-amplify';
2import { MqttOverWSProvider } from '@aws-amplify/pubsub/lib/Providers';

To configure your service provider with a service endpoint, add following code:

1// Apply plugin with configuration
2Amplify.addPluggable(
3  new MqttOverWSProvider({
4    aws_pubsub_endpoint: 'wss://iot.eclipse.org:443/mqtt'
5  })
6);

You can integrate any MQTT Over WebSocket provider with your app. Click here to learn more about MQTT Over WebSocket.

How to reconfigure PubSub providers during runtime

Sometimes you need to reconfigure your PubSub provider when working with multiple concurrent PubSub providers, reconfiguring authentication states, or changing the IoT connection region. To reconfigure the PubSub provider, remove the existing provider using removePluggable and add an updated PubSub provider using addPluggable.

1import { Amplify, PubSub } from 'aws-amplify';
2import { AWSIoTProvider } from '@aws-amplify/pubsub';
3
4// Apply plugin with configuration
5PubSub.addPluggable(
6  new AWSIoTProvider({
7    aws_pubsub_region: '<ORIGINAL-IOT-REGION>',
8    aws_pubsub_endpoint:
9      'wss://xxxxxxxxxxxxx.iot.<ORIGINAL-IOT-REGION>.amazonaws.com/mqtt'
10  })
11);
12
13// Remove plugin using the provider name
14PubSub.removePluggable('AWSIoTProvider');
15
16// Apply plugin with new configuration
17PubSub.addPluggable(
18  new AWSIoTProvider({
19    aws_pubsub_region: '<NEW-IOT-REGION>',
20    aws_pubsub_endpoint:
21      'wss://xxxxxxxxxxxxx.iot.<NEW-IOT-REGION>.amazonaws.com/mqtt'
22  })
23);