从API版本26.0.1开始,系统支持扩展三方自定义认证能力,用于设备解锁登录。锁屏提供USB Key解锁登录界面,支持三方自定义的USB Key身份认证。
USB Key(USB安全密钥)是一种基于硬件的身份认证设备,外形类似U盘,内置安全芯片,可存储数字证书和密钥。用户插入设备后,通过硬件级加密完成身份认证,安全性高于纯密码或生物特征。USB Key广泛应用于企业办公、金融、政务等高安全场景。
MDM(Mobile Device Management,移动设备管理)应用支持为账号添加、删除和查询三方自定义身份认证凭据,并可配置设备解锁策略:系统内置认证单独解锁、三方自定义认证单独解锁、二者融合解锁。
三方自定义身份认证涉及以下接口:
| 接口名称 | 所属模块 | 功能描述 |
|---|---|---|
| openSession | @kit.MDMKit | 打开用户身份认证凭据变更会话,获取挑战值(challenge),用于防重放攻击。 |
| closeSession | @kit.MDMKit | 关闭用户身份认证凭据变更会话。 |
| addUserExtendCredential | @kit.MDMKit | 添加三方自定义身份认证凭据。 |
| removeUserExtendCredential | @kit.MDMKit | 删除三方自定义身份认证凭据。 |
| getUserExtendCredential | @kit.MDMKit | 查询已添加的三方自定义身份认证凭据列表。 |
| setUnlockPolicy | @kit.MDMKit | 配置设备解锁策略:系统内置认证方式单独解锁、三方自定义认证单独解锁、三方自定义认证与系统内置认证融合解锁。 |
| getUnlockPolicy | @kit.MDMKit | 查询当前设备解锁策略。 |
| getUserAuthInstance | @kit.UserAuthenticationKit | 发起用户身份认证,获取认证通过凭证authToken。 |
申请权限:在工程Module对应的module.json5配置文件的requestPermissions标签下声明以下权限:
"requestPermissions": [
{
"name": "ohos.permission.ENTERPRISE_MANAGE_SECURITY"
},
{
"name": "ohos.permission.ACCESS_BIOMETRIC"
}
] 各权限的用途如下:
导入模块。
import { securityManager } from '@kit.MDMKit';
import { userAuth } from '@kit.UserAuthenticationKit'; 调用openSession打开用户身份认证凭据变更会话,获取挑战值challenge。
(可选)指定用户认证相关参数AuthParam(使用上一步获取的challenge作为挑战值),调用getUserAuthInstance获取认证对象。
(可选)调用UserAuthInstance.on('result')订阅认证结果,调用UserAuthInstance.start发起认证,在回调中获取认证通过凭证authToken。
根据业务场景调用addUserExtendCredential(添加凭据)或removeUserExtendCredential(删除凭据),传入authToken。添加凭据时需同时传入pluginInfo,该值为三方自定义认证器的标识名称,由认证器提供方提供。
调用closeSession关闭用户身份认证凭据变更会话。
(可选)调用setUnlockPolicy配置设备解锁策略。
本指南的代码片段摘自UsbKeyAuth示例工程。片段外的accountId、pluginInfo定义见Constants.ets,Logger、MAX_RETRIES、isRetryable、buildFailureMessage、resolveStringResource为日志与重试的辅助实现,定义见UsbKeyAuthService.ets,实际开发中可自行替换;入参uiContext为当前页面的UI上下文(@kit.ArkUI的UIContext),用于解析认证控件的标题文案。
添加三方自定义身份认证凭据是启用该认证方式的必须步骤,未添加凭据时无法使用三方自定义认证解锁设备。本节流程对应三方自定义身份认证开发步骤中第3步至第8步在添加凭据场景下的具体时序,其中第4步至第5步的用户身份认证、第8步的设备解锁策略均为可选。
添加凭据的流程如下:

添加凭据与删除凭据时如选择完成用户身份认证以获取authToken,示例工程将其封装为requestAuthToken:
// 发起用户身份认证,返回 authToken
function requestAuthToken(challenge: Uint8Array, title: string): Promise<Uint8Array> {
return new Promise((resolve, reject) => {
const authParam: userAuth.AuthParam = {
challenge: challenge,
authType: [userAuth.UserAuthType.PIN],
authTrustLevel: userAuth.AuthTrustLevel.ATL4,
};
const widgetParam: userAuth.WidgetParam = { title };
const instance: userAuth.UserAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
instance.on('result', {
onResult: (result: userAuth.UserAuthResult) => {
instance.off('result');
if (result.result === userAuth.UserAuthResultCode.SUCCESS && result.token) {
resolve(result.token);
} else {
reject(new Error(`Authentication failed, result code: ${result.result}`));
}
}
});
// start会弹出密码认证控件,调用阻塞直到用户完成认证
instance.start();
});
} 添加凭据的示例代码如下:
export async function bindUsbKey(uiContext: UIContext): Promise<string> {
let retryCount: number = 0;
while (retryCount < MAX_RETRIES) {
try {
// 第1步:打开会话,获取挑战值
const challenge: Uint8Array = await securityManager.openSession(accountId);
Logger.info('Succeeded in opening session.');
// 第2步:发起用户身份认证,获取认证令牌
const dialogTitle: string = resolveStringResource(uiContext, $r('app.string.bind_auth_dialog_title'));
const authToken: Uint8Array = await requestAuthToken(challenge, dialogTitle);
Logger.info('Authentication succeeded.');
// 第3步:绑定USB Key凭据
const addInfo: securityManager.AddCredentialInfo = { pluginInfo, authToken };
await securityManager.addUserExtendCredential(addInfo, accountId);
Logger.info('Succeeded in adding USB Key credential.');
// 第4步:关闭会话
securityManager.closeSession(accountId);
Logger.info('USB Key binding completed.');
// 可选:配置USB Key解锁模式(EXTENDED_AUTH_REQUIRED 表示USB Key+锁屏密码组合认证)
securityManager.setUnlockPolicy(
securityManager.UnlockPolicy.EXTENDED_AUTH_REQUIRED,
accountId
);
Logger.info('Succeeded in setting unlock policy.');
return 'USB Key binding succeeded.';
} catch (err) {
const error: BusinessError = err as BusinessError;
if (isRetryable(error.code) && retryCount < MAX_RETRIES - 1) {
retryCount++;
Logger.warn(`Operation failed with code ${error.code}, retrying... (${retryCount}/${MAX_RETRIES})`);
await new Promise<void>(resolve => setTimeout(resolve, RETRY_INTERVAL));
continue;
}
const failureMessage: string = buildFailureMessage('USB Key binding', error);
try {
securityManager.closeSession(accountId);
} catch (closeErr) {
// 忽略关闭会话的错误
}
return failureMessage;
}
}
return 'USB Key binding failed.';
} 删除凭据用于移除已添加的三方自定义身份认证凭据,仅在需要撤销该认证方式时执行。本节流程对应三方自定义身份认证开发步骤中第3步至第8步在删除凭据场景下的具体时序,与添加凭据的区别在于:需先查询凭据获取credentialId,且第8步为将设备解锁策略重置为系统内置认证方式(可选)。
删除凭据的流程如下:

删除凭据的示例代码如下:
export async function unbindUsbKey(uiContext: UIContext): Promise<string> {
let retryCount: number = 0;
// 第1步:查询已绑定的USB Key凭据
let credentials: securityManager.UserExtCredentialInfo[];
try {
credentials = await securityManager.getUserExtendCredential(accountId);
} catch (err) {
const error: BusinessError = err as BusinessError;
return buildFailureMessage('USB Key unbinding', error);
}
if (credentials.length === 0) {
Logger.info('No USB Key credential found.');
return 'No USB Key credential found.';
}
const targetCredentialId: Uint8Array = credentials[0].credentialId;
while (retryCount < MAX_RETRIES) {
try {
// 第2步:打开会话,获取挑战值
const challenge: Uint8Array = await securityManager.openSession(accountId);
Logger.info('Succeeded in opening session.');
// 第3步:发起用户身份认证,获取认证令牌
const dialogTitle: string = resolveStringResource(uiContext, $r('app.string.unbind_auth_dialog_title'));
const authToken: Uint8Array = await requestAuthToken(challenge, dialogTitle);
Logger.info('Authentication succeeded.');
// 第4步:解绑USB Key凭据
const removeInfo: securityManager.RemoveCredentialInfo = {
credentialId: targetCredentialId,
authToken: authToken,
};
securityManager.removeUserExtendCredential(removeInfo, accountId);
Logger.info('Succeeded in removing USB Key credential.');
securityManager.closeSession(accountId);
Logger.info('USB Key unbinding completed.');
// 可选:重置解锁模式为系统默认
securityManager.setUnlockPolicy(
securityManager.UnlockPolicy.DEFAULT,
accountId
);
Logger.info('Succeeded in resetting unlock policy.');
return 'USB Key unbinding succeeded.';
} catch (err) {
const error: BusinessError = err as BusinessError;
if (isRetryable(error.code) && retryCount < MAX_RETRIES - 1) {
retryCount++;
Logger.warn(`Operation failed with code ${error.code}, retrying... (${retryCount}/${MAX_RETRIES})`);
await new Promise<void>(resolve => setTimeout(resolve, RETRY_INTERVAL));
continue;
}
const failureMessage: string = buildFailureMessage('USB Key unbinding', error);
try {
securityManager.closeSession(accountId);
} catch (closeErr) {
// 忽略关闭会话的错误
}
return failureMessage;
}
}
return 'USB Key unbinding failed.';
} 调用getUserExtendCredential查询已添加的三方自定义身份认证凭据,返回的credentialId用于删除凭据。
export async function queryCredentials(): Promise<string> {
try {
const credentials: securityManager.UserExtCredentialInfo[] =
await securityManager.getUserExtendCredential(accountId);
Logger.info(`Found ${credentials.length} USB Key credential(s).`);
credentials.forEach((cred: securityManager.UserExtCredentialInfo, index: number) => {
Logger.info(`Credential ${index}: pluginInfo=${cred.pluginInfo}`);
});
return `Found ${credentials.length} USB Key credential(s).`;
} catch (err) {
const error: BusinessError = err as BusinessError;
return buildFailureMessage('Query credentials', error);
}
} export function setUnlockPolicy(): string {
try {
securityManager.setUnlockPolicy(securityManager.UnlockPolicy.EXTENDED_AUTH_ONLY, accountId);
Logger.info('Succeeded in setting unlock policy to EXTENDED_AUTH_ONLY.');
return 'Set unlock policy succeeded.';
} catch (err) {
const error: BusinessError = err as BusinessError;
return buildFailureMessage('Set unlock policy', error);
}
} export function getUnlockPolicy(): string {
try {
const policy: securityManager.UnlockPolicy = securityManager.getUnlockPolicy(accountId);
switch (policy) {
case securityManager.UnlockPolicy.DEFAULT:
Logger.info('Current unlock policy: DEFAULT (system default).');
break;
case securityManager.UnlockPolicy.EXTENDED_AUTH_ONLY:
Logger.info('Current unlock policy: EXTENDED_AUTH_ONLY (USB Key only).');
break;
case securityManager.UnlockPolicy.EXTENDED_AUTH_REQUIRED:
Logger.info('Current unlock policy: EXTENDED_AUTH_REQUIRED (USB Key + password).');
break;
default:
Logger.info(`Unknown unlock policy: ${policy}`);
}
return `Current unlock policy: ${policy}`;
} catch (err) {
const error: BusinessError = err as BusinessError;
return buildFailureMessage('Get unlock policy', error);
}
}