Skip to main content

User Pool Migration Guide

[中文版本]


ESP RainMaker has two Cognito user pools - rainmaker-user-pool and rainmaker-user-email-mobile-pool. The newer pool rainmaker-user-email-mobile-pool was introduced to support OTP-based login and phone number-based users in addition to the rainmaker-user-pool supported features. We recommend using the Email & Phone User Pool even for 3rd party and Voice Assistant integrations as it is continuously maintained. The Email User Pool will be deprecated soon.

If you already have RainMaker set up with the old pool, please follow this guide sequentially to migrate to the new pool.


1. Upgrades

1a. Backend

  • Upgrade the RainMaker Backend by following these steps

1b. Frontend

  • Upgrade the RainMaker Frontend by following these steps

2. Domain Creation

  • Create a new domain for your company by following these steps

3. Manual Third-Party Console Changes

To determine if this step applies to you, check your currently configured identity providers.

  • Log in to the RainMaker Dashboard with your admin account and go to Deployment Settings.

    Dashboard Deployment Settings

  • Go to the Identity Providers tab and toggle to the old pool.

Identity Providers

  • Note down the enabled identity providers. You will need to perform the next steps only for the enabled providers.

3a. Google

Configurations in the Google Developer Account

  • Sign in to the Google API Console with your Google developer account credentials at https://console.developers.google.com/

  • When you log in to the Google Developer Console, you will see the following screen:

Google Developer Console

  • In the Google API Console's left navigation pane, click on Credentials.

Credentials

  • You will see a list of OAuth 2.0 Client IDs:

Client ids

Client id

  • Add new URIs as shown below:
URISteps to get the value
Authorized JavaScript originsAdd <new-company-domain>.auth.<aws-region>.amazoncognito.com where <new-company-domain> is the newly created domain in step 2.
Authorized redirect URIsAdd https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/OAuth2/idpresponse where <new-company-domain> is the newly created domain in step 2.

Client id edit

  • Click on 'Save'.

Configure Google as Identity Provider via RainMaker Dashboard

  • Log in to RainMaker Dashboard with your admin account. Go to deployment settings.

Dashboard Deployment Settings

  • Go to the Identity Providers tab. Toggle to the old pool and note down the values.

Identity Providers

  • Follow these steps to add the Google provider for the new pool with the noted parameters.

3b. Apple

Configurations in the Apple Developer Account

Apple service ids

Apple service ids dropdown

  • Click on the previously configured service identifier for your app

Apple service id

  • Click on Configure

Apple service id configure

  • Click on the + icon next to Website URLs

  • Add new URIs as shown below:

URLSteps to get the value
Domains and SubdomainsAdd <new-company-domain>.auth.<aws-region>.amazoncognito.com where <new-company-domain> is the newly created domain in step 2.
Return URLsAdd https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/OAuth2/idpresponse where <new-company-domain> is the newly created domain in step 2.

Apple service id add url

  • Click on Next and Done.

  • Click on Continue

Apple service id configure1

  • Hit Save

Apple service id configure2

Configure Apple as Identity Provider via RainMaker Dashboard

  • Log in to RainMaker Dashboard with your admin account. Go to deployment settings.

Dashboard Deployment Settings

  • Go to the Identity Providers tab. Toggle to the old pool and note down the values.

Identity Providers

  • Follow these steps to add the Apple provider for the new pool with the noted parameters. (Note: You will have to download the key file from the Apple developer console.)

  • On the RainMaker dashboard, in the Deployment Settings tab, go to the Cognito Configurations tab.

  • Confirm if the enabled identity providers and callback URLs are correct (Android URI and iOS URI)

appclient


4. Cognito App Client Configurations

  • Log in to RainMaker Dashboard with your admin account. Go to deployment settings. Dashboard Deployment Settings

  • Go to the Identity Configurations tab. Toggle to the old pool and note down the 'Enabled Identity Providers' and 'Callback URLs'

Cognito Configuration Old pool

  • Replicate the above notes values for the new pool by toggling to the 'Email & Phone User Pool' tab.

  • Done


5. Email template configuration

  • Log in to RainMaker Dashboard with your admin account. Go to deployment settings. Dashboard Deployment Settings

  • Go to the Email configurations tab. Toggle to the old pool and note down the values.

Email template old pool

  • Follow these steps to configure the email template for the new pool with the noted parameters.

6. Skills upgrade

  • Go to the AWS dashboard and search for Serverless Application Repository or SAR.

  • Go to Private applications and click on the check-box - Show apps that create custom IAM roles or resource policies

SAR Private Application

  • Search for ESP-RainMaker-3p-CognitoClients.

ESP-RainMaker-3p-CognitoClients SAR Application

  • In a new Browser tab open the "Cloudformation" service. Ensure that the region is us-east-1.

  • Toggle the "View Nested" button.

  • Search for stack name "serverlessrepo-ESP-RainMaker-3p-CognitoClients".

  • Go to the parameters section of the Cloudformation stack.

Cognito client cfn

  • Go back to the SAR service tab and check the values that are to be filled.

  • Get the value of all the Cloudformation parameters and copy the respective values in the SAR parameters.

  • Add values for the following parameters:

ParameterSteps to get the value
SkillIdentityProvidersNewUserPool- Login to the RainMaker dashboard.
- Click on the Deployment Settings tab in the left nav-bar.
- Then click on the Identity providers tab.
SAR Private Application
- Note down the Identity Providers.
- If Google, GitHub, and SignInWithApple are configured, then the corresponding values in the SkillIdentityProvidersNewUserPool while deploying the ESP-RainMaker-3p-CognitoClients SAM Application will be Google, GitHub, SignInWithApple, COGNITO. Note: If no identity provider is configured, then the default value will be set to only COGNITO.
- Enter the identity providers to be configured noted down in the previous step
  • Click on Deploy.

7. Manual Skills console config changes and recertification

7a. Alexa

  • Login to the Alexa Developer console.

  • Select the skill created previously.

  • Click on Account Linking in the left nav-bar.

  • Edit values for the following parameters:

ParameterSteps to get the value
Your Web Authorization URIhttps://<new-company-domain>.auth.<aws-region>.amazoncognito.com/OAuth2/authorize where <new-company-domain> is the newly created domain in step 2.
Access Token URIhttps://<new-company-domain>.auth.<aws-region>.amazoncognito.com/OAuth2/token where <new-company-domain> is the newly created domain in step 2.
Your Client ID and Your SecretGet values from the Alexa client esp-rainmaker-alexa-skill by following these steps and copy the esp-rainmaker-alexa-skill client details

Alexa console account linking

  • After this, you will have to recertify the skill by following this guide.

7b. Google Voice Assistant

GVA Action Account Linking


8. Mobile apps configuration

8a. Android

Configuration keyTypeSteps to get the value
authUrlStringOAuth URL. https://<new-company-domain>.auth.<aws_region>.amazoncognito.com/OAuth2 where <new-company-domain> is the newly created domain in step 2.
clientIdStringUniquely identifies an app in a user pool. Check steps to get the Client ID
alexaRMClientId (*If you have Alexa set up)StringRefer section Steps to get Alexa and GVA client ID and copy the esp-rainmaker-alexa-skill client id
  • After this, you will have to republish the app on the play store.

8b. iOS

KeyTypeSteps to get the value
App Client IDStringUniquely identifies an app in a user pool. Check steps to get the Client ID
Authentication URLStringOAuth URL. https://<new-company-domain>.auth.<aws_region>.amazoncognito.com/OAuth2 where <new-company-domain> is the newly created domain in step 2.
Alexa RM Client Id (*If you have Alexa set up)StringRefer section Steps to get Alexa and GVA client ID and copy the esp-rainmaker-alexa-skill client id
  • After this, you will have to republish the app on the app store.

Effects of migrating to new user pool

If you have set up Alexa skill app-to-app account linking using the old user pool, the migration of Alexa skill to new user pool will be seamless for users who have updated their apps.

However, if users have not updated their apps and are still using the older versions with configurations for the old pool, they will experience failure in the app-to-app account linking process. This can be resolved by updating the app to the latest version.

Existing linked accounts will remain linked without any difficulties.

You can ask all the users to update the app to avoid the above issue.

On this page