Auth0.Android Saving and Renewing Tokens
When an authentication is performed with the
offline_access scope included, it will return a Refresh Token that can be used to request a new user token, without forcing the user to perform authentication again.
Auth0.Android provides a utility class to streamline the process of storing and renewing credentials. You can access the
idToken properties from the Credentials instance. This is the preferred method to manage user credentials.
Credential Managers are included as part of the Auth0.Android SDK. If this is not part of your dependencies yet, make sure to check the documentation.
Next, decide which class to use depending on your Android SDK target version.
API less than 21
If you require APIs lower than 21 (Lollipop) create a new instance of
CredentialsManager. This class makes use of the
Context.MODE_PRIVATE to store the credentials in a key-value preferences file, accessible only to your app. The data is stored in plaintext.
API equal to or greater than 21
If you require APIs equal or greater than 21 (Lollipop) create a new instance of
SecureCredentialsManager. This class has the same methods as the one above, but encrypts the data before storing it using a combination of RSA and AES algorithms along with the use of Android KeyStore.
Using the CredentialsManager class
Setup the CredentialsManager
Create a new instance by passing an
AuthenticationAPIClient and a
Current State of the Authentication
Stored credentials are considered valid if they have not expired or can be refreshed. Check if a user has already logged in:
When you want to log the user out of your app, remove the stored credentials and direct them to the login screen.
Because the credentials may need to be refreshed against Auth0 Servers, this method is asynchronous. Pass a callback implementation where you'd like to receive the credentials. Credentials returned by this method upon success are always valid.
Save new Credentials
You can save the credentials obtained during authentication in the manager.
Using the SecureCredentialsManager class
Setup the SecureCredentialsManager
Setup is a little different to the CredentialsManager class. Create a new instance by passing a valid android
AuthenticationAPIClient and a
The methods to obtain, save, check for existence and clearing the credentials are the ones explained before.
Pre-Authenticate the User
This class provides optional functionality for additional authentication using the device's configured Lock Screen. If the Lock Screen Security is set to something different than PIN, Pattern, Password or Fingerprint, this feature won't be available. You need to call the method below to enable the authentication. Pass a valid
Activity context, a request code, and 2 optional Strings to use as title and description for the Lock Screen.
If the feature was enabled, the manager will prompt the user to authenticate using the configured Lock Screen. The result of this call will be obtained in the
onActivityResult method of the activity passed before as first parameter. If the feature was not enabled, Lock Screen authentication will be skipped.
After checking that the received request code matches the one used in the configuration step, redirect the received parameters to the manager to finish the authentication. The credentials will be yield to the original callback.
Handling usage exceptions
In the event that something happened while trying to save or retrieve the Credentials, a
CredentialsManagerException will be thrown. These are some of the failure scenarios you can expect:
- The Credentials to be stored are invalid, e.g. some of the following fields are not defined: access_token, id_token or expires_at.
- The stored Credentials have expired but there is no refresh_token available to renew them automatically.
- Device's Lock Screen security settings have changed (e.g. the security PIN code was changed). Even when
hasCredentialsreturns true, the encryption keys will be deemed invalid and until
saveCredentialsis 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.
- Device is not compatible with some of the cryptography algorithms required by the
SecureCredentialsManagerclass. This is considered a catastrophic event and is the only exception that will prevent you from using this implementation. This scenario happens when the OEM has modified the Android ROM of the device removing some of the algorithms officially included in every Android distribution. Nevertheless, you can check if this is the case in the exception instance itself by calling the
isDeviceIncompatiblemethod. By doing so you can decide the fallback implementation for storing the Credentials, such as using the regular