Authentication

Authentication in the @espressif/rainmaker-base-sdk handles user signup and login operations. This includes registration, password-based login, OTP-based login, and OAuth-based login. For more information about ESP RainMaker, see the Introduction to ESP RainMaker.

Get Auth Instance

ESPRMBase, configured in Setting up the SDK step, provides an instance of the ESPRMAuth class through getAuthInstance method, used to handle operations related to user authentication, including login, signup, forgot password, and more.

try {
  const authInstance = ESPRMBase.getAuthInstance();
  // Use authInstance for authentication operations
} catch (error) {
  console.error("Error retrieving auth instance:", error);
}

User Signup

The user signup process involves sending a request to register a new user with a specified username and password, followed by confirming the user's account with a verification code.

Step 1: Sending Sign Up Code

To initiate the signup process, use the sendSignUpCode method:

/*
- username: The username for new user.
- password: The password for new user.
*/

try {
  const response = await authInstance.sendSignUpCode(username, password);
  console.log("Sign up code sent successfully:", response);
} catch (error) {
  console.error("Error sending sign up code:", error);
}

Step 2: Confirming Sign Up

After sending the signup code, confirm the user's account using the confirmSignUp method:

/*
- username: The username used in sendSignUpCode method.
- verificationCode: The OTP sent to the user's username
*/

try {
  const response = await authInstance.confirmSignUp(username, verificationCode);
  console.log("User confirmed successfully:", response);
} catch (error) {
  console.error("Error confirming user:", error);
}

User Sign in

Login Via Password

The user login process allows a registered user to authenticate by providing their username and password. Upon successful authentication, the user receives ESPRMUser instance for further interactions with the API.

/*
- username: The username of existing user.
- password: The password associated with that username.
*/

try {
  const userInstance = await authInstance.login(username, password);
  console.log("User logged in successfully:", userInstance);
} catch (error) {
  console.error("Error logging in user:", error);
}

---

Login via OTP

The user login process can also be carried out using one-time password (OTP). This method enhances security by requiring a verification code sent to the user.

The OTP login process consists of two steps:

1. Request Login OTP - Request a verification code
2. Login with OTP - Use the verification code to complete login

Step 1: Request Login OTP

To initiate the OTP login process, use the requestLoginOTP method:

/*
- username: The username of existing user.
*/

try {
  const sessionToken = await authInstance.requestLoginOTP(username);
  console.log("OTP requested successfully. Session token:", sessionToken);
} catch (error) {
  console.error("Error requesting OTP:", error);
}

Step 2: Login with OTP

After receiving the OTP, use the loginWithOTP method to log in:

/*
- username: The username of existing user.
- verificationCode: The OTP sent to the user's username.
- sessionToken: The session token received from requestLoginOTP method.
*/

try {
  const userInstance = await authInstance.loginWithOTP(
    username,
    verificationCode,
    sessionToken
  );
  console.log("User logged in successfully with OTP:", userInstance);
} catch (error) {
  console.error("Error logging in user with OTP:", error);
}

---

Third-Party Login

The user login process can also be carried out using third-party authentication providers via OAuth (Open Authorization). This method allows users to authenticate using third-party identity providers.

Supported OAuth Providers:

• Google
• GitHub
• SignInWithApple

OAuth Configuration Required

Before using third-party login, you must configure the following fields and adapter in the SDK initialization:

• authUrl - The authentication URL for third-party login (OAuth)
• clientId - The client ID for third-party login (OAuth)
• redirectUrl - The redirect URL for third-party login (OAuth)
• oauthAdapter - The OAuth adapter implementation for handling OAuth authentication flow

See Configuring the ESPRMBase SDK for details on how to configure these fields and adapter.

loginWithOauth

Logs in a user using OAuth by first requesting an OAuth code and then exchanging it for tokens. This method combines the functionality of requesting an OAuth code and logging in with the code.

Use the loginWithOauth method:

/*
- identityProvider: The identity provider for which to request an OAuth login code.
  Supported values: "Google", "GitHub", "SignInWithApple"
*/

try {
  const userInstance = await authInstance.loginWithOauth("Google");
  console.log("User logged in successfully with OAuth:", userInstance);
} catch (error) {
  console.error("Error logging in user with OAuth:", error);
}

Parameters:

Parameter	Type	Description
identityProvider	string	The identity provider for which to request an OAuth login code. Supported values: "google", "github", "apple", "wechat".

Returns: Promise<ESPRMUser> - A promise that resolves to an instance of ESPRMUser containing user tokens.

note

The userInstance obtained from login operations is an ESPRMUser instance that is used for further interactions with the API. See other user management sections for more operations.