Auth Wechat Miniprogram

When to use this skill

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

Use it when you need to:

• Implement WeChat Mini Program login 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)