Custom Login

Developers can use custom login to issue custom login credentials Ticket with custom identity ID for users on their own servers or in cloud functions, then the client-side SDK can use the Ticket to log in to CloudBase.

Applicable Scenarios

Custom login is generally used in the following scenarios:

• Developers wish to establish a one-to-one mapping between their own account system and CloudBase accounts.
• Developers wish to take over the authentication process themselves.

Steps Overview

Custom login requires the following steps:

1. Obtain the CloudBase custom login private key
2. Use the CloudBase server-side SDK to sign and issue a Ticket with the private key, then return it to the client.
3. The client-side SDK uses the Ticket to log in to CloudBase.

Step 1: Obtain the custom login private key

Log in to the CloudBase console. Under Environment -> Login Authorization, in the Custom login section, click Private Key Download or Copy Private Key:

The private key is a file containing JSON data. Save the downloaded or copied private key file to your server or cloud function, assuming the path is /path/to/your/tcb_custom_login.json.

Note

1. The private key file is a critical credential for verifying administrator identity; ensure it is stored securely to prevent leakage.
2. Each time a private key file is generated, it invalidates the previously generated private key file after 2 hours.

Step 2: Issue a Ticket

Call the CloudBase server-side SDK, pass in the custom login private key during initialization, then issue a Ticket and return it to the client.

Node.js

const cloudbase = require("@cloudbase/node-sdk");

// 1. Initialize the SDK
const app = cloudbase.init({
  env: "your-env-id",
  // Pass in the custom login private key
  credentials: require("/path/to/your/tcb_custom_login.json")
});

// 2. Developer-defined unique user identity identifier
const customUserId = "your-customUserId";

// 3. Create a ticket
const ticket = app.auth().createTicket(customUserId);

// 4. Return the ticket to the client
return ticket;

tip

Developers can also write a cloud function to generate Tickets, set up an HTTP access service for it, then clients can obtain Tickets via HTTP requests. For detailed instructions, refer to Using HTTP to Access Cloud Functions.

Note

customUserId must meet the following requirements:

• 4-32 characters;
• Characters can only be uppercase and lowercase English letters, digits, and the characters in _-#@(){}[]:.,<>+#~.

Step 3: Use the Ticket to log in to CloudBase

After the client application obtains the Ticket, it can call the auth.signInWithTicket() method provided by the client SDK to log in to CloudBase:

import cloudbase from '@cloudbase/js-sdk';

const app = cloudbase.init({
  env: 'your-env-id'
});

const auth = app.auth();

async function login(){
  const loginState = await auth.getLoginState();
  // 1. It is recommended to check whether the user is already logged in before logging in
  if(!loginState){
    // 2. Request the developer's own service interface to get the ticket
    const ticket = await fetch('...');
    // 3. Log in to CloudBase
    await auth.customAuthProvider().signIn(ticket);
  }
}

login();

The overall process is illustrated as follows:

Frequently Asked Questions

Do I need to set up my own server to create a Ticket for custom login?

Custom login requires a service to create a Ticket, but developers do not necessarily have to set up their own servers.

Developers can also write a cloud function to create Tickets, then clients can call this cloud function via HTTP requests to obtain Tickets. For details, refer to Accessing Cloud Functions via HTTP.