Deployment Settings

caution

This is relevant for China deployment.
RainMaker in China region (cn-north-1) is by default an OAuth-only deployment.
The "OAuth-only deployment" mentioned in this section has no relation to setting up 3rd party logins

This setting is not for existing customers. Please read all the Feature limitations, as this action cannot be reversed.

OAuth-only Deployment

There are some deployment-wide settings that can be configured based on your requirements. This is an alternative solution for identity management based on the standard OAuth 2.0 protocol, which allows only social logins. It uses an Amazon Cognito Identity pool instead of a User pool, leading to a lot of configuration changes on the client side. All RainMaker functionality is supported except for the features listed below.

Feature limitations:

1. Phone app Sign up and Login experience: The native app experience of logging in with username and password will be replaced with a pop-up URL redirected to browser. This will be fine if you plan to use standard social identity providers as they always require browser. However, username password based users will be impacted.
2. Mutiple Identity providers are not supported for Voice assistant account linking.
3. Email and phone number based users cannot be directly created. Hence, Signup, password operations are disabled. (You can however use Amazon Cognito from any AWS account or any other standard OIDC provider which support such users.)
4. Admin user management: MFA is unsupported. Also, standard APIs and Cloud to Cloud based APIs aren't supported.
5. REST API gateway is unavailable (HTTP API gateway is the default). For more details refer to RainMaker API URL (Base URL). As a result, API rate limiting is also unavailable.
6. Enabling or disabling identity providers per app client (Right now all are enabled) is not customisable.
7. ESP Insights is unsupported for now.
8. Superadmin user email cannot be updated. (Swagger)

OAuth Limitations (not implemented yet):

1. Implicit grant and password grant (legacy and less secure)
2. Client credentials grant
3. Device code grant
4. PKCE
5. Scope restriction (Just OpenID supported for now)
6. Token revocation
7. Client Authentication: client_secret_jwt and private_key_jwt
8. State

If you require support for any of the above features, get in touch with the RainMaker support team (esp-rainmaker-support@espressif.com).

Steps to Enable

1. Login: To log in via the API, use the HTTP Base URL provided in the deployment details email sent to the Superadmin user. You will receive an access token in response, which must be included in the Authorization header for all subsequent API requests.

   Please note that if you change your password at any point before this step, you will have to use the Forgot Password option again after enabling the oauth_only setting to reset your password.

2. Enable setting: Call the Deployment settings API to enable oauth_only to true.

3. Now like standard OAuth 2.0, we can add any OIDC compliant providers like Google, Apple, or Amazon Cognito.

   How to know if an Identity provider is OIDC compliant?
   There should be a discovery URL like: .well-known/openid-configuration. Examples:

   • Google: https://accounts.google.com/.well-known/openid-configuration
   • Apple: https://appleid.apple.com/.well-known/openid-configuration
   • Facebook: https://www.facebook.com/.well-known/openid-configuration

Important

As a prerequisite for using RainMaker, the users of your identity provider should have an associated email or phone number. This should be embedded in the JWT ID token, in the email or phone_number fields.

4. Create OAuth client in the Identity provider of your choice:

   The callback URL or redirect URL to be allowed: {HTTP API Endpoint}/cognitocallback

   where:

   • HTTP API Endpoint can be achieved by following these steps.

   Important: RainMaker users require an email ID or phone number. Hence make sure you allow the scope giving access to this information.

   Example: Steps for Cognito can be accessed here. If using Cognito as the identity provider, make sure you include aws.cognito.signin.user.admin in the scope. This is to support the change password feature out of the box for Cognito users.

   By the end of this step, you will have a client ID (or App ID) and a secret from the Identity provider console.

5. Add provider to RainMaker:

   Apple and Google have in built support and can be directly added.

   • Adding Google as an Identity provider in RainMaker
   • Adding Apple as an Identity provider in RainMaker

   For others, use the API. Refer example OIDC provider (OAuth-only deployment).

   where:

   • client_id and client_secret fetched from step 4.
   • oidc_url: The OIDC issuer URL. Appending .well-known/openid-configuration to this URL should return the OIDC metadata. For reference, see here.

Verifying OAuth Login Works

1. Go to a browser of your choice.
2. Paste the Authorize API. Client ID and redirect URL can be fetched from the dashboard using steps and the identity_provider will be the provider name you configured above.
3. The Identity provider sign-in page should open. Login.
4. You should get a code on the redirect URL in the browser now (Inspect the page if required).
5. Now call the Token API with the grant_type: authorization_code, code and other parameters.
6. You should receive success response with tokens.

Resource Owner Password Credentials (ROPC) Grant

1. Call the Token API with the following parameters: grant_type as password, username, password, client_id, client_secret, and identity_provider (the provider name you configured above).
2. You should receive success response with tokens.

Phone App Configurations

1. tokenUrl: {HTTP Base URL}/{Stage}/token (Swagger).
2. Verify that the redirect URIs for both Android and iOS are added to the client. For more information, refer to the steps.

Please get in touch with the ESP RainMaker support team (esp-rainmaker-support@espressif.com) for more information.