Developer Pages

# Account recovery

Page contents

# Overview

Our account recovery feature allows the end-user to recover their registration without the need for reactivation with a new activation code.

Account recovery is currently only supported with the CLOUD_BACKUP recovery method. This is fully compliant with the Android Auto Backup (opens new window) feature.

# How to enable file backup in the app

Account recovery generates secrets that are tied to a specific device. Those secrets are stored inside the app files, which need to be backed up by the end-user. To do this, you need to ensure the following:

  1. Your application needs to declare allowBackup in its manifest files.
android:allowBackup="true"
  1. The file 2c5f882341aa8372a6166769bd469903.xml cannot be excluded from the backup in the application manifest section.

Note

You can skip this step if the manifest does not include the fullBackupContent or dataExtractionRules attribute.

For more information about fullBackupContent and dataExtractionRules, see the Backup/restore section in our Encap SDK developer documentation.

  1. The end-user needs to enable backup in their mobile device's settings. To do this, they can either:

    • Set up a Google account and enable auto backup to Google Drive.
    • Set up a cloud backup specific to the their mobile device's manufacturer, for example Samsung Cloud.
    • Transfer data from another mobile device.
    • Perform a manual backup to the external storage.

Note

Google's auto backup is the most convenient way of backing up and restoring data. However, it runs on its own and in some cases files can be backed up with a delay reaching up to 24 hours.

This makes recovery on another device impossible until that particular point in time.

# Token authorisation

Operations introduced in the account recovery feature require an EncapToken. This token is used to authorise the next operation after a successful activation or authentication.

For example, this makes it possible to implement an activation flow that both activates the end-user and sets up recovery for the registration, without an additional authentication.

The authorisation token is issued by our server and returned back to the app as a response when performing certain SDK operations.

To get an authorisation token, you have to specify what purpose (TokenPurpose) you are going to use the token for in the finish operation in the SDK. You can find an overview of the operations that can yield a token below.

Note

Operations will not yield a token unless a TokenPurpose is provided.

# Operations that can yield a token

  • finishActivation
  • finishAuthentication
  • finishAddOrUpdateRecovery
  • finishRecovery
  • finishDeleteRecovery

# Operations that require a token

  • startAddOrUpdateRecovery
  • startDeleteRecovery

# Token Purpose

  • TokenPurpose.ADD_OR_UPDATE_RECOVERY
  • TokenPurpose.DELETE_RECOVERY
  • TokenPurpose.UNSET_PURPOSE

Note

The default value is TokenPurpose.UNSET_PURPOSE.

# How to implement account recovery

The operations addOrUpdateRecovery and deleteRecovery require an EncapToken. See the operations that can yield a token section for a complete list.

# How to get a token

  1. You can request an Encap token by setting the token purpose together with the activation or authentication parameter, using the setTokenPurpose method.
  • If adding or updating recovery, you should use TokenPurpose.ADD_OR_UPDATE_RECOVERY.
  • If deleting recovery, you should use TokenPurpose.DELETE_RECOVERY.

Example: How to request a token during activation

ActivationParameter activationParameter = new DevicePinActivationParameter();
activationParameter.setTokenPurpose(TokenPurpose.ADD_OR_UPDATE_RECOVERY);
  1. The token will be returned with the usual operation response. You can access it using the example shown below.

Example: How to access a token

@Override
public void onSuccess(final FinishActivationResult result) {
    EncapToken token = result.getEncapToken();
}

# Activate account recovery

Next, you have to add account recovery and connect it to the end-user’s registration. To do this:

  1. Call startAddOrUpdateRecovery and pass in the EncapToken you acquired from the previous step.
  2. If this is successful, then you can call finishAddOrUpdateRecovery with an EncapRecoveryParameter.

Note

The EncapRecoveryParameter takes a RecoveryMethod, and a RecoveryCode that the end-user creates. The end-user needs to use this code when they perform a recovery later on.

Example: How to activate account recovery

 encapController.startAddOrUpdateRecovery(<ENCAP_TOKEN>, new AsyncCallback<StartAddOrUpdateRecoveryResult>() {
    @Override
    public void onFailure(ErrorCodeException errorCodeException) { ... }

    @Override
    public void onSuccess(StartAddOrUpdateRecoveryResult result) { ... }
});

EncapRecoveryParameter encapRecoveryParameter = new EncapRecoveryParameter(RecoveryMethod.CLOUD_BACKUP, <RECOVERY_CODE>);

encapController.finishAddOrUpdateRecovery(encapRecoveryParameter, new AsyncCallback<FinishAddOrUpdateRecoveryResult>() {
    @Override
    public void onFailure(ErrorCodeException errorCodeException) { ... }

    @Override
    public void onSuccess(FinishAddOrUpdateRecoveryResult result) { ... }
});

# Perform account recovery

You can recover an end-user's registration by using the startRecovery and finishRecovery operations. This works similarly in concept to the activation process, where a new authentication method must be selected and enabled.

You can only enable one authentication method for a single recovery. If you want to add more authentication methods, then these can be enabled by using the addOrUpdate operation.

Example: How to perform an account recovery

encapController.startRecovery(new AsyncCallback<StartRecoveryResult>() {
    @Override
    public void onFailure(ErrorCodeException errorCodeException) { ... }

    @Override
    public void onSuccess(StartRecoveryResult result) { ... }
});

encapController.finishRecovery(new EncapRecoveryParameter(RecoveryMethod.CLOUD_BACKUP, <RECOVERY_CODE>), new DevicePinActivationParameter(<PIN_CODE>)
	, new AsyncStateChangedCallback<FinishRecoveryResult>() {

	@Override
	public void onFailure(final ErrorCodeException errorCodeException) { ... }

	@Override
	public void onSuccess(final FinishRecoveryResult result) { ... }

	@Override
	public void onStateChanged(State state) { ... }
});

What is the recovery code?

The <RECOVERY_CODE> is a secret code that is provided by the end-user, and is only known by them.

  • The end-user chooses the recovery code, which is a parameter to the finishAddOrUpdateRecovery() operation.
  • The end-user must then provide the same recovery code as a parameter to the finishRecovery() operation.
  • The end-user's choice of authentication method to activate is also a parameter to the finishRecovery() operation.

# Delete a recovery

You can remove an active recovery by performing the startDeleteRecovery and finishDeleteRecovery operations.

The <ENCAP_TOKEN> has to be requested with an authentication, and must have the token purpose set to DELETE_RECOVERY.

Example: How to delete a recovery

encapController.startDeleteRecovery(<ENCAP_TOKEN>, new AsyncCallback<StartDeleteRecoveryResult>() {
            @Override
            public void onFailure(ErrorCodeException errorCodeException) { ... }

            @Override
            public void onSuccess(StartDeleteRecoveryResult result) { ... }
        });
        
EncapRecoveryParameter encapRecoveryParameter = new EncapRecoveryParameter(RecoveryMethod.CLOUD_BACKUP, "");
        
encapController.finishDeleteRecovery(encapRecoveryParameter, new AsyncCallback<FinishDeleteRecoveryResult>() {
            @Override
            public void onFailure(ErrorCodeException errorCodeException) { ... }

            @Override
            public void onSuccess(FinishDeleteRecoveryResult result) { ... }
        });

# Detecting recovery on a device

You can check whether account recovery has been activated on a device by using the method:

encapController.isRecoveryActivated()

Note

In order for the method to detect account recovery, backup has to be restored on the new device first.

You can use the following app flow to detect that a restore from backup has occurred:

  1. Check that isActivated() is returning false.
  2. Check that isRecoveryActivated() is returning true before performing an account recovery.
if(encapController.isActivated() == false && encapController.isRecoveryActivated() == true) {
	// recovery has been activated and can be used to recover registration
}
Last updated: 04/03/2024 15:17 UTC

← App attestation →