Tencent Cloud Serverless Authentication Utility

2.0.1 · active · verified Wed Apr 22

This package, `serverless-tencent-auth-tool`, simplifies authentication and credential management for applications deployed on Tencent Cloud's Serverless Framework. It streamlines processes such as automatic login, obtaining Tencent Cloud AppIds, and verifying real-name authentication status, which are critical for operating services within the Chinese cloud ecosystem. As of version 2.0.1, it provides a utility class to interact with Tencent Cloud's authentication mechanisms from within a Serverless environment. While a specific release cadence isn't clearly documented, the version number indicates active development. It serves as a practical tool for developers to integrate Tencent Cloud's strict identity and access management requirements into their serverless applications, differentiating itself by abstracting complex auth flows.

Common errors

```
UnauthorizedOperation.NonAuthorize
```
cause The Tencent Cloud account has not completed identity (real-name) verification, which is a prerequisite for many services.

fix Log in to the Tencent Cloud console and complete the real-name verification process for your account.
```
UnauthorizedOperation
```
cause The provided `SecretId` and `SecretKey` belong to an account or sub-account that lacks the necessary permissions to perform the requested operation.

fix Verify the IAM policies associated with your credentials in the Tencent Cloud CAM console. Grant the required permissions (e.g., `SCFFullAccess` or specific service permissions) to the user or role.
```
InvalidParameter
```
cause One or more authentication parameters (e.g., `SecretId`, `SecretKey`, `Token`, `Region`) are missing, incorrectly formatted, or invalid.

fix Double-check your credential configuration in `serverless.yml`, environment variables, or `this.context.credentials` to ensure all required fields are present and correctly formatted. Pay attention to whitespace.
```
FailedOperation.AccountArrears
```
cause The Tencent Cloud account has overdue payments or an insufficient balance, which prevents resource operations.

fix Recharge your Tencent Cloud account to ensure a positive balance and resolve any overdue payments.

Warnings

breaking Breaking changes for this specific utility between major versions are not explicitly documented. However, general Tencent Cloud SDKs and the Serverless Framework itself undergo significant updates. Always review the `serverless` CLI and `tencentcloud-sdk-nodejs` release notes when upgrading to avoid compatibility issues.
Fix: Consult the `serverless` and `tencentcloud-sdk-nodejs` official documentation for migration guides related to authentication and API changes.
gotcha Tencent Cloud's stringent real-name verification (实名认证) is mandatory for many services, especially for accounts in mainland China. Operations will fail if the account has not completed this process. This tool can detect if it's done, but cannot complete it.
Fix: Ensure the Tencent Cloud account linked to your credentials has completed real-name verification via the Tencent Cloud Console. This is a manual, out-of-band process.
gotcha Sub-accounts often lack the necessary permissions for initial setup, role creation, or accessing certain resources. This can lead to `UnauthorizedOperation` errors even with correct `SecretId` and `SecretKey`.
Fix: Use the primary (root) Tencent Cloud account to execute initial authorization commands (e.g., `serverless tencent initcam`) or explicitly grant `SCF_QcsRole` and other required permissions to the sub-account through Tencent Cloud's CAM console.
gotcha The `APPID` (AppId) is crucial for certain Tencent Cloud services and features, particularly for package deployments larger than 10MB (which use COS for upload) or specific API Gateway configurations. Omitting it can cause deployment failures.
Fix: Provide the `tencent_app_id` in your Serverless configuration or ensure it's available in your credential context if your application uses features requiring it. It can be found in the Tencent Cloud Account Center.

Install

npm install serverless-tencent-auth-tool npm
yarn add serverless-tencent-auth-tool yarn
pnpm add serverless-tencent-auth-tool pnpm

Imports

tencentAuth
wrong:
```
import { tencentAuth } from 'serverless-tencent-auth-tool';
```
correct:
```
const tencentAuth = require('serverless-tencent-auth-tool');
```
The primary usage shown in documentation is CommonJS `require()`. While ESM import `import tencentAuth from 'pkg'` might work if there's a default export, named imports are incorrect for this pattern.
TencentAuthClassInstance
wrong:
```
tencentAuth.doAuth(...);
```
correct:
```
const auth = new tencentAuth();
```
The module exports a class or constructor function that must be instantiated before calling methods like `doAuth`.

Quickstart

Demonstrates how to import the `tencentAuth` class, instantiate it, and use `doAuth` to manage Tencent Cloud credentials within a Serverless Framework context, including placeholders for environment variables.

const tencentAuth = require('serverless-tencent-auth-tool');

// In a Serverless Framework context (e.g., within a custom plugin or component):
async function authenticateTencentCloud(context) {
  const auth = new tencentAuth();

  // Mimic Serverless Framework's context object structure for credentials
  const mockContext = {
    credentials: {
      tencent: {
        SecretId: process.env.TENCENT_SECRET_ID ?? '',
        SecretKey: process.env.TENCENT_SECRET_KEY ?? '',
        Token: process.env.TENCENT_TOKEN ?? '' // Optional, for temporary credentials
      }
    },
    // Or if credentials are in instance state (e.g., after initial deployment)
    instance: {
      state: {
        status: {
          tencent: {
            SecretId: process.env.TENCENT_SECRET_ID ?? '',
            SecretKey: process.env.TENCENT_SECRET_KEY ?? ''
          }
        }
      }
    }
  };

  // Use provided context or mock if running standalone
  const actualContext = context || mockContext;

  // Perform authentication and update credentials
  actualContext.credentials.tencent = actualContext.credentials.tencent
    ? await auth.doAuth(actualContext.credentials.tencent)
    : await auth.doAuth(actualContext.instance.state.status.tencent);

  console.log('Tencent Cloud credentials updated:', actualContext.credentials.tencent);
  return actualContext.credentials.tencent;
}

// Example usage (replace with your actual Serverless Framework context)
authenticateTencentCloud(null).catch(console.error);

view raw JSON →