Auth Wechat Miniprogram

Standalone Install Note

If this environment only installed the current skill, start from the CloudBase main entry and use the published cloudbase/references/... paths for sibling skills.

• CloudBase main entry: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
• Current skill raw source: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-wechat/SKILL.md

Keep local references/... paths for files that ship with the current skill directory. When this file points to a sibling skill such as auth-tool or web-development, use the standalone fallback URL shown next to that reference.

Activation Contract

Use this first when

• The task is about WeChat Mini Program auth behavior, wx.cloud identity, OPENID / UNIONID, or how a mini program caller is identified in CloudBase.
• The project is a CloudBase mini program and the auth question is about native mini program identity rather than provider configuration.

Read before writing code if

• The request mentions mini program login, user identity in cloud functions, or wx.cloud auth assumptions.
• The user expects a Web-style login page or explicit token exchange in a mini program; route them back to native mini program auth behavior.

Then also read

• Mini program project implementation -> ../miniprogram-development/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/miniprogram-development/SKILL.md)
• Cloud function implementation -> ../cloud-functions/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-functions/SKILL.md)

Do NOT use for

• Web-based WeChat login or Web auth UI.
• Provider enable/disable or auth console setup.
• Generic Node-side auth flows outside mini program identity handling.

Common mistakes / gotchas

• Generating a Web-style login page for a wx.cloud mini program.
• Treating mini program auth as a provider-configuration problem.
• Forgetting that caller identity is injected in cloud functions automatically.

When to use this skill

Use this skill for WeChat Mini Program （小程序） authentication in a CloudBase project.

Use it when you need to:

• Implement identity-aware WeChat Mini Program flows with CloudBase
• Access user identity (openid, unionid) in cloud functions
• Understand how WeChat authentication integrates with CloudBase
• Build Mini Program features that require user identification

Key advantage: WeChat Mini Program authentication with CloudBase is seamless and automatic - no complex OAuth flows needed. When a Mini Program calls a cloud function, the user's openid is automatically injected and verified by WeChat.

Do NOT use for:

• Web-based WeChat login (use the auth-web skill)
• Server-side auth with Node SDK (use the auth-nodejs skill)
• Non-WeChat authentication methods (use appropriate auth skills)

How to use this skill (for a coding agent)

1. Confirm CloudBase environment

   • Ask the user for:
     • env – CloudBase environment ID
     • Confirm the Mini Program is linked to the CloudBase environment

2. Understand the authentication flow

   • WeChat Mini Program authentication is native and automatic
   • No explicit login API calls needed in most cases
   • User identity is automatically available in cloud functions
   • CloudBase handles all authentication verification

3. Pick a scenario from this file

   • For basic user identity in cloud functions, use Scenario 2
   • For Mini Program initialization, use Scenario 1
   • For calling a cloud function from the Mini Program and receiving user identity, use Scenario 3
   • For testing authentication, use Scenario 4

4. Follow CloudBase API shapes exactly

   • Use wx-server-sdk in cloud functions
   • Use wx.cloud in Mini Program client code
   • Treat method names and parameter shapes in this file as canonical

5. If you're unsure about an API

   • Consult the official CloudBase Mini Program documentation
   • Only use methods that appear in official documentation

Core concepts

How WeChat Mini Program authentication works with CloudBase

1. Automatic authentication:

   • When a Mini Program user calls a cloud function, WeChat automatically injects the user's identity
   • No need for complex OAuth flows or token management
   • CloudBase verifies the authenticity of the identity

2. User identifiers:

   • OPENID – Unique identifier for the user in this specific Mini Program
   • APPID – The Mini Program's App ID
   • UNIONID – (Optional) Unique identifier across all apps under the same WeChat Open Platform account
     • Only available when the Mini Program is bound to a WeChat Open Platform account
     • Useful for identifying the same user across multiple Mini Programs or Official Accounts

3. Security:

   • The openid, appid, and unionid are verified and trustworthy
   • WeChat has already completed authentication
   • Developers can directly use these identifiers without additional verification

4. No explicit login required:

   • Users are automatically authenticated when they use the Mini Program
   • No need to call login APIs in most cases
   • Identity is available immediately in cloud functions

Scenarios – WeChat Mini Program auth patterns

Scenario 1: Initialize CloudBase in Mini Program

Use this in your Mini Program's app.js or entry point:

// app.js
App({
	onLaunch: function () {
		// Initialize CloudBase
		wx.cloud.init({
			env: "your-env-id", // Your CloudBase environment ID
			traceUser: true, // Optional: track user access in console
		});
	},
});

Key points:

• Call wx.cloud.init() once when the Mini Program launches
• Set env to your CloudBase environment ID
• traceUser: true enables user access tracking in CloudBase console (optional but recommended)

Scenario 2: Get user identity in a cloud function

Use this when you need to know who is calling your cloud function:

// Cloud function: cloudfunctions/getUserInfo/index.js
const cloud = require("wx-server-sdk");

// Initialize cloud with dynamic environment
cloud.init({
	env: cloud.DYNAMIC_CURRENT_ENV,
});

exports.main = async (event, context) => {
	// Get user identity - this is automatically injected by WeChat
	const { OPENID, APPID, UNIONID } = cloud.getWXContext();

	console.log("User identity:", { OPENID, APPID, UNIONID });

	// Use OPENID for user-specific operations
	// For example: query user data, check permissions, etc.

	return {
		openid: OPENID,
		appid: APPID,
		unionid: UNIONID, // May be undefined if not available
	};
};

Key points:

• Use cloud.getWXContext() to get user identity
• OPENID is always available and uniquely identifies the user
• APPID identifies the Mini Program
• UNIONID is only available when:
  • The Mini Program is bound to a WeChat Open Platform account
  • The user has authorized the Mini Program
• These values are verified and trustworthy - no need to validate them
• Use cloud.DYNAMIC_CURRENT_ENV to automatically use the current environment

Best practices:

• Store OPENID in your database to associate data with users
• Use OPENID for authorization and access control
• Use UNIONID when you need to identify users across multiple Mini Programs or Official Accounts
• Never expose OPENID to other users (it's a private identifier)

Scenario 3: Call cloud function from Mini Program

Use this in your Mini Program to call a cloud function and get user identity:

// In Mini Program page
Page({
	onLoad: function () {
		this.getUserInfo();
	},

	getUserInfo: function () {
		wx.cloud.callFunction({
			name: "getUserInfo", // Cloud function name
			data: {}, // Optional parameters
			success: (res) => {
				console.log("User info from cloud function:", res.result);
				// res.result contains { openid, appid, unionid }

				// Use the user info
				this.setData({
					openid: res.result.openid,
				});
			},
			fail: (err) => {
				console.error("Failed to get user info:", err);
			},
		});
	},
});

Key points:

• Use wx.cloud.callFunction() to call cloud functions
• User identity is automatically passed to the cloud function
• No need to manually send user credentials
• Handle both success and error cases

Scenario 4: Test authentication - Simple test function

Cloud function (cloudfunctions/test/index.js):

const cloud = require("wx-server-sdk");

cloud.init({
	env: cloud.DYNAMIC_CURRENT_ENV,
});

exports.main = async (event, context) => {
	// Get verified user identity - automatically injected by WeChat
	const { OPENID, APPID, UNIONID } = cloud.getWXContext();

	console.log("User identity:", { OPENID, APPID, UNIONID });

	return {
		success: true,
		message: "Authentication successful",
		identity: {
			openid: OPENID,
			appid: APPID,
			unionid: UNIONID || "Not available",
		},
		timestamp: new Date().toISOString(),
	};
};

Mini Program code:

// pages/index/index.js
Page({
	data: {
		userIdentity: null,
	},

	onLoad: function () {
		this.testAuth();
	},

	testAuth: function () {
		console.log("Testing authentication...");

		wx.cloud.callFunction({
			name: "test",
			success: (res) => {
				console.log("Authentication test result:", res.result);

				this.setData({
					userIdentity: res.result.identity,
				});

				wx.showToast({
					title: "Auth successful",
					icon: "success",
				});
			},
			fail: (err) => {
				console.error("Authentication test failed:", err);
				wx.showToast({
					title: "Auth failed",
					icon: "error",
				});
			},
		});
	},
});

Key points:

• No explicit login API call needed
• User identity is automatically available in cloud function
• OPENID is always present and verified
• UNIONID may be undefined if not available
• Use this pattern to verify authentication is working correctly

Best practices

1. Always use cloud.DYNAMIC_CURRENT_ENV

cloud.init({
	env: cloud.DYNAMIC_CURRENT_ENV,
});

This ensures the cloud function uses the correct environment automatically.

2. Store OPENID for user identification

• Use OPENID as the primary user identifier
• Store it in your database to associate data with users
• Never expose OPENID to other users

3. Handle UNIONID availability

const { OPENID, UNIONID } = cloud.getWXContext();

if (UNIONID) {
	// User has UNIONID - can be used for cross-app identification
	console.log("UNIONID available:", UNIONID);
} else {
	// UNIONID not available - use OPENID only
	console.log("Using OPENID only:", OPENID);
}

4. Use OPENID for user-specific operations

• Use OPENID to identify and authorize users
• Store OPENID when you need to associate data with users
• Use OPENID in queries to ensure users only access their own data

5. Error handling

Always handle errors when calling cloud functions:

wx.cloud.callFunction({
	name: "myFunction",
	success: (res) => {
		// Handle success
	},
	fail: (err) => {
		console.error("Cloud function error:", err);
		// Show user-friendly error message
		wx.showToast({
			title: "Operation failed",
			icon: "error",
		});
	},
});

6. Initialize CloudBase early

Initialize CloudBase in app.js onLaunch:

App({
	onLaunch: function () {
		wx.cloud.init({
			env: "your-env-id",
			traceUser: true,
		});
	},
});

Common patterns

Pattern 1: Get and return user identity

const cloud = require("wx-server-sdk");
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV });

exports.main = async (event, context) => {
	const { OPENID, APPID, UNIONID } = cloud.getWXContext();

	return {
		openid: OPENID,
		appid: APPID,
		unionid: UNIONID || null,
	};
};

Pattern 2: Use OPENID for authorization

const cloud = require("wx-server-sdk");
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV });

exports.main = async (event, context) => {
	const { OPENID } = cloud.getWXContext();

	// Check if user is authorized
	if (OPENID === event.resourceOwnerId) {
		// User is authorized to access this resource
		return { authorized: true };
	} else {
		return { authorized: false, error: "Unauthorized" };
	}
};

Pattern 3: Handle UNIONID availability

const cloud = require("wx-server-sdk");
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV });

exports.main = async (event, context) => {
	const { OPENID, UNIONID } = cloud.getWXContext();

	if (UNIONID) {
		// Can use UNIONID for cross-app user identification
		console.log("User has UNIONID:", UNIONID);
	} else {
		// Fall back to OPENID only
		console.log("Using OPENID only:", OPENID);
	}

	return { openid: OPENID, hasUnionId: !!UNIONID };
};

v3 Web SDK Mini Program methods

If the Mini Program uses @cloudbase/js-sdk (Web SDK v3) instead of wx-server-sdk, the following auth methods are available:

signInWithOpenId

WeChat OpenID silent login — automatically uses the current WeChat login state:

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

const app = cloudbase.init({
	env: "your-env-id",
	region: "ap-shanghai",
});
const auth = app.auth;

// OpenID silent login (default: use wx.cloud mode)
const { data, error } = await auth.signInWithOpenId();
if (error) {
	console.error("OpenID login failed:", error.message);
} else {
	console.log("Logged in with OpenID:", data.user?.id);
}

// For non-wx.cloud mode, pass useWxCloud: false
// const { data, error } = await auth.signInWithOpenId({ useWxCloud: false })

signInWithPhoneAuth

WeChat phone number authorization login — requires the user to authorize phone number via the Mini Program button:

// Step 1: In Mini Program page, use <button open-type="getPhoneNumber">
// to get the encrypted phone code

// Step 2: Pass the phoneCode to signInWithPhoneAuth
const { data, error } = await auth.signInWithPhoneAuth({
	phoneCode: "<encrypted-phone-code-from-wechat>",
});
if (error) {
	console.error("Phone auth failed:", error.message);
} else {
	console.log("Logged in with phone:", data.user);
}

Important:

• These methods are from @cloudbase/js-sdk, not wx-server-sdk or wx.cloud
• They provide an alternative auth path for Mini Programs using the v3 Web SDK
• For the standard wx.cloud + cloud function path, use the scenarios above instead
• signInWithPhoneAuth requires the user to tap a <button open-type="getPhoneNumber"> in the Mini Program

Summary

WeChat Mini Program authentication with CloudBase is simple and secure:

1. No explicit login needed - authentication is automatic
2. User identity is verified - OPENID, APPID, and UNIONID are trustworthy
3. Easy to use - just call cloud.getWXContext() in cloud functions
4. Secure by default - WeChat handles all authentication verification

Key takeaways:

• Initialize CloudBase with wx.cloud.init() in Mini Program
• Use cloud.getWXContext() to get user identity in cloud functions
• Use OPENID for user identification and authorization
• Handle UNIONID availability appropriately
• No explicit login API calls needed - authentication is automatic

For more complex authentication scenarios or integration with other systems, consider using CloudBase custom login in combination with WeChat authentication.