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 CloudBase Web Auth skill at
```
skills/auth-web-skill
```
)
Server-side auth with Node SDK (use the CloudBase Node Auth skill at
```
skills/auth-nodejs-skill
```
)
Non-WeChat authentication methods (use appropriate auth skills)

How to use this skill (for a coding agent)

Confirm CloudBase environment
- Ask the user for:
  - env
    – CloudBase environment ID
  - Confirm the Mini Program is linked to the CloudBase environment
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
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
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
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

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
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
Security:
- The
```
openid
```
  ,
```
appid
```
  , and
```
unionid
```
  are verified and trustworthy
- WeChat has already completed authentication
- Developers can directly use these identifiers without additional verification
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 }
}

Summary

WeChat Mini Program authentication with CloudBase is simple and secure:

No explicit login needed - authentication is automatic
User identity is verified -
```
OPENID
```
,
```
APPID
```
, and
```
UNIONID
```
are trustworthy
Easy to use - just call
```
cloud.getWXContext()
```
in cloud functions
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.

auth-wechat-miniprogram

NPX Install

SKILL.md Content

When to use this skill

How to use this skill (for a coding agent)

Core concepts

How WeChat Mini Program authentication works with CloudBase

Scenarios – WeChat Mini Program auth patterns

Scenario 1: Initialize CloudBase in Mini Program

Scenario 2: Get user identity in a cloud function

Scenario 3: Call cloud function from Mini Program

Scenario 4: Test authentication - Simple test function

Best practices

1. Always use cloud.DYNAMIC_CURRENT_ENV

2. Store OPENID for user identification

3. Handle UNIONID availability

4. Use OPENID for user-specific operations

5. Error handling

6. Initialize CloudBase early

Common patterns

Pattern 1: Get and return user identity

Pattern 2: Use OPENID for authorization

Pattern 3: Handle UNIONID availability

Summary