Custom Login Page

CloudBase ships a login page in each environment's static hosting. Your platform can restyle it—swap the brand, rewrite copy, adjust colors, and choose which login methods to show.

What you are changing is the login page's configuration file and image assets, not the identity authentication settings. Upload the files back to static hosting and the new page takes effect within seconds.

This suits platforms that need a consistent brand identity or want the login page to blend into their own product.

What the login page consists of

Path	Description
__auth/index.html	Shell page, about 0.5 KB. Loads the remote SSO renderer, which draws the page from the config
__auth/env/login.config.json	Login page config. Brand, colors, login methods, agreements, and access policy live here
__auth/env/<hash>.png	Logo image, referenced by the logo field
__auth/env/agreement/<hash>	Agreement text, referenced by the agreement.path field

The page is served at https://<env-domain>/__auth. __auth is the fixed path for identity authentication SSO (single sign-on) and is written when the environment is created.

Customization normally touches files under __auth/env/: the config, the logo, and—when the agreement text changes—the agreement file. The shell page needs no change.

⚠️ Do not delete files under __auth. /__auth returns 404 and login breaks. If that happens, restore the preset page on the SSO recovery page.

Configuration

The fields in login.config.json that matter:

Field	Type	Description
logo	String	Path to the logo image, usually /__auth/env/<hash>.png
backgroundColor	String	Page background color, as a hex value
miniprogram	Array	Mini program login methods. Each entry has id, label, type, and enable
web	Array	Web login methods. Each entry has id, label, type, icon, and enable; extraLink adds a helper link
agreement	Object	Agreement checkboxes. Entries in items carry label, type, value, and enable; path points to the agreement text file
userRegistry	Object	Whether users may sign up on their own
access	Object	Access policy. needLogin forces sign-in, noPermissionPolicy sets the fallback, defaultRoleId picks the role

items[].value is the identifier attached to a checkbox. The agreement text is not stored there but in the file that agreement.path points to. That path is relative to the environment domain, for example __auth/env/agreement/c3887e49bb82439bf2f0d21adac1f4b8.

The config also carries name, keepRedirectUri, showDoc, loginPage, security, plus type and maxDevice under access. The platform writes these when it saves the config. Keep them as they are.

Back up the original file before editing, and restore it to roll back. A complete config looks like this:

{
  "logo": "/__auth/env/54423064ef3ba6c1176a6a07b110cc26.png",
  "name": "",
  "backgroundColor": "#f3f3f3",
  "web": [
    {
      "id": "__password",
      "label": "Account and password",
      "type": "password",
      "enable": true,
      "extraLink": {
        "title": "Forgot account or password",
        "url": "https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/extensions/manage-system/faq.html",
        "type": "_blank"
      },
      "icon": "https://cloudcache.tencent-cloud.com/qcloud/ui/static/static_source_business/c0774b3d-2718-46b7-bb21-785e164f1ca0.svg"
    }
  ],
  "keepRedirectUri": true,
  "showDoc": false,
  "miniprogram": [
    {
      "id": "__miniprogram_phone",
      "label": "Mini program phone number authorization",
      "type": "miniprogram_phone",
      "enable": true
    }
  ],
  "agreement": {
    "enable": true,
    "items": [
      { "label": "Privacy Policy", "type": "privacy", "value": "", "enable": true },
      { "label": "User Agreement", "type": "user", "value": "", "enable": true }
    ],
    "path": "__auth/env/agreement/c3887e49bb82439bf2f0d21adac1f4b8"
  },
  "userRegistry": { "enable": false },
  "access": {
    "needLogin": true,
    "noPermissionPolicy": "to_login",
    "whiteListPageIds": "",
    "configVersion": "v2",
    "type": "env",
    "maxDevice": 1
  },
  "security": { "expiresTime": 2592000, "enableLoginStatusShare": true },
  "loginPage": "env"
}

Each type must match a login method enabled for the environment. Editing the config changes only what the page shows; it does not toggle login methods. Those are still configured under Login Methods in identity authentication.

Update flow

1. Fetch the current files: download __auth/env/login.config.json and the logo image, plus the file agreement.path points to if the agreement text changes.
2. Edit: change the config using the fields above, replace the image file for a new logo, and replace the agreement file for new agreement text.
3. Overwrite: upload the edited files back to static hosting at their original paths. A different path means the config or the agreement will not be found.
4. Verify: open https://<env-domain>/__auth in an incognito window and confirm the new page is served.

Static hosting has no build step. An uploaded file is published, so no separate deploy action is needed.

Upload options

Pick one that fits how you integrate:

Option	Action
Console	Static hosting → File management, open __auth/env/, and upload to overwrite
CLI	tcb hosting deploy ./login.config.json /__auth/env/login.config.json
COS SDK	PutObject to __auth/env/login.config.json with credentials for the static hosting bucket

For bulk updates, loop over environments. Each environment has its own __auth.

Notes

Item	Detail
Caching	Static hosting serves through CDN, so changes usually apply within tens of seconds. Verify in an incognito window
Agreement filename	The file name under agreement/<hash> is generated by the platform and differs each time. Never hardcode it—edit through the path in agreement.path
Gateway route	Do not use a wildcard domain (domain: "*") for HTTP gateway routes—it intercepts the __auth path and the page stops loading
Whole-page swap	The shell page can be replaced entirely, but it loads the remote renderer and the content still comes from the config. Later platform upgrades may overwrite it, so this is not recommended
Secrets	The login page is frontend code. Never put SecretId, AppSecret, or any other secret in the config
Cloud app API	DescribeCloudAppCosInfo targets cloud apps (build services). __auth is not a cloud app service, so it cannot upload the login page

Related

• Login methods
• Static hosting overview
• Static hosting file management