Secrets Manager
Protocol: JSON 1.1 (X-Amz-Target: secretsmanager.*)
Endpoint: POST http://localhost:4566/
Supported Actions
| Action | Description |
|---|---|
CreateSecret |
Create a new secret |
GetSecretValue |
Retrieve the current secret value |
PutSecretValue |
Update the secret value (new version) |
UpdateSecret |
Update secret metadata or value |
DescribeSecret |
Get secret metadata and version info |
ListSecrets |
List all secrets |
DeleteSecret |
Delete a secret (with recovery window) |
RestoreSecret |
Cancel a scheduled deletion and restore the secret |
RotateSecret |
Trigger secret rotation, via a Lambda or by the owning service |
CancelRotateSecret |
Turn off automatic rotation and report any half-staged AWSPENDING version |
TagResource |
Tag a secret |
UntagResource |
Remove tags |
ListSecretVersionIds |
List all versions of a secret |
GetResourcePolicy |
Get the resource policy |
GetRandomPassword |
Generate a random password |
BatchGetSecretValue |
Retrieve multiple secret values in one call |
DeleteResourcePolicy |
Remove the resource policy |
PutResourcePolicy |
Attach a resource policy |
UpdateSecretVersionStage |
Move a staging label between versions |
ValidateResourcePolicy |
Check a resource policy for overly broad principals |
ReplicateSecretToRegions |
Replicate a secret into other regions |
RemoveRegionsFromReplication |
Delete replicas from the given regions |
StopReplicationToReplica |
Promote a replica to a standalone primary |
IAM resource tags
With IAM enforcement enabled, secret-scoped operations read current stored tags
for aws:ResourceTag/<key> and secretsmanager:ResourceTag/<key> conditions.
Names and full ARNs resolve to the same stored secret before authorization.
Retagging or removing a tag affects the next request; request tags cannot replace
the stored tags during a write. Missing secrets contribute no stored tags.
Case-variant tag keys retain all their values in the case-insensitive IAM context,
so set operators such as ForAnyValue:StringEquals inspect every stored value.
Bare operators retain the shared evaluator's single-value semantics; use consistent
tag key casing or a set operator for case-variant keys.
The keys are the ones the Service Reference gives the Secret resource type, from
the generated resourceTagKeys table in iam-request-resources.json, regenerated by
tools/aws/regen_iam_request_resources.py.
Secret write events
Successful PutSecretValue and UpdateSecret API calls emit an EventBridge event with
source: aws.secretsmanager and detail-type: AWS API Call via CloudTrail. A metadata-only
UpdateSecret also emits an event. Delivery requires:
- A CloudTrail trail in the caller's account with logging started. A single-region trail must cover the request's region; a multi-region trail can cover other regions in its partition.
- Management writes selected by that trail. New trails select management events by default.
Basic selectors must include management events and allow
AllorWriteOnly. Advanced selectors must match the management event; data-only and read-only selectors do not qualify. - An enabled rule on the default event bus, in the secret's account and region, with an appropriate target. A custom bus receives these events only through an explicit forwarding rule.
Match a particular secret with this pattern, replacing the example ARN with the ARN returned
by CreateSecret:
{
"source": ["aws.secretsmanager"],
"detail-type": ["AWS API Call via CloudTrail"],
"detail": {
"eventName": ["PutSecretValue", "UpdateSecret"],
"responseElements": {
"arn": ["arn:aws:secretsmanager:us-east-1:000000000000:secret:example-AbCdEf"]
}
}
}
The lowercase responseElements.arn follows the current AWS CloudTrail format. Records include
the operation, account, region, caller identity, secret name, and version ID when returned.
Request metadata is restricted to the secret ID, client request token, version stages, and KMS
key ID. Secret strings, binary values, descriptions, and unrecognized request fields are omitted
from both EventBridge events and CloudTrail logs.
One event is published per successful API call even when several trails select it. Matching trails also buffer the same redacted record for their normal S3 log delivery. EventBridge target delivery is asynchronous and does not wait for the CloudTrail S3 flush interval.
Coverage is limited to these two successful API operations. Reads, failed writes, and internal
service writes do not emit these API-call events. Native Secret Label Updated events and
RotationSucceeded service events are separate contracts and are not generated by this hook.
Event publication is best effort: a delivery failure does not fail the completed secret write.
Publication runs on two background workers with a bounded queue of 256 pending events. Slow
targets do not hold the secret-write response open. Each queued delivery restores the originating
account and region. Notifications are dropped and logged when the queue is full or publication
is paused or stopped. Pending notifications are in memory and are not retained across shutdown.
An emulator reset discards queued notifications and pauses new notifications. Active deliveries finish before storage is cleared, then publication resumes, including after a failed reset. If active deliveries cannot drain within 30 seconds, or draining is interrupted, reset fails before the storage wipe.
See AWS's Secrets Manager event types and CloudTrail event prerequisites.
Configuration
| Variable | Default | Description |
|---|---|---|
FLOCI_SERVICES_SECRETSMANAGER_ENABLED |
true |
Enable or disable the service |
FLOCI_SERVICES_SECRETSMANAGER_DEFAULT_RECOVERY_WINDOW_DAYS |
30 |
Days before a deleted secret is permanently purged |
FLOCI_SERVICES_SECRETSMANAGER_SCHEDULED_ROTATION_ENABLED |
true |
Run the background sweep that fires rotations when a schedule comes due |
FLOCI_SERVICES_SECRETSMANAGER_ROTATION_TICK_SECONDS |
60 |
How often that sweep looks for due rotations |
Examples
export AWS_ENDPOINT_URL=http://localhost:4566
# Create a string secret
aws secretsmanager create-secret \
--name /app/database-url \
--secret-string "postgresql://admin:secret@localhost/mydb" \
--endpoint-url $AWS_ENDPOINT_URL
# Create a JSON secret
aws secretsmanager create-secret \
--name /app/api-keys \
--secret-string '{"stripe":"sk_test_xxx","sendgrid":"SG.xxx"}' \
--endpoint-url $AWS_ENDPOINT_URL
# Retrieve a secret
aws secretsmanager get-secret-value \
--secret-id /app/database-url \
--endpoint-url $AWS_ENDPOINT_URL
# Update a secret
aws secretsmanager put-secret-value \
--secret-id /app/database-url \
--secret-string "postgresql://admin:new-password@localhost/mydb" \
--endpoint-url $AWS_ENDPOINT_URL
# List secrets
aws secretsmanager list-secrets --endpoint-url $AWS_ENDPOINT_URL
# Delete (with recovery window)
aws secretsmanager delete-secret \
--secret-id /app/database-url \
--recovery-window-in-days 7 \
--endpoint-url $AWS_ENDPOINT_URL
# Delete immediately (no recovery)
aws secretsmanager delete-secret \
--secret-id /app/database-url \
--force-delete-without-recovery \
--endpoint-url $AWS_ENDPOINT_URL
# Generate a random password
aws secretsmanager get-random-password \
--password-length 24 \
--exclude-punctuation \
--endpoint-url $AWS_ENDPOINT_URL
# Batch-fetch multiple secrets in one call
aws secretsmanager batch-get-secret-value \
--secret-id-list /app/database-url /app/api-keys \
--endpoint-url $AWS_ENDPOINT_URL
# Move the AWSCURRENT label to a different version (e.g. during a rotation)
aws secretsmanager update-secret-version-stage \
--secret-id /app/database-url \
--version-stage AWSCURRENT \
--move-to-version-id <new-version-id> \
--remove-from-version-id <old-version-id> \
--endpoint-url $AWS_ENDPOINT_URL
# Turn on scheduled rotation, then turn it back off
aws secretsmanager rotate-secret \
--secret-id /app/database-url \
--rotation-lambda-arn arn:aws:lambda:us-east-1:000000000000:function:my-rotator \
--rotation-rules '{"ScheduleExpression":"rate(10 days)"}' \
--endpoint-url $AWS_ENDPOINT_URL
aws secretsmanager cancel-rotate-secret \
--secret-id /app/database-url \
--endpoint-url $AWS_ENDPOINT_URL
# Replicate to another region, then promote the replica to its own primary
aws secretsmanager replicate-secret-to-regions \
--secret-id /app/database-url \
--add-replica-regions Region=eu-west-1 \
--endpoint-url $AWS_ENDPOINT_URL
aws secretsmanager stop-replication-to-replica \
--secret-id /app/database-url \
--region eu-west-1 \
--endpoint-url $AWS_ENDPOINT_URL
# Check a resource policy before attaching it
aws secretsmanager validate-resource-policy \
--secret-id /app/database-url \
--resource-policy file://policy.json \
--endpoint-url $AWS_ENDPOINT_URL
Behaviour notes
- Rotation schedules fire. A background sweep (see the config table) rotates any secret whose
NextRotationDatehas passed.AutomaticallyAfterDays,rate()andcron()are all honoured. - Redshift-owned master secrets rotate with their cluster.
RotateSecretand scheduled rotation change the provisioned Redshift cluster password, then publish the matching secret version. The cluster must be available, and a rotation Lambda is not used. RotateSecretalso needslambda:InvokeFunctionunder IAM enforcement. As on AWS, the caller must be allowed to invoke the rotation function as well as to callRotateSecret. A caller that is not getsAccessDeniedExceptionwith HTTP 400, as Secrets Manager reports it, and the secret is left as it was. A function in another account is checked as any cross-account call is: its function policy must allow the caller too. Rotations started by the background sweep have no caller and are not checked.- A rotation function that does not exist is reported as AWS reports it:
AccessDeniedException(HTTP 400), "Secrets Manager cannot invoke the specified Lambda function". The function is looked up where the rotation runs it, in the account its ARN names and as the version or alias the ARN names, so a missing alias is reported the same way. The secret's rotation settings are left as they were, including any rotation function configured before. - A rotation function reference Lambda refuses, one it cannot parse or a full ARN in another
Region, gets
InvalidParameterException(HTTP 400), the errorRotateSecretdeclares for an invalid parameter, with Lambda's reason in the message. The secret is left as it was. AWS does not document which error a function in another Region gets. - Replication is synchronous. Real AWS reports
InProgressfirst; floci copies the secret immediately, so a replica isInSyncby the time the call returns. Replicas are read-only and track later writes to the primary. - Secret values are stored in the clear.
KmsKeyIdis validated — a missing key is rejected, and a disabled or pending-deletion key raisesEncryptionFailure— but values are not actually encrypted, since encrypting with the emulator's own KMS would protect nothing. ValidateResourcePolicyandBlockPublicPolicycheck for wildcard principals only. AWS runs the policy through Zelkova; a pass here is weaker than a pass on AWS.PutResourcePolicywithBlockPublicPolicyraisesPublicPolicyExceptionfor a wildcard principal, and — as on AWS — leaves such a policy alone when the flag is absent.PrimaryRegionandReplicationStatusappear only on multi-region secrets, matching AWS's "only returns fields that have a value" rule — a standalone secret carries neither.- Rotation schedule limits are enforced:
AutomaticallyAfterDays1–1000,DurationasNh, andrate()in hours or days no faster than every four hours. - Known deviation:
RotateSecretwithRotateImmediately: falseinvokes the rotation function'stestSecretstep but does not first create the throwawayAWSPENDINGversion that AWS creates and removes, so a rotation function whosetestSecretreads that version by id will not find it.