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 the 3rd party and Voice assistant integrations as it is continually maintained. The Email User Pool will get 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 RainMaker Backend by following these steps
1b. Frontend
- Upgrade 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 check if this step applies to you, you'll have to check the currently configured identity providers.
Log in to RainMaker Dashboard with your admin account. Go to deployment settings.
Go to the Identity Providers tab. Toggle to the old pool.
- Note down the identity providers enabled, you 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 using the URL - https://console.developers.google.com/.
When you login to the Google Developer console, the below screen is displayed.
- In the Google API Console, in the left navigation pane, click on Credentials.
- You will see a list of OAuth 2.0 Client IDs
- Select the client which you had created while configuring Google sign-in for the first time
- Add new URIs as shown below:
| URI | Steps to get the value |
|---|---|
| Authorized JavaScript origins | Add <new-company-domain>.auth.<aws-region>.amazoncognito.com where <new-company-domain> is the newly created domain in step 2. |
| Authorized redirect URIs | Add https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/idpresponse where <new-company-domain> is the newly created domain in step 2. |
- Click on 'Save'.
Configure Google as Identity Provider via RainMaker Dashboard
- Log in to RainMaker Dashboard with your admin account. Go to deployment settings.
- Go to the Identity Providers tab. Toggle to the old pool and note down the values.
- Follow these steps to add the Google provider for the new pool with the noted parameters.
3b. Apple
Configurations in the Apple Developer Account
Sign in to the Apple developer Console with your Apple developer account credentials using the URL - https://developer.apple.com/account/resources/certificates/list.
Go to Identifiers and select Service IDs
- Click on the previously configured service identifier for your app
- Click on Configure
Click on the + icon next to Website URLs
Add new URIs as shown below:
| URL | Steps to get the value |
|---|---|
| Domains and Subdomains | Add <new-company-domain>.auth.<aws-region>.amazoncognito.com where <new-company-domain> is the newly created domain in step 2. |
| Return URLs | Add https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/idpresponse where <new-company-domain> is the newly created domain in step 2. |
Click on Next and Done.
Click on Continue
- Hit Save
Configure Apple as Identity Provider via RainMaker Dashboard
- Log in to RainMaker Dashboard with your admin account. Go to deployment settings.
- Go to the Identity Providers tab. Toggle to the old pool and note down the values.
- 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)
4. Cognito App Client Configurations
Log in to RainMaker Dashboard with your admin account. Go to deployment settings.
Go to the Cognito Configurations tab. Toggle to the old pool and note down the 'Enabled Identity Providers' and 'Callback URLs'
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.
Go to the Email configurations tab. Toggle to the old pool and note down the values.
- 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
- Search for ESP-RainMaker-3p-CognitoClients.
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.
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:
| Parameter | Steps 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.  - 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 SAR 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:
| Parameter | Steps to get the value |
|---|---|
| Your Web Authorization URI | https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/authorize where <new-company-domain> is the newly created domain in step 2. |
| Access Token URI | https://<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 Secret | Get values from the Alexa client esp-rainmaker-alexa-skill by following these steps and copy the esp-rainmaker-alexa-skill client details |
- After this, you will have to recertify the skill by following this guide.
7b. Google Voice Assistant
Login to Google Actions Console
Go to the Develop tab of your action
Go to the account linking section
- Edit values for the following parameters:
| Parameter | Steps to get the value |
|---|---|
| Client ID and Client secret | Refer section Getting the Client ID and Client Secret for Alexa Skill and Google Action and copy the esp-rainmaker-google-action client details |
| Authorization URL | Add https://<new-company-domain>.auth.<aws-region>.amazoncognito.com/oauth2/authorize where <new-company-domain> is the newly created domain in step 2. |
| Token URL |
 |
- After this, you will have to:
8. Mobile apps configuration
8a. Android
Open your RainMaker project in Android Studio (Pull and rebase with the latest source code - https://github.com/espressif/esp-rainmaker-android)
In your local.properties file, edit values for the following configuration fields.
| Configuration key | Type | Steps to get the value |
|---|---|---|
| authUrl | String | OAuth URL. https://<new-company-domain>.auth.<aws_region>.amazoncognito.com/oauth2 where <new-company-domain> is the newly created domain in step 2. |
| clientId | String | Uniquely identifies an app in a user pool. Check steps to get the Client ID |
| alexaRMClientId (*If you have Alexa set up) | String | Refer 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
Open your RainMaker project in Xcode (Pull and rebase with the latest source code - https://github.com/espressif/esp-rainmaker-ios)
In the Configuration.plist file, edit values for the following configuration fields.
| Key | Type | Steps to get the value |
|---|---|---|
| App Client ID | String | Uniquely identifies an app in a user pool. Check steps to get the Client ID |
| Authentication URL | String | OAuth 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) | String | Refer 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.