Skip to main content

Configurations

About

Welcome to the post deployment section, the last stage in the deployment of Private RainMaker. 🚀 This section should be reviewed only when deployment of RainMaker Services have been successfully completed.
As there are differences in the deployment of Private RainMaker between China and the global region. Two tabs are displayed to distinct global and China region. Please select the relevant tab based on the region of your deployment.

On this page

Configure Amazon Cognito to Use SES as its Email Provider Instead of the Default Cognito Sender Address​

tip

If end users are still receiving emails from no-reply@verificationemail.com despite configuring a verified SES email address, follow the steps below to resolve this issue.

Here are the steps to correctly configure the SES email provider for your Cognito user pool:

  1. Access Amazon Cognito.

    • Open Amazon Cognito in the AWS console.
    • Select your user pool (e.g., rainmaker-user-email-mobile-pool).
    • Click Messaging in the menu list.

    SES_mail_configure1

  2. Check Email provider settings.

    • In the Email provider section, review the current configuration and the email address used to send emails.
    • Ensure that Send email with Amazon SES is selected as the email provider.

  3. Configure the SES Email Address.

    • Select an email address from the verified list in Amazon SES.
    • Click Save Changes to apply the new configuration.

    SES_mail_configure2

By completing these steps, emails should be sent from the specified SES email address instead of the default no-reply@verificationemail.com.

Configure SES to Send Email​

About

When a new user is created, RainMaker sends an email notification to the end-users, which contains a verification code. By default Amazon Cognito is used to send these email notifications. However, Amazon Cognito's default email service limits the number of emails sent to 50 per day. This includes all types of emails, such as verification codes sent during user sign-up or password recovery. Therefore, Amazon SES needs to be configured for sending the email notifications to the user instead of relaying on Amazon Cognito. By using SES, it can also support message customizations.

Note

This feature is not supported for OAuth-only RainMaker yet.

Follow these steps to configure SES to send emails:

  1. Log in to the RainMaker dashboard with Superadmin credentials.
  2. Go to the Deployment Settings tab.
  3. Click Email Configurations.

message_template

  1. Enter the email subject.
  2. Choose an email address for sending emails.
  3. Enter your name for From Username.
  4. Enter email body in Template.
  5. Click Set Email Template.
  6. You will get a success message as shown below:

message_template3

Configure the Email Template for Verification Messages​

About

When the user signs up, the RainMaker platform sends them an email containing a verification code. This verification code must be used to confirm accounts when logging in using the mobile Apps. You can customize the email template from the RainMaker dashboard, but admin privileges are required to make changes to the template.

Follow these steps to configure email template for verification messages:

  1. Log in to the RainMaker dashboard using your Admin account credentials.
  2. Click Deployment Settings.
  3. Click the Email Configurations tab.

configure2

  1. Keep the template type as Welcome Email Notification.
    • You can change the Subject of the Email.
    • You can change the Template, as per your requirement. This template can be simple text or a valid HTML.
    • Please note that you will need to have the string {####} in the template. This is a placeholder string, which is filled by the AWS service with the verification code.
  2. After your changes are done, click Set Email Template.

configure3

info

With this setup, the verification email sent to new users will use the customized template.

Configure Cognito Domain​

about

Cognito domain is required for implementing sign-in using third party identity providers (e.g., Google, Apple) and for linking your Alexa or Google Voice Assistants account with your RainMaker account.
The Cognito domain is used to form the URL of sign-in and sign-up webpages, that are used for third party identity providers and voice assistant integrations.

info

This is not relevant for OAuth-only RainMaker.

Follow these steps to configure the Cognito domain name:

  1. Log in to RainMaker dashboard with Superadmin credentials.
  2. Go to Deployment Settings tab.
  3. Go to Identity Configurations tab.
  4. Enter the value for the custom domain name as shown below:

customdomain

note

Cognito domain names can only contain lower-case letters, numbers, and hyphens.

  1. Click Save and refresh the page to view the full URL if it is not generated automatically.

customdomain_2

Configure Cognito Callback URL (Optional)​

about

The callback URLs are needed while using the third party authenticating services and linking your account in Alexa/Google Voice Assistants with your account in RainMaker. After successful sign-in, users are redirected to one of the URLs specified in callback URLs.

Follow these steps to configure the Callback URLs are given below:

  1. Log in to RainMaker dashboard with Superadmin credentials.
  2. Go to Deployment Settings tab.
  3. Go to Cognito Configurations tab.
  4. Enter your callback URLs as shown below. Multiple callback URLs can be specified by entering a comma after each URL.

appclient

Configuring Custom Cognito Domain (Optional)​

note

This is not relevant for Oauth only RainMaker

1. Create ACM certificate​

AWS Certificate Manager (ACM) handles the complexity of creating, storing, and renewing public and private SSL/TLS X.509 certificates and keys that protect your AWS websites and applications. You can provide certificates for your integrated AWS services either by issuing them directly with ACM or by importing third-party certificates into the ACM management system.

  1. Sign in to the AWS console & search for AWS Certificate Manager service.
  2. Click on Request Certificate.
  3. Select request a public certificate option & Click Next.
  4. Enter Fully qualified domain name & Click Request.

ACM_certificate

Add a CNAME record for certificate validation​

In this step, you create a CNAME record in Route53 using the CNAME name and CNAME value from the previous step to validate your SSL certificate.

  1. Sign in to the Route 53 console.
  2. In the navigation pane, choose Hosted zones.
  3. Select the hosted zone for your domain.
  4. Choose Create record.
  5. For Record name, enter the CNAME name (without your domain name, as Route53 will append it automatically).
  6. For Record type, select CNAME.
  7. For Value, enter the CNAME value copied from the ACM certificate.
  8. Keep TTL as default (300 seconds).
  9. Ensure that Alias is not selected/ticked.
  10. Choose Create records.
  11. Wait for approximately 30 minutes for your certificate status to move from "Pending validation" to "Issued" (verified).
note

The CNAME record type is used for certificate validation and should not have the alias option enabled.

2. Creating a custom domain and adding it to the user pool​

Here, you need to enter a custom domain name & select ACM certificate from the drop down arrow that we created in then previous step.

  1. Sign in to the Amazon Cognito console.
  2. Click User pools.
  3. Choose the rainmaker-user-email-mobile-pool to which you want to add your domain.
  4. Click on the App integration tab.

create_custom_domain_1

  1. Next to Domain, choose Actions, then choose Create custom domain.
  2. For Custom domain, enter the URL of the domain you want to use with Amazon Cognito. Your domain name can include only lowercase letters, numbers, and hyphens. Do not use a hyphen for the first or last character. Use periods to separate subdomain names.
  3. For ACM certificate, choose the SSL certificate that you want to use for your domain. Only ACM certificates in US East (N. Virginia) are eligible to use an Amazon Cognito custom domain, regardless of the AWS region of your user pool.
  4. Click on Create.

create_custom_domain_2

  1. Amazon Cognito returns you to the App integration tab. A message titled Create an alias record in your domain's DNS is displayed. Note down the Domain and Alias target displayed in the console. They will be used in the next step to direct traffic to your custom domain.

3. Add an alias target and subdomain​

In this step, you set up an alias through your Domain Name Server (DNS) service provider that points back to the alias target from the previous step.

A) To add an alias target and subdomain to your current DNS configuration​
  • If you aren't using Route 53 for DNS address resolution, then you must use your DNS service provider's configuration tools to add the alias target from the previous step to your domain's DNS record. Your DNS provider will also need to set up the subdomain for your custom domain.
B) To add an alias target and subdomain using Route 53​

If you aren't using Route 53 for DNS address resolution, then you must use your DNS service provider's configuration tools to add the alias target from the previous step to your domain's DNS record. Your DNS provider will also need to set up the subdomain for your custom domain.

  1. Sign in to the Route 53 console.
  2. If you don't have a hosted zone in Route 53, you must create one using the following steps. Otherwise, continue to step 3.
    a) Choose Create Hosted Zone.
    b) Enter the parent domain
    e.g. auth.example.com, of your custom domain,
    e.g. myapp.auth.example.com, from the Domain Name list.
    c) (Optional) For Comment, enter a comment about the hosted zone.
    d) Choose a hosted zone Type of Public hosted zone to allow public clients to resolve your custom domain. Choosing Private hosted zone is not supported.
    e) Apply Tags as desired.
    f) Choose Create hosted zone.
  3. On the Hosted Zones page, choose the name of your hosted zone.
  4. Choose Create record. Add a DNS record for the parent domain and choose Create records.
    The following is an example record for the domain auth.example.com.
    auth.example.com. 60 IN A 198.51.100.1

Amazon Cognito verifies that there is a DNS record for the parent domain of your custom domain to protect against accidental hijacking of production domains. If you do not have a DNS record for the parent domain, Amazon Cognito will return an error when you attempt to set the custom domain.

  1. Choose Create record again.
  2. Enter a Record name that matches your custom domain, for example, myapp to create a record for myapp.auth.example.com.
  3. Enter the alias target name that you previously noted into Alias Target.
  4. Enable the Alias option.
  5. Choose to Route traffic to an Alias to Cloudfront distribution. Enter the Alias target provided by Amazon Cognito when you created your custom domain.
  6. Choose Create Records.

Your new records can take around 60 seconds to propagate to all Route 53 DNS servers. You can use the Route 53 GetChange API method to verify that your changes have propagated.

4. Verify your sign-in page​

Verify that the sign-in page is available on your custom domain by following these steps:

  1. Sign in to the Amazon Cognito console.
  2. Select the user pool rainmaker-user-email-mobile-pool.
  3. From the left navigation menu, click on the App clients option.
  4. Click on rainmaker-user-email-mobile-pool-client.
  5. Click on the View login page option on the right side of the client name. verify_custom_domain_1

Reference link: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-add-custom-domain.html

Configuring Custom IoT MQTT Domain (Optional)​

1. Create ACM certificate​

AWS Certificate Manager (ACM) handles the complexity of creating, storing, and renewing public and private SSL/TLS X.509 certificates and keys that protect your AWS websites and applications. You can provide certificates for your integrated AWS services either by issuing them directly with ACM or by importing third-party certificates into the ACM management system.

  1. Sign in to the AWS console & search for AWS Certificate Manager service.
  2. Click on Request Certificate.
  3. Select request a public certificate option & Click Next.
  4. Enter Fully qualified domain name
  5. Keep Default i.e Validation Method as DNS Validation and Key Algorithm as RSA 2048 & Click on Request.
  6. Copy CNAME name and CNAME value
  7. Add these records as CNAME in Route53 (see detailed steps below)

ACM_certificate

Add a CNAME record for certificate validation​

In this step, you create a CNAME record in Route53 using the CNAME name and CNAME value from the previous step to validate your SSL certificate.

  1. Sign in to the AWS console & search for Route 53 service.
  2. In the navigation pane, choose Hosted zones.
  3. Select the hosted zone for your domain.
  4. Choose Create record.
  5. For Record name, enter the CNAME name (without your domain name, as Route53 will append it automatically).
  6. For Record type, select CNAME.
  7. For Value, enter the CNAME value copied from the ACM certificate.
  8. Keep TTL as default (300 seconds).
  9. Ensure that Alias is not selected/ticked.
  10. Choose Create records.
  11. Wait for approximately 30 minutes for your certificate status to move from "Pending validation" to "Issued" (verified).
note

The CNAME record type is used for certificate validation and should not have the alias option enabled.

2. Creating an IoT MQTT custom domain​

Here, you need to create a custom domain configuration for AWS IoT and select the ACM certificate that we created in the previous step.

  1. Sign in to the AWS console & search for AWS IoT Core service.
  2. In the navigation pane, choose Domain configurations.
  3. Choose Create domain configuration.
  4. In the Domain configuration properties section:
    • For Domain configuration name, enter a unique name (e.g., esp-rainmaker-<account_id>).
    • For Select security policy, keep default IoTSecurityPolicy_TLS13_1_2_2022_10.
  5. In the Domain type section, select Customer managed domain.
  6. For Domain name, enter your custom MQTT domain (e.g., mqtt.example.com).
  7. For Server certificate, select the ACM certificate created in the previous step from the dropdown.
  8. For Validation certificate, choose the appropriate certificate if using a private certificate (optional).
  9. In the Authentication configuration section, keep default Default as the authentication type.
  10. In the Custom authorizer section, keep No custom authorizer.
  11. Click on Create domain configuration.

iot_custom_domain

  1. After creation, you can see your domain configuration listed in the Domain configurations page. Note down the Domain name from the list (e.g., ********-ats.iot.<region>.amazonaws.com) - this is your IoT Data-ATS endpoint that you'll need for the CNAME record.

3. Add CNAME record for MQTT custom domain​

In this step, you create a CNAME record in Route53 that points your custom MQTT domain to the AWS IoT Data-ATS endpoint.

Follow the same Route53 steps as described in step 1 above, but use the following values:

  • Record name: Enter the subdomain part of your MQTT custom domain (e.g., mqtt.example.com).
  • Value: Enter your AWS IoT Data-ATS endpoint (obtained from step 13 above, e.g., ********-ats.iot.<region>.amazonaws.com).
note
  • The CNAME record maps your custom MQTT domain to the AWS IoT Data-ATS endpoint
  • Make sure to use the correct IoT endpoint for your AWS region
  • DNS propagation may take a few minutes to complete

Your new CNAME record will allow MQTT clients to connect to your custom domain (e.g., mqtt.example.com) which will route to the AWS IoT endpoint.

Configure MFA (Optional)​

about

Admin users can set up multi-factor authentication (MFA) for higher security. This will send a verification code to the admin's phone number at each login.

Increase the SNS sending limit if not done already before going further.

info

This is not supported for OAuth-only RainMaker yet.

Follow these steps to configure MFA:

  1. Log in to RainMaker dashboard with your admin account.
    Go to Deployment Settings > MFA Configuration.

    configure4

  2. To add or update phone number on which you wish to receive the verification code, enter the number along with the country code and click Update.

    configure4

    tip

    You may skip step 2 and 3 if you have already added the phone number.

  3. Verify the phone number by entering the verification code sent to the updated phone number.

    configure4

  4. Your phone number is now updated. You can enable MFA using the toggle.

    configure4

    tip

    You can also disable MFA any time using the same toggle.

  5. MFA settings updated successfully.

    tip

    The settings will reflect from the next login onwards.

    If enabled, an MFA prompt will appear after the initial password authentication:

    configure4

Configure the Location-based Triggers for Weather API Configurations​

about

This process enables location-based weather triggers for automation through the integration of the OpenWeather API with RainMaker.
By configuring the API key and setting up polling intervals, devices or systems can automatically respond to weather conditions such as temperature or humidity. This enhances automation by allowing actions like turning on or off devices based on real-time weather data, providing greater customization and efficiency. It adds intelligent, dynamic responses to weather changes, improving convenience and energy management in smart environments.

Follow these steps to configure location-based weather triggers for Weather API Configurations:

  1. Create Open-Weather account
    • Begin the process by signing up for an account at https://home.openweathermap.org/users/sign_up.
    • After signing up, check your email for a verification message and follow the instructions to confirm your email address.
    • Once your email is verified, you will receive an email containing the API key, which will become active within the next couple of hours.
  1. Steps for configuring weather-based automation in RainMaker

    • In Postman, log in to RainMaker using Superadmin credentials.

      weather-API_1

    • Access and configure the deployment settings for location triggers by clicking on the following Swagger link:

      https://swaggerapis.rainmaker.espressif.com/?urls.primaryName=RainMaker%20Superadmin%20APIs#/Deployment%20Setting/cofigureServiceConfiguration

    • Under the Request body, choose Location Trigger Configurations from the dropdown list to see the sample JSON request.

      weather-API_2

    • In Postman, create a new API request.

      PUT - {{url}}/v1/admin/deployment_settings/config/location_trigger

      Follow Get Base Url steps to fetch the {{url}}.

Params
KeyValue
servicelocation_trigger
Header
KeyValue
Authorization{{access_key}}
Body

Select node_id, choose JSON from the dropdown list. Add the following JSON to the body, and click Send.

 {
    "weather_trigger_api_key": "<add_your_key>",

    "weather_trigger_polling_interval": 30,

    "weather_trigger_host_url": "https://api.openweathermap.org/data/2.5/weather?units=metric"

 }
tip

Refer to the screenshot below for an example of the required input.

weather-API_3

  1. Test the triggers

    Header
KeyValue
Authorization{{access_key}}
Body

Change the node_id value according to the node on which you want to apply automation trigger.

weather-API_5

Downgrade Cognito User Pool from Essentials to Lite Tier​

about

When downgrading a Cognito User Pool from the Essentials tier to the Lite tier, certain features exclusive to Essentials must be disabled. This ensures a seamless downgrade without errors. If you attempt to downgrade while advanced features are still enabled, you will receive a tierChangeNotAllowedException error. Follow the steps below to disable all required advanced features before confirming the tier change via API.

Note

For each step, if the advanced feature is already absent or not configured, you may skip to the next section.

Follow these steps to disable advanced features and prepare for the tier downgrade:

1. Remove Access Token Customization​

  • In the AWS Console, open your User Pool.
  • Navigate to Extensions in the left sidebar under the Authentication section.
  • If a Pre token generation Lambda trigger is enabled, select the lambda trigger and click Delete.
  • If there is no such trigger, skip further action.

cognito-tier-disable-lambda-trigger

Screenshot Reference

Look for the Triggers section showing Lambda triggers. If none are present, a screenshot showing "No triggers configured" is helpful.

2. Disable Threat Protection​

  • Open the User Pool in the AWS Console.
  • Click Threat Protection in the left sidebar under the Security section.
  • If any threat protection features (such as Advanced Security, Compromised Credentials Check, or Adaptive Authentication) are enabled, deactivate them.
  • If all options show as disabled with an option to Switch to Plus, skip further action.

cognito-tier-disable-threat-protection

Screenshot Reference

Review the Threat Protection menu with toggles to ensure all features are turned off.

3. Turn Off Log Streaming (Log Export)​

  • Open the User Pool in the AWS Console.
  • Click Log Streaming in the left sidebar under the Security section.
  • If log delivery or streaming is configured to CloudWatch or other destinations, remove these destinations.
  • If all options show as disabled with an option to Switch to Plus, skip further action.

cognito-tier-disable-log-streaming

Screenshot Reference

Check the Log Streaming menu to confirm no destinations are configured.

4. Disable Email-based MFA​

  • In the User Pool Console, select Sign-in from the left sidebar under the Authentication section.
  • Click Edit for Multi-factor Authentication.
  • If Email message is selected as an MFA method, under "Require MFA" or "Optional MFA", deselect it. Click Save changes to confirm.
  • If "Email message" is not shown or currently selected, skip further action.

cognito-tier-disable-email-mfa

Screenshot Reference

Review the MFA options screen showing "Email message" unchecked or absent.

5. Remove Password Reuse Prevention​

  • In the left sidebar, choose Authentication methods and then Password policy.
  • Check the value for Prevent use of previous passwords.
  • If the value is greater than zero, edit and set it to zero.
  • Save changes to change the option to "Allow reuse of previous passwords"
  • If an option already appears as "Allow reuse of previous passwords", skip further action.

cognito-tier-disable-password-reuse

Screenshot Reference

Review the password policy settings to confirm the password reuse prevention is set to zero.

6. Revert Managed Login (Hosted UI)​

  • In the left sidebar, click Managed login under Branding section.
  • If Managed login or advanced branding features are enabled or customised, revert to basic Hosted UI branding/settings or delete the customised managed login pages.
  • If standard Hosted UI is already used, skip further action.
Screenshot Reference

Check the Domain and UI settings showing default or basic options.

7. Disable Choice-Based Authentication​

  • In the sidebar, select Sign-in and then Options for choice-based sign-in.
  • If Passwordless status is active, click the Edit option.
  • Unselect all three provided options - Passkey Email message one-time password SMS message one-time password
  • Click Save Changes to confirm
  • If only Password based sign-in is active and Passwordless status is inactive, skip further actions.

cognito-tier-disable-passwordless-sign-in

Screenshot Reference

Review the options menu for sign-in methods to ensure only Lite-compatible methods are enabled.

Additional Notes​

Important
  • If any feature is found already absent or not configured, you may skip deactivation for that step.
  • Always verify all features are disabled before using your API to downgrade the tier.
  • Review the User Pool configuration after making changes to ensure all advanced features have been successfully disabled.
  • Once all advanced features are disabled, you can proceed with entering the verification code sent to your email to confirm the tier downgrade.

Configure the DNS Names

info

This feature is optional for Global RainMaker, but mandatory for China.

about

When the RainMaker backend and the frontend stacks are deployed successfully, you can access the API end points and the Dashboard using the URLs generated. Alternatively, you can configure to use the domain names which are specific to your organization, by configuring the Route 53 service.

Follow these steps to configure the Route 53 service:

  1. Create a hosted Zone in Route 53
  1. Map the hosted zone to the DNS registrar

  1. Map the API Gateway endpoint with the DNS name

    • Once the mapping between the hosted zone and your current DNS provider is done, you will need to configure the API Gateway endpoint to Route 53 hosted zone.
    tip

    Follow Get Base Url steps to fetch the API Gateway endpoint.

    Take note

    Please note, choose the API endpoint type as Edge.

    After the configuration is done, the API Gateway and Custom domain names configuration will be as shown:

    dns1

    The Route 53 configuration for API Gateway will be as shown:

    dns2

    dns3

  1. Configure the Domain name mapping for the RainMaker dashboard

    • When the RainMaker frontend stack is deployed, the required UI components are deployed and a CloudFront distribution is created.

    • This sets up the Content Delivery Network for caching the UI and provides SSL connectivity for the UI dashboard.

    • You can create your organization specific domain name for this, so that the admin users will be able to access the Dashboard using the domain name.

    • To check your CloudFront distribution, search for the CloudFront service from the AWS console.

      dns4 dns5

    • The steps to configure Route 53 DNS mapping for CloudFront distribution are as shown in the link below:

    After the CloudFront distribution is configured with the DNS mapping, the CloudFront screen will be as shown:

    dns7

    The following is the Route 53 screen you'll see when setting up a CloudFront distribution:

    dns8