QQ Login Setup

This guide covers setting up QQ Login (QQ互联登录) for your application, providing authentication for users with Tencent QQ accounts.

Prerequisites

• QQ Internet (QQ互联) account
• Business qualification for verification
• Access to QQ Internet Platform

Step 1: Register on QQ Internet Platform

1. Go to QQ Internet Platform
2. Click 登录 (Login) with your QQ account
3. Click 应用管理 (Application Management)
4. Complete developer registration if first time

Developer Verification

For full features, complete verification:

1. Go to 个人信息 (Personal Information)
2. Complete real-name verification
3. For business accounts:

• Submit business license
• Complete enterprise verification

Step 2: Create an Application

1. Click 创建应用 (Create Application)
2. Select application type:

• 网站应用 (Website) - For web applications
• 移动应用 (Mobile) - For iOS/Android apps

Website Application

Fill in the following:

Mobile Application

Fill in platform-specific information:

For iOS:

• Bundle ID: com.yourcompany.myapp
• Universal Links (if using)

For Android:

• Package Name: com.yourcompany.myapp
• App Signature (MD5)

1. Submit for review (usually 1-3 days)

Step 3: Get Application Credentials

After approval:

1. Go to 应用管理 (Application Management)
2. Find your application
3. Note down:

• APP ID - Application identifier
• APP Key - Application secret key

Security: Never expose your APP Key in client-side code.

Step 4: Configure Callback URLs

1. In application settings, find 回调地址 (Callback URLs)
2. Add your authorized callback URLs:

https://yourdomain.com/auth/qq/callback
https://yourdomain.com/auth/callback

Note: Callback URL must exactly match the registered URL, including protocol and path.

Step 5: Configure in OpenDev

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

{
  "provider": "qq",
  "appId": "101234567",
  "appKey": "YOUR_APP_KEY",
  "scopes": ["get_user_info"],
  "callbackUrl": "https://yourdomain.com/auth/callback?provider=qq"
}

Note:

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

Configuration Fields

Available Scopes

Step 6: Implement QQ Login

Web Authorization Flow

1. Redirect user to:
   https://graph.qq.com/oauth2.0/authorize?
   response_type=code&
   client_id=APP_ID&
   redirect_uri=CALLBACK_URL&
   state=STATE&
   scope=get_user_info

2. User authorizes with QQ account

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

4. Exchange code for access_token:
   POST https://graph.qq.com/oauth2.0/token

5. Get OpenID:
   GET https://graph.qq.com/oauth2.0/me?access_token=TOKEN

6. Get user info:
   GET https://graph.qq.com/user/get_user_info?
   access_token=TOKEN&
   oauth_consumer_key=APP_ID&
   openid=OPENID

Mobile Implementation

For mobile apps, use QQ SDK:

iOS (Swift):

// Initialize
let oauth = TencentOAuth(appId: "APP_ID", andDelegate: self)

// Request authorization
oauth.authorize(["get_user_info"])

// Handle callback
func tencentDidLogin() {
    let openId = oauth.openId
    let accessToken = oauth.accessToken
}

Android (Kotlin):

// Initialize
val tencent = Tencent.createInstance("APP_ID", context)

// Request authorization
tencent.login(activity, "get_user_info", listener)

// Handle callback in listener
override fun onComplete(response: Any?) {
    val openId = (response as JSONObject).getString("openid")
    val accessToken = response.getString("access_token")
}

Step 7: Test the Integration

Testing Checklist

1. Test authorization flow works
2. Verify callback receives correct parameters
3. Check user info retrieval
4. Test error handling

Sample OAuth Response

{
  "provider": "qq",
  "providerId": "A1B2C3D4E5F6",
  "nickname": "QQ昵称",
  "avatar": "https://thirdqq.qlogo.cn/...",
  "avatarHD": "https://thirdqq.qlogo.cn/.../100",
  "gender": "男",
  "year": "1990"
}

Understanding QQ Identifiers

Tip: Apply for UnionID permission if you have multiple apps and need to identify the same user across them.

Troubleshooting

Error: redirect uri is illegal (100010)

Solutions:

• Callback URL must exactly match registered URL
• Check for trailing slashes
• Verify protocol (http vs https)

Error: client_id is empty or invalid

Solutions:

• Verify APP ID is correct
• Ensure application is approved
• Check application status is active

Error: access_token is invalid

Solutions:

• Token may have expired (default 3 months)
• Refresh the access token
• User may have revoked authorization

User Info Returns Empty

Solutions:

• Verify scope includes getuserinfo
• Check OpenID is correct
• Ensure access_token is valid

Platform-Specific Considerations

ICP Requirements

• Website must have valid ICP registration
• ICP number required during application creation
• Non-ICP domains will be rejected

Mobile App Requirements

iOS:

• Configure URL Schemes: tencent[APP_ID]
• Add LSApplicationQueriesSchemes for QQ and TIM

Android:

• Add permissions for internet access
• Configure AuthActivity in manifest
• Handle deep links properly

User Privacy

• Request only necessary permissions
• Explain why permissions are needed
• Provide Chinese privacy policy

Security Best Practices

1. Validate State Parameter - Prevent CSRF attacks
2. Use Server-Side Token Exchange - Never exchange tokens in frontend
3. Secure APP Key - Store securely on server
4. HTTPS Required - All endpoints must use HTTPS
5. Token Expiration - Handle token refresh properly

SDK Integration

iOS SDK

# Podfile
pod 'TencentOpenAPI'

Android SDK

// build.gradle
implementation 'com.tencent.open:opensdk:3.5.2'

JavaScript SDK

<script src="https://connect.qq.com/qc_jssdk.js"></script>
<script>
QC.Login({
    btnId: "qqLoginBtn"
}, function(result) {
    // Handle login result
});
</script>

Related Documentation

• QQ Internet Platform
• QQ Login Documentation
• OpenDev OAuth Channels