WeChat Login Setup

This guide covers setting up WeChat Login (微信登录) for your application, enabling authentication for users in the Chinese market.

Prerequisites

• WeChat Open Platform account (微信开放平台)
• Business license for verification
• Access to WeChat Open Platform

Step 1: Register on WeChat Open Platform

1. Go to WeChat Open Platform
2. Click 注册 (Register) if you don't have an account
3. Complete email verification
4. Fill in developer information

Account Verification

For full access, complete account verification:

1. Go to 账号中心 (Account Center)
2. Click 开发者资质认证 (Developer Verification)
3. Submit required documents:

• Business license
• Contact information
• Authorization letter

Note: Verification typically takes 3-5 business days and costs ¥300/year.

Step 2: Create an Application

For Mobile Apps

1. Go to 管理中心 (Management Center)
2. Click 移动应用 (Mobile Applications)
3. Click 创建移动应用 (Create Mobile App)
4. Fill in application details:

1. Submit for review

For iOS Apps

Add iOS platform information:

• Bundle ID: com.yourcompany.myapp
• App Store download link (if published)
• Universal Links support

For Android Apps

Add Android platform information:

• Package Name: com.yourcompany.myapp
• App Signature (MD5, lowercase, no colons)
• Download link

For Websites

1. Go to 网站应用 (Website Applications)
2. Click 创建网站应用 (Create Website App)
3. Fill in website details:

• Domain name
• Website introduction
• Authorization callback domain

Step 3: Get Application Credentials

After approval:

1. Go to your application details
2. Note down:

• AppID - Application identifier
• AppSecret - Application secret (click to reveal)

Warning: Keep your AppSecret secure. Reset it immediately if compromised.

Step 4: Configure Authorization

For Website Applications

1. In application settings, find 接口权限 (API Permissions)
2. Apply for 网页授权获取用户基本信息 (Web Authorization)
3. Configure authorization callback domain:

• Domain only (no protocol): yourdomain.com
• Must be ICP registered domain in China

For Mobile Applications

Permissions are granted based on verification level:

• 未认证 (Unverified): Basic login only
• 已认证 (Verified): Full user info access

Step 5: Configure in OpenDev

1. Log in to OpenDev Platform
2. Navigate to OAuth Channels
3. Add or edit the WeChat OAuth channel
4. Enter your configuration:

{
  "provider": "wechat",
  "appId": "wx1234567890abcdef",
  "appSecret": "YOUR_APP_SECRET",
  "scopes": ["snsapi_login"],
  "callbackUrl": "https://yourdomain.com/auth/callback?provider=wechat"
}

Note:

• The unified callback URL format is /auth/callback?provider=wechat (GET/POST method).
• The appSecret should be encrypted before storing in the database.
• Field name aliases supported: clientId for appId, clientSecret for appSecret.

Configuration Fields

Scope Options

Step 6: Implement WeChat Login

Web Authorization Flow

1. Redirect user to:
   https://open.weixin.qq.com/connect/qrconnect?
   appid=APPID&
   redirect_uri=CALLBACK_URL&
   response_type=code&
   scope=snsapi_login&
   state=STATE#wechat_redirect

2. User scans QR code with WeChat

3. Receive callback with code:
   https://yourdomain.com/callback?code=CODE&state=STATE

4. Exchange code for access_token

5. Get user info with access_token

Mobile Authorization Flow

For mobile apps, use WeChat SDK:

// iOS
let req = SendAuthReq()
req.scope = "snsapi_userinfo"
req.state = "your_state"
WXApi.send(req)

// Android
val req = SendAuth.Req()
req.scope = "snsapi_userinfo"
req.state = "your_state"
api.sendReq(req)

Step 7: Test the Integration

Testing Notes

1. Test Environment: Use WeChat Sandbox for development
2. Test Accounts: Add test accounts in Open Platform
3. Real Device: WeChat login requires actual WeChat app

Sample OAuth Response

{
  "provider": "wechat",
  "providerId": "oWv1234567890ABCDEF",
  "unionId": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
  "nickname": "用户昵称",
  "avatar": "https://thirdwx.qlogo.cn/...",
  "gender": 1,
  "province": "广东",
  "city": "深圳"
}

UnionID vs OpenID

Tip: Always store UnionID if available for cross-app user identification.

Troubleshooting

Error: redirect_uri 参数错误

Solutions:

• Callback domain must exactly match registered domain
• No protocol in registered domain (use domain.com not https://domain.com)
• Domain must have valid ICP registration

Error: invalid appid

Solutions:

• Check AppID is correct
• Ensure application is approved
• Verify you're using correct environment (sandbox vs production)

Error: scope 参数错误

Solutions:

• Use snsapi_login for website applications
• Use snsapi_userinfo for mobile apps
• Ensure permission is granted in Open Platform

QR Code Not Loading

Solutions:

• Check if WeChat JS SDK is loaded
• Verify domain is whitelisted
• Check browser console for errors

China-Specific Considerations

ICP Registration

• Website domain must have valid ICP (Internet Content Provider) registration
• ICP number should be displayed on website footer

Data Privacy

• Comply with China's Personal Information Protection Law (PIPL)
• Store user data in servers located in China if required
• Provide privacy policy in Chinese

User Experience

• Provide Chinese language support
• Consider WeChat Mini Program for deeper integration
• Support both QR code and in-app authorization

Security Best Practices

1. Validate State Parameter - Prevent CSRF attacks
2. Use HTTPS - Required for all callbacks
3. Secure AppSecret - Never expose in frontend code
4. Token Management - Store and refresh tokens properly
5. UnionID Binding - Use UnionID for user identification

Related Documentation

• WeChat Open Platform Documentation
• Web Authorization Guide
• OpenDev OAuth Channels