Key Manager

Subscription

Liferay DXP 2026.Q4+

The Key Manager connects Liferay DXP to AWS to protect passwords and encryption keys. In FIPS mode, DXP stores each password or other secret you save in AWS Secrets Manager and keeps only a reference to it. With FIPS mode on or off, DXP can also wrap each virtual instance’s company key with an AWS KMS key. A company key is the encryption key DXP generates for a virtual instance, and wrapping encrypts it.

Both features use the AWS profile, a set of Key Manager settings that connects DXP to your AWS account. For every field and message, see Key Manager Reference.

Important

Configure and activate the AWS profile before you turn on FIPS mode. The Custom profile’s default provider IDs name providers DXP doesn’t include, so saving a password or other secret in FIPS mode fails while they’re set.

Prerequisites

Prepare AWS before you configure anything in DXP:

Credentials: DXP reads AWS credentials only from the AWS default credential provider chain, such as an EC2 instance profile or the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. No Key Manager field accepts static credentials. Make them available to the DXP JVM on every cluster node.
KMS Key: DXP doesn’t create KMS keys, so create one in AWS before you activate the profile. In FIPS mode, or with Strict Mode checked, the key’s origin must be AWS_KMS or AWS_CLOUDHSM. One KMS key can serve both the AWS profile and company key wrapping.
IAM Permissions: Grant the credentials kms:Encrypt, kms:Decrypt, and kms:DescribeKey on the KMS keys that Key ARN Template and Company KEK Identifier resolve to (see ARN Templates). For storing secrets, also grant secretsmanager:GetSecretValue, secretsmanager:PutSecretValue, secretsmanager:CreateSecret, and secretsmanager:DeleteSecret on the secrets DXP creates.

To use AWS IAM Identity Center (SSO), export the session’s temporary credentials, including AWS_SESSION_TOKEN, in the shell that starts DXP, because the default credential provider chain doesn’t read SSO profiles:

eval "$(aws configure export-credentials --profile [profile] --format env)"

When the SSO session expires, AWS rejects DXP’s requests until you export new credentials and restart DXP.

Turning On the Key Manager Feature Flag

The Key Manager feature flag (LPD-88411) is system scoped and off by default.

Go to Control Panel → System Settings → Platform → Feature Flags → Beta.
Toggle Key Manager to enable it.

The flag controls only whether the Key Manager category appears at Control Panel → System Settings → Security → Key Manager. With the flag off, set these configurations with configuration files.

Configuring and Activating the AWS Profile

Go to Control Panel → System Settings → Security → Key Manager and click AWS Key Manager Profile Configuration.
Fill in these fields. In FIPS mode, strict mode is always on.

AWS Account ID: Enter the AWS account ID. If you leave it blank, DXP looks it up through AWS STS, and every node must have an AWS default region, such as AWS_REGION, even when AWS Region is set.

AWS Region: Enter the region of the KMS key and secrets, such as us-east-1. In strict mode, use a region where AWS Secrets Manager has a FIPS endpoint: a US, Canada, or AWS GovCloud (US) region (see AWS Secrets Manager endpoints).

Key ARN Template: Enter the KMS key’s ARN, or a template that resolves to it, such as arn:aws:kms:{region}:{accountId}:key/[key-id]. Strict mode requires it. For its placeholders, see ARN Templates.

Strict Mode: With FIPS mode off, check it to use strict mode.

Vault Layer: Leave it at AWS, the default.
Click Save.
In the Key Manager category, click Key Manager Configuration.
In Active Profile ID, enter aws.
Click Save.
Open AWS KMS System Crypto Provider Configuration. If activation succeeded, Enabled is checked and AWS Region shows the profile’s region.

If it didn’t, check that Active Profile ID is exactly aws, because a mismatch logs nothing (see Key Manager Configuration). Then find Unable to initialize key manager profile: aws and its cause in the DXP log (see Activating the AWS Profile). Correct the cause and save Key Manager Configuration again to retry.

Make later changes to the AWS settings in AWS Key Manager Profile Configuration. Activation and every DXP start overwrite the AWS settings in the four provider entries with the profile’s values, and some profile changes take effect only after a restart (see AWS Key Manager Profile Configuration).

Storing Secrets Under One Name Prefix

You can store every secret under one name prefix, for example to scope IAM permissions to DXP’s secrets. Set it before DXP stores its first secret (see ARN Template in AWS Secrets Manager Secret Provider Configuration).

Go to Control Panel → System Settings → Security → Key Manager.
In AWS Secrets Manager System Secret Provider Configuration and AWS Secrets Manager Company Secret Provider Configuration, set ARN Template to a template with the prefix, such as arn:aws:secretsmanager:{region}:{accountId}:secret:liferay/{identifier}, and click Save.
Grant the Secrets Manager actions on arn:aws:secretsmanager:[region]:[account]:secret:liferay/*.

Storing Secrets in FIPS Mode

In FIPS mode, DXP stores each Password-type configuration field, OAuth2 client secret, time-based one-time password enrollment, and other sensitive value in AWS Secrets Manager when you save it. It keeps a secret reference in place of the value.

To confirm that the Key Manager stores secrets, save a Password-type field in System Settings, and check the AWS Secrets Manager console for the new secret. With ARN Template blank, the secret’s name is its identifier, such as config/[pid]/0/[attributeId] for a system-scoped field, where [pid] is the configuration’s ID and [attributeId] is the field’s ID.

DXP stores a value only when you save it. Values saved before you turned on FIPS mode stay in plain text in the database until you save them again.

With the AWS profile active, enter the value itself in a Password-type field. DXP stores a $[env:...] or $[secret:...] placeholder in Secrets Manager as literal text, and the component receives the placeholder instead of the value.

Changing the Active Profile

Changing Active Profile ID leaves stored secrets where they are. Configuration fields and preferences hold references that name their provider, so they keep resolving while that provider stays deployed, configured, and reachable. The exception is a configuration field or preference saved at system scope and read by a virtual instance. It fails once the active profile’s system secret provider is no longer aws-system-secret, including when Vault Layer is set to DB.

Important

OAuth2 client secrets and time-based one-time password secrets use wildcard references (${secretRef:*:...}) that follow the active profile. Changing Active Profile ID or Vault Layer after secrets are stored breaks OAuth2 client authentication and time-based one-time password verification once each node’s cache expires, within ten minutes. DXP shows no warning.

Wrapping Company Keys

Company KEK Identifier names the KMS key (the key encryption key, or KEK) that wraps company keys. It’s system scoped, so one value applies to every virtual instance. Wrapping uses the AWS KMS company provider, which activating the AWS profile enables. With the Custom profile, enable it yourself, as described in Key Manager Reference.

Go to Control Panel → System Settings → Security → Key Manager and click Key Manager Configuration.
In Company KEK Identifier, enter the KMS key’s alias, such as alias/liferay-company-kek, or its ARN.
Click Save.

To wrap each virtual instance’s company key with a different KMS key, see Key ARN Template in AWS KMS Crypto Provider Configuration.

When Company KEK Identifier is set, DXP wraps each company key it generates:

When you create a virtual instance
When a virtual instance has no key
During the database upgrade that runs when you upgrade DXP. The upgrade regenerates every company key.

Until then, existing virtual instances keep plain text company keys.

To confirm wrapping works, create a test virtual instance. Creation succeeds only when DXP can wrap its key. If it fails, look up the log message in Key Manager Reference.

DXP keeps each decrypted company key in memory until it restarts or you save Key Manager Configuration again. After you disable the KMS key or remove DXP’s permission on it, restart each node.

Warning

Each wrapped company key records the Company KEK Identifier value that wrapped it, and only the KMS key that value resolves to can unwrap it. Once company keys are wrapped:

Don’t delete the KMS key. Its wrapped company keys become unrecoverable (see Deleting AWS KMS keys).
Keep the earlier KMS key when you change Company KEK Identifier. The new value wraps only keys generated afterward, and the earlier key still unwraps the rest.
Don’t point the key’s alias at a different key. The recorded identifier then resolves to a key that can’t unwrap them.
Don’t change the Key ARN Template in AWS KMS Company Crypto Provider Configuration when Company KEK Identifier resolves through it. The recorded identifier then resolves to a different key. An alias/ or arn: value doesn’t resolve through the template, because DXP uses it verbatim.
Don’t clear Company KEK Identifier. The next database upgrade fails with Unable to wrap the regenerated key for company [companyId].