Skip to main content

Advanced usage

For users that would like to go the extra mile in terms of customization of the plugin, this page will learn you how to customize Headlockr’s security features by configuring environment variables. Our system uses the AES-256-GCM encryption standard to securely protect sensitive data. AES-256-GCM (Advanced Encryption Standard with Galois/Counter Mode) is a highly secure and widely trusted encryption method that ensures both data confidentiality and integrity through authenticated encryption.

How It Works​

We use the following approach for encryption and decryption:

  • Encryption Key: A 32-byte Base64-encoded secret key used for encryption/decryption.
  • Initialization Vector (IV): A 16-byte Base64-encoded random value ensuring unique ciphertexts.
  • Authentication Tag: Ensures data integrity and prevents tampering.

Key Validation During Strapi’s Bootstrap Lifecycle​

Before encryption/decryption, Headlockr validates the following:

  • Encryption Key Length: Must be 32 bytes (Base64-encoded).
  • IV Length: Must be 16 bytes (Base64-encoded).

If these lengths are incorrect, Headlockr logs an error and terminates the process.

Auth Configuration Reference

The auth config object in the headlockr plugin configuration is used to secure you multifactor authentications system.

Auth - Encryption IV​

Headlockr provides backup codes for account recovery. These codes are hashed by default for security reasons and displayed only once. Alternatively, you can enable encryption mode for more flexible recovery. In this mode, codes are encrypted and can be displayed securely multiple times after passing a challenge. For this feature to work, the user has to configure a unique Encryption IV ENCRYPTION_IV_HEADLOCKR_BACKUP and a unique Encryption Key ENCRYPTION_KEY_HEADLOCKR_BACKUP that will be used internally by Headlockr to encrypt a backupcode and store it securely.

Generate an Encryption IV & Key​

# Generate a 16-byte Encryption IV
openssl rand -base64 16

# Generate a 32-byte Encryption Key
openssl rand -base64 32
tip

Please note that the generation of Encryption IV & Key also applies for the environment variables ENCRYPTION_KEY_HEADLOCKR and ENCRYPTION_IV_HEADLOCKR

Auth - Secret​

Headlockr uses a Secret Key to sign temporary Multi-Factor Authentication (MFA) tokens, ensuring they cannot be tampered with.

How It Works​

  • This secret is NOT the same as Strapi’s native auth.secret.
  • Headlockr auth.secret is used only for shortlived MFA (multifactor authentication) tokens during the initial login.
  • Shortlived mfa tokens do not give the user permission to do anything else besides using it for solving MFA challenges
  • After completing the MFA process, the user is issued a token with full access based on their roles permissions and allows them to login to the admin panel

Auth - Phone Token Secret​

Before a phone number can be used as a sms multifactor authentication method within Headlockr, it needs to be registered and validated. This registration process is explained in depth in the SMS Authentication guide.

During this process a so called phone token secret is being issued after you have succefully solved the sms OTP Challenge. Without this token you won't be able to register a phone number into Headlockr. The so called Phone Token Secret makes sure that the phone token returned by the server cannot be tampared with.

Create a unique phone token secret​

openssl rand -base64 12

Paste your generated phone token secret in your .env file.

PHONE_TOKEN_SECRET=your-phone-token-secret ⚡️

Auth - Options​

You can customize short-lived token settings for Headlockr by passing any standard JWT option/claim supported by official JWT libraries.

Examples:

  • Token Expiration (expiresIn)
  • Audience Validation (audience)
  • Token Issuer (issuer)

Best Practices & Security Considerations​

  • Use Unique Secrets: Always generate fresh secrets for each deployment.
  • Store Secrets Securely: Use a secure storage solution like a secrets manager.
  • IV Rotation: Consider regularly rotating your IV and Key for enhanced security.