Deployment settings

There are some deployment wide settings that can be configured based on your requirements. Please understand the implications before enabling.

OAuth only deployment

An alternative cost-effective solution for identity management based on the standard OAuth 2.0 protocol which allows just social logins. This uses Amazon Cognito Identity pool instead of User pool. This changes a lot of configuration on the client side. All RainMaker functionality is supported except the below list.

caution

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

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 (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, private_key_jwt
8. State

note

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: Login using the API using HTTP Base URL from the deployment details email sent to the superadmin. You will get an accesstoken in response to this. This will be required in the 'Authorization' header of all further API requests.

note

Please note if you change your password before this step anytime, you will have to do 'forgot password' again after enabling OAuth_only setting and set the 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.

important

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 pre-requisite to use RainMaker, the users of your Identity provider should have an associated email or phone number. This should be embedded in the JWT IdToken, fields: email or phone_number

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

   Callback or Redirect URL to be allowed: {HTTP API Endpoint}/cognitocallback

   where:

   • HTTP API Endpoint: Follow these steps to get the URL
   important

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

   Example: Cognito as the Identity provider: 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 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 6
   • oidc_url: The OIDC issuer URL (Adding .well-known/openid-configuration should give the OIDC metadata. Ref: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata)

Verifying OAuth login works

Authorisation code grant

1. Go to a browser of your choice
2. Paste the Authorize API where 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 URI 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 grant_type: password, username, password, client Id, client secret, and identity_provider will be 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 the redirect URIs for both Android and iOS are added to Client. For more info check steps

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