• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Applying Custom Authentication
2
3<!--Kit: User Authentication Kit-->
4<!--Subsystem: UserIAM-->
5<!--Owner: @WALL_EYE-->
6<!--SE: @lichangting518-->
7<!--TSE: @jane_lz-->
8
9If the biometric authentication fails and the user taps the navigation button for a custom authentication, the unified identity authentication framework will terminate the system authentication process and instruct the caller to launch the custom authentication page.
10
11For example, if the facial or fingerprint authentication provided by the system fails in a payment process, the user can switch to the password authentication defined by the device vendor.
12
13Since payment password authentication is not a system authentication capability, the application must provide explicit navigation button information, for example, **Use Payment Password**, when initiating authentication. This ensures that a **Use Payment Password** button is displayed on the authentication page.
14
15When the user taps this button, the application that initiates the custom authentication request will receive a special authentication result returned by the user authentication framework, indicating that the system authentication process is ended and prompting the application to launch its custom authentication page. As a result, the payment password authentication page customized by the service is displayed.
16
17<!--RP1-->
18![](figures/authentication-widget.png)
19<!--RP1End-->
20
21As shown in the following figure, the selected area is the **WidgetParam.navigationButtonText** field. You can configure this field to guide users to switch from biometric authentication to the service password authentication customized by the application.
22
23> **NOTE**
24> The lock screen password authentication and custom authentication are mutually exclusive.
25
26| Authentication Type| Switch to Custom Authentication<br>(√ indicates supported, x indicates not supported)|
27| -------- | -------- |
28| Lock screen password authentication| × |
29| Facial authentication| √ |
30| Fingerprint authentication| √ |
31| Facial + fingerprint authentication<sup>18+</sup>| √ |
32| Facial + lock screen password authentication| × |
33| Fingerprint + lock screen password authentication| × |
34| Facial + fingerprint + lock screen password authentication| × |
35
36## Development Example
37
38For details about how to initiate the authentication request in the transition from a system-supported authentication to a custom authentication, see [initiating authentication](start-authentication.md). Ensure that the **widgetParam** parameter passed in must contain **navigationButtonText**.
39
40This example only shows how to configure the UI and select the custom authentication UI. You need to add the code for launching the custom authentication page at the commented line in the example.
41
42```ts
43import { BusinessError } from  '@kit.BasicServicesKit';
44import { cryptoFramework } from '@kit.CryptoArchitectureKit';
45import { userAuth } from '@kit.UserAuthenticationKit';
46
47try {
48  const rand = cryptoFramework.createRandom();
49  const len: number = 16;
50  let randData: Uint8Array | null = null;
51  let retryCount = 0;
52  while(retryCount < 3){
53    randData = rand?.generateRandomSync(len)?.data;
54    if(randData){
55      break;
56    }
57    retryCount++;
58  }
59  if(!randData){
60    return;
61  }
62  const authParam: userAuth.AuthParam = {
63    challenge: randData,
64    authType: [userAuth.UserAuthType.FACE],
65    authTrustLevel: userAuth.AuthTrustLevel.ATL3,
66  };
67  // Set navigationButtonText for the authentication page.
68  const widgetParam: userAuth.WidgetParam = {
69    title: 'Verify identity',
70    navigationButtonText: 'Use password',
71  };
72  // Obtain an authentication object.
73  const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
74  console.info('get userAuth instance success');
75  // Subscribe to the authentication result.
76  userAuthInstance.on('result', {
77    onResult(result) {
78      // If the ResultCode 12500000 is returned, the operation is successful.
79      console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`);
80      // If the ResultCode 12500011 is returned, the user taps the navigation button to switch to the custom authentication page.
81      if (result.result == 12500011) {
82        // You need to implement the process of launching the custom authentication page.
83      }
84    }
85  });
86  console.info('auth on success');
87  userAuthInstance.start();
88  console.info('auth start success');
89} catch (error) {
90  const err: BusinessError = error as BusinessError;
91  console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`);
92}
93```
94