Deployment settings

There are some deployment wide settings that can be configured based on your requirements. Some settings should be ideally be enabled before going into production.

OAuth only deployment (Optimised costs)

Important: Enable this setting before going into production.

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.

RainMaker in china region (cn-north-1) is by default an oauth only deployment.

Feature limitations (Not supported):

1. Mutiple Identity providers
2. Email and phone number based users. Hence, Signup, password operations are disabled. (You can however use Amazon Cognito from any AWS account as an OAuth provider)
3. MFA
4. REST API gateway (HTTP API gateway is the default). For more details refer to RainMaker API URL (Base URL)
5. API rate limiting
6. Enabling or disabling identity providers per app client (Right now all are enabled)
7. User migration into RainMaker tools and Admin user management
8. ESP Insights
9. Backup and restore
10. Update superadmin user to some other email (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, 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: 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.

   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.

   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

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

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 sin-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

Phone app configurations

1. tokenUrl: {HTTP Base URL}/{Stage}/token (Swagger)

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