Store Outpost Credentials in a Customer-Managed Secret

An Outpost connection can use the In Host BYOK runtime mode. In this mode, the credentials for the connection stay in a secret in the customer environment. Relyance stores only the location of the secret, not the credentials. The scanner reads the secret during the scan with its own identity.

#Secret providers

AWS Secrets Manager is available only for an Outpost deployment on AWS. Relyance rejects a secret ARN for an Outpost deployment on GCP.

#What the secret contains

The secret value is a JSON object. Each key is a credential field of the authentication method. The Authentication step of the connection has a builder that makes this JSON.

Some connection settings are not credentials, for example the data storage location. These settings stay on the Relyance form, and Relyance stores them. All other credential fields go in the secret. This includes the credential fields that are not secret.

For AWS Secrets Manager, a field that is not secret can be left out of the secret when it has a default value on the Relyance form. This also applies to checkbox and dropdown fields. The scanner then uses the default value from the form.

Relyance rejects secret values that are sent for an In Host BYOK connection. When a connection changes to In Host BYOK, Relyance deletes the copy of the credentials that it kept for the connection.

#Set up a connection with AWS Secrets Manager

The Outpost deployment must be on AWS and use the Relyance Terraform module.

1. Open the connection.
2. In Connection Settings, set Runtime Mode to In Host BYOK.
3. Save the connection settings.
4. Go to the Authentication step.
5. Select the authentication method.
6. In Credentials Secret, set Secret provider to AWS Secrets Manager.
7. Enter the credential values in the builder fields. The JSON shows in Secret value (JSON).
8. Click Copy.
9. In AWS Secrets Manager, create a secret. Use the copied JSON as the secret value.
10. Give the scanner role access to the secret. Refer to Give the scanner access.
11. Copy the full secret ARN from the secret details page in AWS Secrets Manager.
12. Enter the ARN in Secret ARN.
13. Save the connection.

Use one secret for each connection. A common name prefix, for example relyance/inhost/, lets one access pattern cover all connections. This example creates the secret from a file that contains the copied JSON:

aws secretsmanager create-secret \
  --name relyance/inhost/example-vendor/example-connection \
  --secret-string file://secret.json

Delete the local file after AWS creates the secret. To encrypt the secret with a customer-managed KMS key, add --kms-key-id with the key ARN.

#Give the scanner access

The scanner reads the secret with the scanner IAM role of the Outpost deployment. The default name of this role is Relyance_Sierra. Set these variables in the Relyance Terraform module, then apply the module:

module "outpost" {
  # ...
  byok_secret_arn_patterns = [
    "arn:aws:secretsmanager:us-west-2:123456789012:secret:relyance/inhost/*",
  ]

  # Only for secrets that a customer-managed KMS key encrypts.
  byok_secret_kms_key_arns = [
    "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
  ]

  # The default is true.
  byok_secret_write_back = true
}

• A secret ARN ends with a random suffix of six characters. End each pattern with *.
• The AWS managed key aws/secretsmanager needs no entry in byok_secret_kms_key_arns.
• A key policy that does not delegate to IAM policies must also allow the scanner role.
• A secret resource policy must not deny access to the scanner role.

#How the scanner uses the secret

Read. The scanner reads the secret when a scan starts. Relyance does not test access to the secret when the connection is saved. The next scan shows access problems.

Rotation. The scanner keeps the secret value in memory for up to 5 minutes. After a change to the secret, scans use the new value within 5 minutes. A pod restart is not necessary.

Region. The scanner calls AWS Secrets Manager in the region of the secret ARN.

Default values. Some fields that are not secret have a default value on the Relyance form. Checkbox and dropdown fields can also have a default value. If the secret does not contain such a field, the scanner uses the default value. This applies only to AWS Secrets Manager.

Required fields. Each required credential field must be in the secret with a value. If a required field is missing or empty, the scan fails.

Token write-back. The scanner writes to the secret only when it refreshes an OAuth token and the token changes. It writes only the keys that changed, and merges them into the current secret value. The other keys do not change. The scanner does not write to the secret at other times, for example when it only reads the secret.

If a write-back fails, the scan does not fail. The scanner continues the scan with the new token in memory. The scan shows a warning that starts with "Token refresh could not be saved to the credential secret". The warning gives a reason code and does not contain the secret ARN. The scanner logs also record the failure. For a vendor that rotates refresh tokens, correct the cause before the next scan. The secret still contains the old refresh token.

Automatic rotation. Do not turn on automatic rotation in AWS Secrets Manager for a secret of an OAuth connection with a refresh token. A rotation function can write over a token that the scanner saved. The next scan then uses a token that is not valid, and authentication fails.

Write-back setting. The Terraform module and the deployment each have a write-back setting. Set the deployment setting to the same value as the Terraform variable. A Helm deployment uses byokSecretWriteBack. A kustomize deployment uses SECRET_REF_WRITE_BACK.

When the value is false, the scanner does not write to the secret. Vendors with static credentials are not affected. A vendor that rotates refresh tokens fails after the first token refresh, because the secret keeps the old refresh token.

Runtime mode change. When the runtime mode changes from In Host BYOK to a different mode, Relyance removes the stored secret ARN and disconnects the connection. The connection does not scan until its credentials are saved and it is connected again.

#Authentication methods that cannot use AWS Secrets Manager

#Use a Kubernetes secret

1. In Credentials Secret, set Secret provider to Kubernetes secret (environment variable mount).
2. Enter the credential values in the builder fields.
3. Click Copy.
4. Create a Kubernetes secret with the copied JSON as the value.
5. Give the secret to the scanner pods as the environment variable RELYANCE_INTEGRATION_<vendor-key>_<connection-id>.
6. Save the connection.

A Kubernetes secret is different from AWS Secrets Manager in these ways:

• The scanner does not fill default values for missing fields. It checks only the required secret fields.
• The scanner does not write refreshed tokens back to the secret.
• A connection that was connected with a Kubernetes secret before continues to use it. To change to AWS Secrets Manager, set Secret provider and enter the secret ARN.

#Limits

• Provider. Relyance accepts only AWS Secrets Manager ARNs, in the format arn:aws:secretsmanager:<region>:<account-id>:secret:<name>.
• Cloud. Secret ARNs are available only for an Outpost deployment on AWS.
• Account. The secret must be in the AWS account of the Outpost deployment. Relyance must know that account. If Relyance does not know the account, it rejects the secret ARN.
• Value. The secret value must be a JSON object in the secret text. A binary secret value does not work.

#Troubleshooting

When the scanner cannot read the secret, the scan fails with an authentication error. The message starts with "Authentication failed. The scanner cannot read the credential secret:". The rest of the message gives the reason. The message never contains the secret value or the secret ARN.

Relyance can also reject the connection when it is saved:

#Related

• How Outpost Works