Custom Login

Developers can use custom login to issue custom login credentials Ticket with a 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.

Version Information

• Login Authentication (v2) applies to @cloudbase/js-sdk@2.x version
• If you are using SDK version 1.x, please refer to Login Authentication (v1)
• v2 version currently does not support Official Account login. If you need to use this method, please use the v1 version

This document will introduce using the V2 version.

Applicable Scenarios

Custom login is generally used in the following scenarios:

• Developers want to associate their own account system with CloudBase accounts in a one-to-one manner;
• Developers wish to take over the authentication process themselves.

Steps Overview

Custom login involves 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, and return it to the client;
3. The client-side SDK uses the Ticket to log in to CloudBase.

Preparatory Actions

Obtain the custom login private key

1. Go to CloudBase/Authentication
2. In the login methods list, select the custom login method, click "Go to Settings" to enable custom login, then click to download the 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; it must be securely stored to prevent leakage.
2. Each time a private key file is generated, it will invalidate all previously generated private key files within 2 hours.

Issue Ticket

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

Node.js

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

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

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

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

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

Note

customUserId should meet the following requirements:

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

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.

Registration Process

When using custom login, user management is entirely handled by developers. In CloudBase, custom login doesn't require a separate registration process; corresponding CloudBase users are automatically created when users first authenticate with custom login.

Registration process mainly includes:

1. Create a user account in your user system.
2. Use the CloudBase server-side SDK to issue a Ticket for the user.
3. The client completes the initial login using the Ticket (at which time CloudBase automatically creates the corresponding user).

Login Flow

After the client application obtains the Ticket, it can call the client SDK method to log in to CloudBase:

Auth.setCustomSignFunc is used to obtain the ticket for custom login.

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

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

const auth = app.auth();

async function login() {
    const loginState = auth.hasLoginState();
    // 1. It is recommended to check whether you are already logged in before logging in.
    if (!loginState) {
        // 2. Request the developer's service API to obtain the ticket.
        await auth.setCustomSignFunc(() => {
            // Get and return the ticket.
            return Promise.resolve( /* ticket */ );
        })
        // 3. Log in to CloudBase
        await auth.signInWithCustomTicket();
    }
}

login();

The overall process is 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.