打造用戶認證系統，構筑信息安全防線

在當今的數字化時代，信息安全和用戶隱私保護變得越來越重要。用戶身份認證是確保信息安全的第一道防線。通過驗證用戶身份，可以防止未經授權的訪問和數據泄露。它有助于保護用戶的個人信息、賬戶資金和其他敏感數據。此外，用戶身份認證還可以提高系統的安全性，減少惡意行為和欺詐事件的發生。

HarmonyOS SDK用戶認證服務（User Authentication Kit）提供了基于用戶在設備本地注冊的鎖屏口令、人臉和指紋來認證用戶身份的能力，并提供了多設備統一的、集多種認證方式（人臉、指紋、口令）于一體的系統級用戶身份認證控件。用戶身份認證可用于各種鑒權場景，如應用內賬號登錄、支付認證等。

開發準備

申請權限

在開發具備用戶身份認證的應用前，需要先申請權限ohos.permission.ACCESS_BIOMETRIC，應用才能使用生物特征識別能力（如人臉、指紋）進行身份認證。
該權限授權方式為system_grant（系統授權），開發者只需要在module.json5配置文件的requestPermissions標簽中聲明權限，即可獲取系統授權。具體聲明指導請參考申請應用權限-聲明權限。

開發步驟

查詢支持的認證能力

指定認證類型（UserAuthType）和認證等級（AuthTrustLevel），調用getAvailableStatus接口查詢當前的設備是否支持相應的認證能力。

認證等級ATL的選擇參見下表：

以查詢設備是否支持認證可信等級≥ATL1的人臉認證功能為例：

import { BusinessError } from  '@kit.BasicServicesKit';
import { userAuth } from '@kit.UserAuthenticationKit';// 查詢認證能力是否支持
try {    userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL1);    console.info('current auth trust level is supported');
} catch (error) {const err: BusinessError = error as BusinessError;console.error(`current auth trust level is not supported. Code is ${err?.code}, message is ${err?.message}`);
}

發起認證

1.指定用戶認證相關參數AuthParam（包括挑戰值、認證類型UserAuthType列表和認證等級AuthTrustLevel）、配置認證控件界面WidgetParam，調用getUserAuthInstance獲取認證對象。

2.調用UserAuthInstance.on接口訂閱認證結果。

3.調用UserAuthInstance.start接口發起認證，通過IAuthCallback回調返回認證結果UserAuthResult。

當認證成功時返回認證通過類型（UserAuthType）和令牌信息（AuthToken）。

示例1：

發起用戶認證，采用認證可信等級≥ATL3的人臉+鎖屏密碼認證，獲取認證結果：

// API version 10
import { BusinessError } from '@kit.BasicServicesKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { userAuth } from '@kit.UserAuthenticationKit';try {const rand = cryptoFramework.createRandom();const len: number = 16;const randData: Uint8Array = rand?.generateRandomSync(len)?.data;// 設置認證參數const authParam: userAuth.AuthParam = {challenge: randData,authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE],authTrustLevel: userAuth.AuthTrustLevel.ATL3,};// 配置認證界面const widgetParam: userAuth.WidgetParam = {title: '請進行身份認證',};// 獲取認證對象const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);console.info('get userAuth instance success');// 訂閱認證結果userAuthInstance.on('result', {onResult(result) {console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`);// 可在認證結束或其他業務需要場景，取消訂閱認證結果userAuthInstance.off('result');}});console.info('auth on success');userAuthInstance.start();console.info('auth start success');
} catch (error) {const err: BusinessError = error as BusinessError;console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}

示例2：

發起用戶認證，采用認證可信等級≥ATL3的人臉 + 認證類型相關 + 復用設備解鎖最大有效時長認證，獲取認證結果：

// API version 10
import { BusinessError } from  '@kit.BasicServicesKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { userAuth } from '@kit.UserAuthenticationKit';// 設置認證參數
let reuseUnlockResult: userAuth.ReuseUnlockResult = {reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT,reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,
}
try {const rand = cryptoFramework.createRandom();const len: number = 16;const randData: Uint8Array = rand?.generateRandomSync(len)?.data;const authParam: userAuth.AuthParam = {challenge: randData,authType: [userAuth.UserAuthType.FACE],authTrustLevel: userAuth.AuthTrustLevel.ATL3,reuseUnlockResult: reuseUnlockResult,};// 配置認證界面const widgetParam: userAuth.WidgetParam = {title: '請進行身份認證',};// 獲取認證對象const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);console.info('get userAuth instance success');// 訂閱認證結果userAuthInstance.on('result', {onResult(result) {console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`);// 可在認證結束或其他業務需要場景，取消訂閱認證結果userAuthInstance.off('result');}});console.info('auth on success');userAuthInstance.start();console.info('auth start success');
} catch (error) {const err: BusinessError = error as BusinessError;console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}

認證過程中取消認證

1.指定用戶認證相關參數AuthParam（包括挑戰值、認證類型UserAuthType列表和認證等級AuthTrustLevel），獲取認證對象UserAuthInstance，并調用UserAuthInstance.start發起認證。

2.通過使用已經成功發起認證的UserAuthInstance對象調用UserAuthInstance.cancel接口取消本次認證。

示例代碼為發起認證可信等級≥ATL3的人臉+鎖屏密碼認證后，取消認證請求：

import { BusinessError } from  '@kit.BasicServicesKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { userAuth } from '@kit.UserAuthenticationKit';try {const rand = cryptoFramework.createRandom();const len: number = 16;const randData: Uint8Array = rand?.generateRandomSync(len)?.data;// 設置認證參數const authParam: userAuth.AuthParam = {challenge: randData,authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE],authTrustLevel: userAuth.AuthTrustLevel.ATL3,};// 配置認證界面const widgetParam: userAuth.WidgetParam = {title: '請進行身份認證',};// 獲取認證對象const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);console.log('get userAuth instance success');// 開始認證userAuthInstance.start();console.log('auth start success');// 取消認證userAuthInstance.cancel();console.log('auth cancel success');
} catch (error) {const err: BusinessError = error as BusinessError;console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}

切換自定義認證

針對需要切換自定義認證方式的場景，發起認證請求的方式請參考發起認證，但在傳入的widgetParam需包含字段navigationButtonText。

當前示例僅展示如何配置界面、選擇切換到自定義認證界面，具體拉起的頁面及對應頁面的實現，請開發者自行實現，代碼插入位置可參考注釋提示。

import { BusinessError } from  '@kit.BasicServicesKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { userAuth } from '@kit.UserAuthenticationKit';try {const rand = cryptoFramework.createRandom();const len: number = 16;const randData: Uint8Array = rand?.generateRandomSync(len)?.data;const authParam: userAuth.AuthParam = {challenge: randData,authType: [userAuth.UserAuthType.FACE],authTrustLevel: userAuth.AuthTrustLevel.ATL3,};// 配置認證界面需設置navigationButtonTextconst widgetParam: userAuth.WidgetParam = {title: '請驗證身份',navigationButtonText: '使用密碼',};// 獲取認證對象const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);console.log('get userAuth instance success');// 訂閱認證結果userAuthInstance.on('result', {onResult(result) {// 若收到ResultCode值為12500000，代表操作成功console.log('userAuthInstance callback result = ' + JSON.stringify(result));// 若收到ResultCode值為12500011,說明用戶點擊了導航按鈕想切換自定義認證方式if (result.result == 12500011) {//請開發者自行完成拉起自定義認證界面的實現}}});console.log('auth on success');userAuthInstance.start();console.log('auth start success');
} catch (error) {const err: BusinessError = error as BusinessError;console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
}

查詢用戶注冊憑據的狀態

指定認證類型（UserAuthType），調用getEnrolledState接口查詢用戶注冊憑據的狀態。

以查詢用戶人臉注冊憑據的狀態為例：

import { BusinessError } from  '@kit.BasicServicesKit';
import { userAuth } from '@kit.UserAuthenticationKit';try {let enrolledState = userAuth.getEnrolledState(userAuth.UserAuthType.FACE);console.info(`get current enrolled state success, enrolledState: ${JSON.stringify(enrolledState)}`);
} catch (error) {const err: BusinessError = error as BusinessError;console.error(`get current enrolled state failed, Code is ${err?.code}, message is ${err?.message}`);
}

了解更多詳情>>

訪問用戶認證服務聯盟官網

獲取用戶認證服務開發指導文檔