Key Manager Reference
Subscription
Liferay DXP 2026.Q4+
This reference describes the system-scoped Key Manager settings in Liferay DXP, the secret reference format, and the messages DXP logs.
The category appears at Control Panel → System Settings → Security → Key Manager when the Key Manager beta feature flag (LPD-88411) is on. To set up the AWS profile, see Key Manager.
Key Manager Configuration
Key Manager Configuration selects the active profile and the KMS key that wraps company keys.
| Field | Default | Description |
|---|---|---|
| Active Profile ID | custom | Names the profile that chooses the crypto and secret providers. Set it to aws for the AWS profile. It’s a free text field. A value that matches no profile selects the Custom profile without a log message. With aws, saving this entry initializes the AWS profile if it hasn’t initialized since DXP started. |
| Company KEK Identifier | Blank | Names the KMS key that wraps each company key, for every virtual instance. When it’s blank, DXP stores newly generated company keys in plain text. It resolves through the AWS KMS Company Crypto Provider Configuration’s Key ARN Template (see ARN Templates). Before you change or clear it, see Wrapping Company Keys. |
Key Manager Custom Profile Configuration
The Custom profile is the default profile. Its fields name the providers for the data encryption key (DEK), key encryption key (KEK), and secret roles. No provider in DXP supplies the default IDs, so with those IDs, saving a secret fails in FIPS mode.
To point the Custom profile at AWS, set its provider IDs to the AWS providers: aws-company-crypto, aws-company-secret, and aws-system-secret. Then enable each AWS provider entry and set its region yourself, because no profile initialization fills them in.
| Field | Default | Description |
|---|---|---|
| Company DEK Provider ID | db-company-crypto | Names the provider for the company DEK role. |
| Company KEK Provider ID | db-company-crypto | Names the provider for the company KEK role. |
| Company Secret Provider ID | db-company-secret | Names the provider for secrets saved at virtual instance scope or below. |
| System DEK Provider ID | db-system-crypto | Names the provider for the system DEK role. |
| System KEK Provider ID | db-system-crypto | Names the provider for the system KEK role. |
| System Secret Provider ID | db-system-secret | Names the provider for secrets saved at system scope. |
AWS Key Manager Profile Configuration
AWS Key Manager Profile Configuration sets the account, region, and key the AWS profile uses.
| Field | Default | Description |
|---|---|---|
| AWS Account ID | Blank | Sets the AWS account for the {accountId} placeholder. When it’s blank, DXP looks up the account with the AWS STS GetCallerIdentity call. The lookup ignores AWS Region and takes its region only from the AWS default region chain, such as AWS_REGION or the EC2 instance’s region. Without a default region on every node, the profile doesn’t initialize. |
| AWS Region | Blank | Sets the AWS region for AWS KMS and AWS Secrets Manager. When it’s blank, DXP uses the AWS default region chain, which includes the AWS_REGION environment variable. |
| Key ARN Template | Blank | Sets the template that resolves to the KMS key the profile verifies when it initializes. It must name one specific key, so it can’t use {identifier}. Strict mode requires it. |
| Strict Mode | false | Turns on strict mode, which is always on in FIPS mode. Strict mode requires Key ARN Template, accepts only a key whose origin is AWS_KMS or AWS_CLOUDHSM, and turns on FIPS Enforced in the AWS KMS entries and Use FIPS Endpoint in all four provider entries. With it off, the profile runs in standard mode. Standard mode turns both off and logs a warning. |
| Vault Layer | AWS (aws) | AWS (aws) stores secrets in AWS Secrets Manager. DB (db) names db-system-secret and db-company-secret. No provider in Liferay DXP supplies them, so secret saves fail in FIPS mode. |
When the AWS profile initializes, on activation and at every DXP start, it overwrites these provider settings with the profile’s values, including values set by hand:
- In all four AWS KMS and AWS Secrets Manager provider entries: AWS Region, AWS Account ID (when known), Enabled, and Use FIPS Endpoint
- In the two AWS KMS provider entries: FIPS Enforced
After the profile has initialized, restart each node to apply a change to AWS Region, AWS Account ID, Key ARN Template, or Strict Mode. Setting Vault Layer to DB takes effect immediately, and setting it back to AWS takes effect after a restart.
AWS KMS Crypto Provider Configuration
AWS KMS System Crypto Provider Configuration and AWS KMS Company Crypto Provider Configuration have the same fields.
| Field | Default | Description |
|---|---|---|
| AWS Account ID | Blank | Sets the AWS account for the {accountId} placeholder. |
| AWS Region | Blank | Sets the AWS region of the KMS key and of the {region} placeholder. |
| Cipher Mode | AES_256_GCM | Sets the cipher mode DXP checks when FIPS Enforced is on. Only AES_256_GCM, AES_GCM, and SYMMETRIC_DEFAULT pass. DXP doesn’t send this value to AWS KMS, so it affects only that check. |
| Enabled | false | Turns the provider on. |
| FIPS Enforced | false | Requires an AEAD cipher mode in Cipher Mode, and a KMS key whose origin is AWS_KMS or AWS_CLOUDHSM. |
| Key ARN Template | Blank | Resolves a key identifier to a KMS key ARN (see ARN Templates). In the company entry, Company KEK Identifier resolves through it, and the {companyId} placeholder can make it a different key for each virtual instance. Activating the AWS profile doesn’t copy the profile’s Key ARN Template here. |
| Pending Window in Days | 30 | Sets the waiting period, from 7 to 30 days, that AWS applies to a KMS key scheduled for deletion. No DXP feature schedules a KMS key for deletion. |
| Use FIPS Endpoint | false | Sends requests to kms-fips.[region].amazonaws.com. |
AWS Secrets Manager Secret Provider Configuration
AWS Secrets Manager System Secret Provider Configuration and AWS Secrets Manager Company Secret Provider Configuration have the same fields.
| Field | Default | Description |
|---|---|---|
| ARN Template | Blank | Resolves a secret identifier to an AWS Secrets Manager secret ARN (see ARN Templates). DXP creates each secret the first time it stores it. Set the template before DXP stores the first secret. References keep only the identifier, so a later change makes DXP look for each stored secret under a new name. |
| AWS Account ID | Blank | Sets the AWS account for the {accountId} placeholder. |
| AWS Region | Blank | Sets the AWS region of the secrets and of the {region} placeholder. |
| Enabled | false | Turns the provider on. |
| Recovery Window in Days | 30 | Sets the recovery window, from 7 to 30 days, that AWS applies when DXP deletes a secret. DXP deletes a secret when you delete a configuration, an OAuth2 application, or a time-based one-time password enrollment, or disconnect Marketplace. |
| Use FIPS Endpoint | false | Sends requests to secretsmanager-fips.[region].amazonaws.com. |
ARN Templates
Key ARN Template and ARN Template accept these placeholders:
| Placeholder | Value |
|---|---|
{accountId} | The AWS account ID |
{region} | The AWS region |
{companyId} | The virtual instance’s company ID, or 0 for the system providers |
{identifier} | The key or secret identifier, such as the Company KEK Identifier value or an identifier from Secret References |
When the template is blank, or the identifier starts with alias/ or arn:, DXP uses the identifier verbatim.
The secret name is the part of the resolved value after :secret:, or the whole value when it has none. To store every secret under one name prefix, see Storing Secrets Under One Name Prefix.
Secret References
When DXP stores a secret with a provider, it keeps a secret reference in place of the value:
${secretRef:[providerId]:[identifier]}
With a provider ID of *, the active profile chooses the provider. OAuth2 client secrets and time-based one-time password secrets use this wildcard. Before you change the active profile, see Changing the Active Profile.
Each kind of stored value has its own identifier:
| Stored Value | Identifier |
|---|---|
| Configuration field | config/[pid]/[companyId]/[attributeId]. A ~ in a factory or scoped PID becomes /, and [companyId] is 0 at system scope. |
| Widget preference | preference/portlet/[plid]/[portletId]/[name] |
| Virtual instance preference | preference/company/[companyId]/[key] |
| Site preference | preference/group/[groupId]/[key] |
| OAuth2 client secret | The OAuth2 application’s ID |
| Time-based one-time password secret | MFATimeBasedOTPEntry/[id] |
| Marketplace token | Marketplace/[companyId]/[token name]/[uuid] |
In FIPS mode, a configuration or preference field accepts a typed ${secretRef:...} reference only when it names the field’s own identifier (for a preference, its last path segment). Outside FIPS mode, DXP saves a typed reference as you entered it.
DXP doesn’t resolve a reference in portal-ext.properties. To keep a sensitive value out of portal-ext.properties, see Sensitive Values.
DXP caches each resolved secret on each node for up to ten minutes, so a change reaches each node at a different time:
- A value changed directly in AWS Secrets Manager: up to ten minutes on each node.
- A configuration or preference value saved in DXP: immediately on the node that saves it, and within ten minutes on other cluster nodes.
- A new OAuth2 client secret: up to ten minutes even on the node that saves it. The previous secret can keep authenticating until then.
What FIPS Mode Stores
With fips.enabled=true, DXP stores the value of every non-empty Password-type configuration field with the active profile’s secret provider when you save it, at any scope: system, virtual instance, site, or widget. The field then holds a ${secretRef:...} reference. Storage doesn’t depend on the Key Manager feature flag. With FIPS mode off, these values stay in plain text.
DXP also stores these values, which aren’t configuration fields:
- OAuth2 client secrets, including the ones SCIM uses
- The Avalara connector’s license key
- The Facebook API key
- The Google Places and Google Maps API keys in virtual instance and site settings, and an asset library’s Google Maps API key set through the headless API
- The Iframe widget’s basic and form passwords
- The Marketplace access and refresh tokens
- The OAuth2 authorization server’s generated JWT signing key
- Time-based one-time password secrets
Custom fields with the Secret property are masked, but their values stay in plain text.
Messages
Activating the AWS Profile
A failure to initialize the AWS profile logs Unable to initialize key manager profile: aws, followed by its cause. Correct the cause and save Key Manager Configuration again. Warnings don’t stop initialization.
| Message | Level | Cause | Fix |
|---|---|---|---|
AWS profile is in standard mode and permits software backed CMKs | Warning | The AWS profile runs in standard mode. | To run in strict mode, check Strict Mode in AWS Key Manager Profile Configuration, or enable FIPS mode, and restart DXP. |
AWS credentials are not available from the default credential provider chain | Error | DXP found no AWS credentials. | Supply credentials through the AWS default credential provider chain. See Prerequisites. |
Configure "aws-region" or export "AWS_REGION" because the AWS region could not be resolved | Error | AWS Region is blank, and the AWS default region chain has no region. | Set AWS Region in AWS Key Manager Profile Configuration, or export AWS_REGION. |
Configure "key-arn-template" because strict mode requires a CMK to verify | Error | Key ARN Template is blank in strict mode. | Set Key ARN Template in AWS Key Manager Profile Configuration. |
Unable to verify AWS KMS key [arn] | Error in strict mode, warning in standard mode | The profile couldn’t verify the KMS key. | Create the KMS key in AWS before activating the profile, and give the credentials kms:DescribeKey on it. |
FIPS enforcement requires a CMK within the AWS FIPS boundary (origin AWS_CLOUDHSM or AWS_KMS) but the key origin is "[origin]" | Error | In strict mode, the KMS key’s origin isn’t AWS_KMS or AWS_CLOUDHSM. | Use a KMS key whose origin is AWS_KMS or AWS_CLOUDHSM. |
Unable to get AWS account ID via STS | Warning | AWS Account ID is blank, and the STS lookup failed for a reason other than a missing default region. Initialization continues without an account ID and fails only if Key ARN Template uses {accountId}. | Set AWS Account ID in AWS Key Manager Profile Configuration and restart each node. |
Unable to resolve AWS account ID for ARN template "[template]" | Error | The template contains {accountId}, and the account ID is unknown. | Set AWS Account ID in AWS Key Manager Profile Configuration and restart each node. |
Storing Secrets
These messages appear when DXP stores, reads, or deletes a secret. Provider [id] is not enabled and Unable to resolve AWS region for ARN template "[template]" can also appear when DXP wraps a company key.
| Message | Cause | Fix |
|---|---|---|
No secret provider found for secret provider ID [id] and company ID [n] | The active profile names an unregistered secret provider, db-system-secret or db-company-secret: the Custom profile, or the AWS profile with Vault Layer set to DB. | Activate the AWS profile with Vault Layer set to AWS. If the profile has already initialized, restart each node. See Configuring and Activating the AWS Profile. |
Provider [id] is not enabled | The provider’s Enabled field is off. Activating the AWS profile turns its providers on. | Check the log for Unable to initialize key manager profile: aws, correct its cause, and save Key Manager Configuration again. If Vault Layer was changed from DB to AWS after initialization, restart each node. |
Unable to resolve AWS region for ARN template "[template]" | A provider entry’s AWS Region is blank, and its template contains {region}. | Set AWS Region in AWS Key Manager Profile Configuration and restart each node. |
FIPS is enforced but the AWS Secrets Manager provider is not configured to use a FIPS endpoint | Use FIPS Endpoint was turned off in a Secrets Manager provider entry after a strict-mode activation. | Turn Use FIPS Endpoint back on. |
Unable to read AWS secret [arn] | DXP couldn’t read a stored secret, for example because the AWS credentials expired or lack secretsmanager:GetSecretValue. | Renew the credentials, or grant the permission. |
Unable to write AWS secret [arn] | DXP couldn’t write the secret to AWS Secrets Manager, for example because the AWS credentials expired. The save is refused. | Renew the credentials, and give them secretsmanager:PutSecretValue and secretsmanager:CreateSecret on the secrets. |
Configuration [pid] is declared by a static module and its credentials are not stored | The configuration is declared by a static module. DXP saves its value in plain text. | None. |
Unable to store "[identifier]" because it references "[other]" | In FIPS mode, a reference typed into a field names another field’s identifier. | Enter the value itself, or a reference with the field’s own identifier. |
Unable to parse the key reference | A reference doesn’t follow the reference format. | Enter the reference in the format in Secret References. |
Wrapping Company Keys
| Message | Cause | Fix |
|---|---|---|
KEK provider db-company-crypto is not registered for company [companyId] | A virtual instance was created with Company KEK Identifier set while the Custom profile keeps its default KEK provider ID. | Activate the AWS profile. See Configuring and Activating the AWS Profile. |
Unable to encrypt the key for company [companyId] | Creating a virtual instance couldn’t wrap its company key. The log shows the cause. | Find the cause’s message in the log, and apply the fix in its row in this table or in Storing Secrets. |
Unable to describe AWS KMS key [keyId] for FIPS validation | In strict mode, the key identifier doesn’t resolve to a KMS key, or the credentials lack kms:DescribeKey. | Create the KMS key in AWS, correct the identifier, or grant kms:DescribeKey. |
Unable to encrypt with AWS KMS key [keyId] | AWS KMS rejected the request: the identifier doesn’t resolve to a KMS key, or the credentials expired or lack kms:Encrypt. | Create the KMS key, correct the identifier, or renew the credentials and grant kms:Encrypt. |
FIPS enforcement requires an AEAD cipher mode but "[mode]" is not AEAD | FIPS Enforced is on, and Cipher Mode isn’t AES_256_GCM, AES_GCM, or SYMMETRIC_DEFAULT. | Set Cipher Mode to AES_256_GCM, AES_GCM, or SYMMETRIC_DEFAULT. |
The company key is stored in plaintext in FIPS mode because the KEK identifier is not configured for company [companyId] | In FIPS mode, DXP generated a company key while Company KEK Identifier was blank. | Activate the AWS profile, then set Company KEK Identifier (see Wrapping Company Keys). Existing company keys stay in plain text until they’re generated again. |
Unable to wrap the regenerated key for company [companyId] | A database upgrade regenerated a company key that was wrapped, and the new key couldn’t be wrapped, for example because Company KEK Identifier was cleared. | Keep Company KEK Identifier set, and its key reachable, while company keys are wrapped. |