Password end-to-end encryption configuration in the Loginapp REST API

This article explains how to configure password end-to-end encryption in the Loginapp REST API. It does so using the Username Password Authentication Step as an example.

Make sure to enable password end-to-end encryption in all flows that let the end-user enter a password.

For consistent end-to-end encryption, all password-related steps have to be configured with E2EE!

In the following example configurations, a Username Password Authentication Step (typically the first password-related authentication step) is configured with end-to-end password encryption (E2EE).

• Procedure summary:
• In the Username Password Authentication Step, a Default End-To-End Encryption Password Repository is configured instead of the originally configured password repository plugin. It decrypts the password and passes the plain password to the originally used password repository.
• Inside the Default End-To-End Encryption Password Repository the configuration is as follows:
• Set the decryption type and with it configure the cryptographic keys.
• Configure the originally used password repository.

• An IAM Authentication Flow with a Username Password Authentication Step (but without E2EE) is configured for the target application.
• Key store information must be available:
• For configuration case 1 with a Java key store, a JKS or JCEKS key store file is available and the passwords to access it must be known. See also Using standard keystore tools.
• For configuration case 2 with an HSM, a compatible hardware security module must be available and information for its connection to Airlock IAM available. See HSM encryption support for passwords.

To enable password end-to-end encryption in a Username Password Authentication Step, proceed as follows:

1. Go to:
   Loginapp >> Authentication Flows >> affected application >> Authentication Flow
2. In property Steps edit the Username Password Authentication Step plugin.
3. In property Password Repository :
1. Note down the type and identifier of the password repository (Default Password Repository, External Database Password Repository, or alike) configuration for later reuse in step 4 of this instruction.
2. To replace the current password repository, create and edit the Default End-To-End Encryption Password Repository plugin.
4. At this point, we start configuring a new E2EE password repository plugin that can be reused for other password-related steps.
5. In property Internal Password Repository, add the password repository from step 3a to restore the original password repository settings.
6. In property Password Decryption, create and edit a JWE Password Decryption plugin to set the type of password decryption. Remember that password encryption is done by JavaScript code in the end-user's browser if using the Loginapp REST UI.
7. In property Key Pair, create and edit a Public/Private JWK Configuration plugin.

The rest of the configuration depends on whether a Java key store (Case 1) is used or an HSM (Case 2) is used. See below.

Configuration step 3 can be repeated on other step plugins that let the user enter a password.

The shown configuration works with the Loginapp REST UI out of the box.

1. In property Key Store, create and edit a Java keystore.
1. In property Keystore Type, select JKS - Default or JCEKS for the type of the used Java keystore. You may specify another key type, e.g. PKCS12, as long as it is supported by the underlying implementation.
2. In property Keystore File, add the path to the key store file, e.g. /opt/airlock/keystore.jks.
3. In property Keystore Password, add the password to access the key store.
2. Go back to the Key Pair plugin. In property Key Pair Alias, add the entry name of the key pair in the Java key store. It specifies which key pair to use for the E2EE feature (usually there are multiple entries in a key store).
3. Optionally, in property Private Key Password, add a password to access the private key of the selected key pair.
4. At this point, JavaScript code of the Loginapp REST UI will automatically encrypt the end-user's password. Airlock IAM calls the Java key store to receive the decrypted password.

This configuration case is only supported by the Loginapp REST UI if the HSM supports the decryption scheme implemented by the Loginapp REST UI. See separate section below.

1. In property Key Store, create and edit an HSM keystore and configure it according to the HSM's documentation. Refer to the property descriptions in the Config Editor for further information.
2. Go back to the Key Pair plugin. In property Key Pair Alias, add the entry name of the key pair in the HSM key store. It specifies which key pair to use for the E2EE feature (usually there are multiple entries in a key store).
3. Optionally, in property Private Key Password, add a password to access the private key of the selected key pair.
4. At this point, third-party clients that support HSM encryption can communicate with the Loginapp REST API. Airlock IAM calls the HSM key store to receive the decrypted password. The Loginapp REST UI can be used with the HSM if the HSM meets the requirements documented below.

As stated in the intro part of this section, E2EE must be configured consistently for all password-related steps linked to the corresponding target application(s) to ensure that passwords are never transmitted unencrypted. This applies not only to authentication flows but also to other Airlock IAM flow types where password steps are configured.

• For example in:
• Authentication flows: password check, mandatory and voluntary password change.
• Public self-services: password reset.
• Self-registration flows: when setting an initial password.
• Protected self-services: voluntary password change.

The system encrypting the password must do this in such a way that the decrypting code in Airlock IAM can decrypt it. The exact way passwords have to be encrypted is specified in the plugin documentation of plugin JWE Password Decryption.

• This imposes the following restrictions:
• REST clients, e.g. in custom loginapp front-ends, must encrypt passwords according to the documentation in JWE Password Decryption.
• The Loginapp REST UI works with HSMs that support decryption as specified in plugin JWE Password Decryption.

• End-to-End Encryption of passwords
• HSM encryption support for passwords
• Using standard keystore tools
• Password end-to-end encryption configuration