如何使用Node.js集成Aadhaar e-KYC或Aadhaar身份认证功能

接入前合规前置要求 #

• 所有Aadhaar相关接口的调用主体必须先获得印度唯一身份识别管理局（UIDAI）的授权，你可以选择自行申请成为认证服务提供商（ASP），也可以对接已经拿到UIDAI授权的第三方ASP服务。未获得授权的主体无法调用官方核心接口，使用非授权第三方API存在极高的合规风险，不符合法律服务类应用的监管要求。
• 发起任何身份认证前必须明确告知用户信息使用用途，获取用户的主动同意，同意记录需留存至少7年，符合UIDAI的监管规范。

核心接入实现（Node.js 侧） #

1. 基础依赖安装 #

常用工具依赖如下，所有敏感授权信息建议存放在环境变量中，不要硬编码在业务代码里：

npm install axios crypto uuid
# axios用于接口请求，crypto用于签名加密和哈希处理，uuid用于生成唯一请求ID

2. 标准请求逻辑示例 #

UIDAI要求所有接口请求必须携带签名，所有Aadhaar号码、手机号等敏感信息需哈希后再传输，禁止明文传输：

const axios = require('axios');
const crypto = require('crypto');
const { v4: uuidv4 } = require('uuid');

// 从对接的ASP服务商处获取的授权参数，通过环境变量读取
const ASP_APP_KEY = process.env.ASP_APP_KEY;
const ASP_APP_SECRET = process.env.ASP_APP_SECRET;
const ASP_KYC_API_ENDPOINT = process.env.ASP_KYC_API_ENDPOINT;

// 签名生成函数，具体规则以对接的ASP要求为准，核心逻辑为拼接关键参数后用app_secret加密
const generateRequestSignature = (timestamp, requestId, payloadHash) => {
  const signRawString = `${ASP_APP_KEY}|${timestamp}|${requestId}|${payloadHash}`;
  return crypto.createHmac('sha256', ASP_APP_SECRET).update(signRawString).digest('base64');
};

// Aadhaar e-KYC 认证主函数
const verifyAadhaarIdentity = async (hashedAadhaarNumber, hashedUserMobile) => {
  const requestId = uuidv4();
  const requestTimestamp = Date.now().toString();
  const requestPayload = {
    aadhaar_hash: hashedAadhaarNumber,
    mobile_hash: hashedUserMobile,
    user_consent: true, // 该字段为UIDAI强制要求，必须确认用户已授权后再传true
    request_id: requestId
  };

  // 生成请求体哈希
  const payloadHash = crypto.createHash('sha256').update(JSON.stringify(requestPayload)).digest('base64');
  const requestSignature = generateRequestSignature(requestTimestamp, requestId, payloadHash);

  try {
    const apiResponse = await axios.post(ASP_KYC_API_ENDPOINT, requestPayload, {
      headers: {
        'Content-Type': 'application/json',
        'X-App-Key': ASP_APP_KEY,
        'X-Timestamp': requestTimestamp,
        'X-Signature': requestSignature,
        'X-Request-ID': requestId
      }
    });
    // 接口返回的身份信息均为脱敏结果，不会返回完整Aadhaar号，可直接用于客户身份核验
    return {
      verifySuccess: true,
      userInfo: apiResponse.data
    };
  } catch (requestError) {
    return {
      verifySuccess: false,
      errorMsg: requestError.response?.data?.message || '身份认证请求失败'
    };
  }
};

3. 业务侧注意事项 #

• 禁止在本地服务器存储用户的完整Aadhaar号码、生物特征信息，仅可存储哈希后的身份标识用于后续业务匹配。
• 律师客户沟通场景下的身份核验记录需要和客户的案件档案绑定，留存周期符合司法行业的档案管理要求。

常见问题排查 #

• 签名校验失败：优先检查签名生成的字段拼接顺序、加密算法是否和ASP要求一致，请求时间戳和服务器时间误差不要超过5分钟。
• 认证请求被拒绝：先确认用户提供的Aadhaar号和手机号为绑定状态，其次确认用户未在UIDAI平台冻结自身的e-KYC使用权限。

内容的提问来源于stack exchange，提问作者Aditya Harsh