You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can require the user authentication to obtain credentials. This will make the manager prompt the user with the device's configured Lock Screen, which they must pass correctly in order to obtain the credentials. **This feature is only available on devices where the user has setup a secured Lock Screen** (PIN, Pattern, Password or Fingerprint).
522
520
523
-
To enable authentication you must call the `requireAuthentication` method passing a valid _Activity_ context, a request code that represents the authentication call, and the title and description to display in the Lock Screen. As seen in the snippet below, you can leave these last two parameters with `null` to use the system's default title and description. It's only safe to call this method before the Activity is started.
521
+
To enable authentication you must supply an instance of `FragmentActivity` on which the authentication prompt to be shown, and an instance of `LocalAuthenticationOptions` to configure the authentication prompt with details like title and authentication level when creating an instance of `SecureCredentialsManager` as shown in the snippet below.
524
522
525
523
```kotlin
526
-
//You might want to define a constant with the Request Code
When the above conditions are met and the manager requires the user authentication, it will use the activity context to launch the Lock Screen activity and wait for its result. If your activity is a subclass of `ComponentActivity`, this will be handled automatically for you internally. Otherwise, your activity must override the `onActivityResult` method and pass the request code and result code to the manager's `checkAuthenticationResult` method to verify if this request was successful or not.
#### Creating LocalAuthenticationOptions object for requiring Authentication while using SecureCredentialsManager
559
+
560
+
`LocalAuthenticationOptions` class exposes a Builder class to create an instance of it. Details about the methods are explained below:
561
+
562
+
-**setTitle(title: String): Builder** - Sets the title to be displayed in the Authentication Prompt.
563
+
-**setSubTitle(subtitle: String?): Builder** - Sets the subtitle of the Authentication Prompt.
564
+
-**setDescription(description: String?): Builder** - Sets the description for the Authentication Prompt.
565
+
-**setAuthenticationLevel(authenticationLevel: AuthenticationLevel): Builder** - Sets the authentication level, more on this can be found [here](#authenticationlevel-enum-values)
-**setNegativeButtonText(negativeButtonText: String): Builder** - Sets the negative button text, used only when the device credential fallback is disabled (or) the authentication level is not set to `AuthenticationLevel.DEVICE_CREDENTIAL`.
568
+
-**build(): LocalAuthenticationOptions** - Constructs the LocalAuthenticationOptions instance.
569
+
569
570
570
-
If the manager consumed the event, it will return true and later invoke the callback's `onSuccess` with the decrypted credentials.
571
+
#### AuthenticationLevel Enum Values
571
572
573
+
AuthenticationLevel is an enum that defines the different levels of authentication strength required for local authentication mechanisms.
574
+
575
+
**Enum Values**:
576
+
-**STRONG**: Any biometric (e.g., fingerprint, iris, or face) on the device that meets or exceeds the requirements for Class 3 (formerly Strong).
577
+
-**WEAK**: Any biometric (e.g., fingerprint, iris, or face) on the device that meets or exceeds the requirements for Class 2 (formerly Weak), as defined by the Android CDD.
578
+
-**DEVICE_CREDENTIAL**: The non-biometric credential used to secure the device (i.e., PIN, pattern, or password).
572
579
573
580
### Handling Credentials Manager exceptions
574
581
@@ -579,6 +586,27 @@ In the event that something happened while trying to save or retrieve the creden
579
586
- Device's Lock Screen security settings have changed (e.g. the PIN code was changed). Even when `hasCredentials` returns true, the encryption keys will be deemed invalid and until `saveCredentials` is called again it won't be possible to decrypt any previously existing content, since they keys used back then are not the same as the new ones.
580
587
- Device is not compatible with some of the algorithms required by the `SecureCredentialsManager` class. This is considered a catastrophic event and might happen when the OEM has modified the Android ROM removing some of the officially included algorithms. Nevertheless, it can be checked in the exception instance itself by calling `isDeviceIncompatible`. By doing so you can decide the fallback for storing the credentials, such as using the regular `CredentialsManager`.
581
588
589
+
You can access the `code` property of the `CredentialsManagerException` to understand why the operation with `CredentialsManager` has failed and the `message` property of the `CredentialsManagerException` would give you a description of the exception.
590
+
591
+
Starting from version `3.0.0` you can even pass the exception to a `when` expression and handle the exception accordingly in your app's logic as shown in the below code snippet:
592
+
593
+
```kotlin
594
+
when(credentialsManagerException) {
595
+
CredentialsManagerException.NO_CREDENTIALS-> {
596
+
// handle no credentials scenario
597
+
}
598
+
599
+
CredentialsManagerException.NO_REFRESH_TOKEN-> {
600
+
// handle no refresh token scenario
601
+
}
602
+
603
+
CredentialsManagerException.STORE_FAILED-> {
604
+
// handle store failed scenario
605
+
}
606
+
// ... similarly for other error codes
607
+
}
608
+
```
609
+
582
610
## Bot Protection
583
611
If you are using the [Bot Protection](https://auth0.com/docs/anomaly-detection/bot-protection) feature and performing database login/signup via the Authentication API, you need to handle the `AuthenticationException#isVerificationRequired()` error. It indicates that the request was flagged as suspicious and an additional verification step is necessary to log the user in. That verification step is web-based, so you need to use Universal Login to complete it.
-**Constructor**: The constructor of the `Auth0` class is now private. Use `Auth0.getInstance(clientId, domain)` to get an instance. This method checks if an instance with the given configuration exists; if yes, it returns it, otherwise, it creates a new one.
7
+
8
+
### BaseCredentialsManager Interface
9
+
-**New Methods**: Added multiple overloads of `getCredentials()` and `awaitCredentials()` to the `BaseCredentialsManager` interface. All implementations of this interface must now override these new methods.
10
+
11
+
### Request Interface
12
+
-**await Function**: The `await` function of the `Request` interface is now abstract. All implementations must implement this method.
13
+
14
+
### Credentials Class
15
+
-**Data Class**: The `Credentials` class is now a data class and can no longer be extended. The `currentTimeInMillis` property has been removed.
16
+
17
+
### SecureCredentialsManager
18
+
-**requireAuthentication Method**: The `requireAuthentication` method, used to enable authentication before obtaining credentials, has been removed. Refer to the [Enabling Authentication](#enabling-authentication-before-obtaining-credentials) section for the new approach.
19
+
20
+
## Changes
21
+
22
+
### Biometrics Authentication
23
+
-**Library Update**: Implementation of biometrics authentication for retrieving credentials securely is now done using the `androidx.biometric.biometric` library.
24
+
25
+
### CredentialsManagerException
26
+
-**Enum Code**: The `CredentialsManagerException` now contains an enum code. You can use a `when` expression to handle different error scenarios:
27
+
28
+
```kotlin
29
+
when (credentialsManagerException) {
30
+
CredentialsManagerException.NO_CREDENTIALS-> {
31
+
// handle no credentials scenario
32
+
}
33
+
CredentialsManagerException.NO_REFRESH_TOKEN-> {
34
+
// handle no refresh token scenario
35
+
}
36
+
CredentialsManagerException.STORE_FAILED-> {
37
+
// handle store failed scenario
38
+
}
39
+
// ... similarly for other error codes
40
+
}
41
+
```
42
+
43
+
## Enabling Authentication before Obtaining Credentials
44
+
45
+
To enable authentication before obtaining credentials, you need to pass the below to the constructor of `SecureCredentialsManager`:
46
+
- An instance of `FragmentActivity` where the authentication prompt should be shown.
47
+
- An instance of `LocalAuthenticationOptions` to configure details like the level of authentication (Strong, Weak), prompt title, etc.
If you need more information, please refer to the [examples.md](examples.md#requiring-authentication) file under the section **Requiring Authentication**.
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments