Add certificates from AWS Secrets Manager

F5 NGINXaaS for AWS can fetch secrets directly from AWS Secrets Manager to use as certificates and keys in your NGINX configuration, ensuring your credentials remain securely within AWS.

Prerequisites

If you haven’t already done so, create an NGINXaaS deployment with an IAM role. See Identity and access management for more information.

IAM role permissions policy

To allow NGINXaaS for AWS access to your AWS Secrets Manager secrets, you must attach a permissions policy to your IAM role. The policy must allow the secretsmanager:GetSecretValue action. For example, the following policy allows access to the specified secret.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": "secretsmanager:GetSecretValue",
			"Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf"
		}
	]
}

See AWS Secrets Manager identity-based policies for more examples.

NGINXaaS for AWS also supports attribute-based access control (ABAC) by restricting access based on tag attributes. For example, the following policy allows only the specified NGINXaaS deployment to access the secret.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": "secretsmanager:GetSecretValue",
			"Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf",
			"Condition": {
				"StringEquals": {
					"aws:PrincipalTag/NGINXaaS:DeploymentName": "test-deployment"
				}
			}
		}
	]
}

The session tags passed in the request to fetch the secret will appear in AssumeRole events in CloudTrail. The following tags are supported:

• NGINXaaS:OrganizationID
• NGINXaaS:DeploymentID
• NGINXaaS:DeploymentName

Add an SSL/TLS certificate to AWS Secrets Manager

To add an SSL/TLS certificate and key as a secret to AWS Secrets Manager,

1. Make sure your certificate and key file(s) are in one of the accepted formats.
2. Follow AWS’s instructions to create a secret in AWS Secrets Manager and set your certificate and private key file contents as the plaintext secret value.

There are many ways to manage your SSL/TLS certificates and keys. For example, you can include the PEM certificate data in the same secret as your private key. The ssl_certificate directive supports a single file containing multiple certificates and a key. See NGINX’s Configuring HTTPS servers guide for more details.

Use an AWS Secrets Manager certificate in an NGINX configuration

To add your AWS Secrets Manager certificate and key to an NGINX configuration in the NGINXaaS console,

1. Select Configurations in the left menu.
2. Select the ellipsis (three dots) next to the configuration you want to edit, and select Edit.
3. Select Add File.
4. Select Cloud Provider Secret as the type of file you want to add.
5. Select AWS Secrets Manager as the Cloud Secret Manager.
6. Provide the required information:

   Field	Description	Note
   Secret ARN	The Amazon Resource Name (ARN) of the secret in AWS Secrets Manager	The ARN must match the format arn:<PARTITION>:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:<SECRET_NAME>-<6_RANDOM_CHARACTERS>.
   Version Stage	The staging label of the secret version.	Version stage is optional and cannot be specified at the same time as Version ID. If you don’t specify a version stage or a version ID, NGINXaaS for AWS fetches the version labeled AWSCURRENT. See AWS’s documentation on secret versions for more information.
   Version ID	The unique identifier of the secret version.	Version ID is optional and cannot be specified at the same time as version stage. If you don’t specify a version stage or a version ID, NGINXaaS for AWS fetches the version labeled AWSCURRENT.
   File Path	NGINXaaS writes the secret to this file path, so it can be used with NGINX directives such as ssl_certificate or ssl_certificate_key in your NGINX configuration.	The path must be unique within the configuration. See the NGINX Filesystem Restrictions table for the allowed directories the file can be written to.

If you set the Version Stage to AWSCURRENT or leave Version Stage and Version ID unspecified, NGINXaaS for AWS automatically picks up any new secret version AWS Secrets Manager promotes to AWSCURRENT without a configuration change. NGINXaaS for AWS applies new versions within four hours. See Rotate an AWS Secrets Manager certificate (automatic) for details.

7. Update the NGINX configuration to reference the certificate you just added by the path value.
8. Select Add, Next, and then Save to save your changes.

Update your NGINXaaS deployment’s NGINX configuration

Before updating your NGINXaaS deployment to use your new NGINX configuration, make sure your deployment already has an IAM role set up with the secretsmanager:GetSecretValue permission granted, so it can fetch certificates. Then, in the NGINXaaS console:

1. Select Deployments.
2. Select the deployment you want to edit.
3. In the Configuration Info panel, select Edit.
4. Select the configuration and configuration version created in the last section.
5. Select Update Configuration.

Configurations with AWS Secrets Manager secrets can only be added to AWS deployments.

Rotate an AWS Secrets Manager certificate (automatic)

If you set the Version Stage to AWSCURRENT or leave Version Stage and Version ID unspecified, NGINXaaS for AWS fetches the latest secret version. When you update the value of a secret or configure an AWS Lambda function to rotate the secret, AWS Secrets Manager moves the AWSCURRENT label to the new secret version. NGINXaaS for AWS automatically picks up that new version within four hours.

If you set the Version Stage to a staging label other than AWSCURRENT, NGINXaaS for AWS fetches the secret version the staging label points to. When you move a staging label to point to a different secret in AWS Secrets Manager, NGINXaaS for AWS automatically picks up that secret within four hours.

No configuration changes are required in either case. To confirm your deployment is using an updated certificate, check the Certificates list for the new serial number or inspect the certificate at your deployment’s endpoint.

Rotate an AWS Secrets Manager certificate (manual)

To immediately refetch secrets without editing your NGINX configuration, use Reapply Configuration. This is useful in the following scenarios:

• New secret version: You’ve uploaded a new certificate and want NGINXaaS for AWS to use it right away.
• Updated IAM role or permissions: You’ve updated your IAM role trust policy or permissions policy and want NGINXaaS for AWS to retry immediately.

To reapply your configuration:

1. In the NGINXaaS console, go to your deployment.
2. Select Reapply Configuration in the Configuration Info panel.

NGINXaaS for AWS reapplies your current configuration version and immediately refetches all referenced secrets.

Monitor secret fetch events

NGINXaaS for AWS generates an event each time it fetches or fails to fetch a secret from AWS Secrets Manager. Use these events to track successful rotations and diagnose access failures.

Event types

View events in the console

• Select Overview in the left menu, then select Events. To narrow results to a specific deployment, filter by its object ID using the controls at the top of the page.
• For a summary of recent events for a specific deployment, select Deployments, select the deployment, and look for the Recent Events card. Select See Events Details to go to the full Events page pre-filtered for that deployment.

Common failure messages and remediation

What’s next

Upload an NGINX Configuration