> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Secrets Manager

The AWS Secrets Manager secret provider connects the Orchestrator to AWS Secrets Manager for cloud-native secrets management. This provider integrates natively with AWS IAM, making it ideal for Orchestrator deployments running on AWS infrastructure.

<Note>
  **Console terminology:** In the Maverics Console, Orchestrator instances and
  configuration delivery are managed through **Deployments**. When working directly
  with YAML, configuration is managed as files delivered via the `-config` flag or
  `MAVERICS_CONFIG` environment variable.
</Note>

## Overview

When configured with the AWS Secrets Manager provider, the Orchestrator authenticates to AWS using the SDK default configuration and retrieves secrets on demand as they are referenced in the Orchestrator configuration. The provider supports AWS SDK credential resolution (IAM roles, environment variables, shared credentials) as well as explicit access key credentials provided in the URL. Secrets can be referenced by name or by ARN, and JSON secrets support individual key extraction.

## Use Cases

* **AWS-native deployments** -- retrieve Orchestrator secrets from AWS Secrets Manager when running on AWS infrastructure, using IAM for authentication
* **Existing AWS Secrets Manager deployments** -- use an existing Secrets Manager setup without duplicating credentials into another system
* **Centralized credential rotation** -- rotate secrets in AWS and pick up new values on Orchestrator restart or config reload

## Configuration

Secret providers are not configured in YAML. They are set via the `MAVERICS_SECRET_PROVIDER` environment variable or the `-secretProvider` CLI flag.

### Configuration via Environment Variable

```bash theme={null}
# Using default AWS SDK credentials (IAM role, env vars, etc.)
export MAVERICS_SECRET_PROVIDER="awssecretsmanager://amazonaws.com?region=us-west-2"

# Using explicit access key credentials
export MAVERICS_SECRET_PROVIDER="awssecretsmanager://amazonaws.com?region=us-west-2&accessKeyID=<key-id>&secretAccessKey=<secret-key>"
```

### Configuration via CLI Flag

```bash theme={null}
maverics -config maverics.yaml -secretProvider "awssecretsmanager://amazonaws.com?region=us-west-2"
```

### Referencing Secrets in YAML

Once the secret provider is configured, reference secrets in your Orchestrator YAML configuration using angle bracket syntax. The secret name in the angle brackets maps directly to the secret name in AWS Secrets Manager:

```yaml theme={null}
connectors:
  - name: my-idp
    # Retrieve the entire secret value (plaintext or full JSON string)
    oauthClientSecret: <my-app-secrets>

    # Retrieve a specific key from a JSON secret
    oauthClientID: <my-app-secrets:clientID>
```

For JSON secrets stored in AWS Secrets Manager, use the `secretName:jsonKey` format to retrieve a specific key from the JSON object. You can also reference secrets by ARN:

```yaml theme={null}
connectors:
  - name: my-idp
    oauthClientSecret: <arn:aws:secretsmanager:us-east-2:123456789:secret:my-secret-AbCdEf:clientSecret>
```

## Configuration Reference

### URL Structure

```
awssecretsmanager://{host}?{parameters}
```

### URL Parameters

| Parameter         | Required | Description                                                                             |
| ----------------- | -------- | --------------------------------------------------------------------------------------- |
| `region`          | No       | AWS region for Secrets Manager (e.g., `us-west-2`). Overrides region from SDK defaults. |
| `accessKeyID`     | No       | AWS access key ID. Must be used with `secretAccessKey`.                                 |
| `secretAccessKey` | No       | AWS secret access key. Must be used with `accessKeyID`.                                 |

<Note>
  The URL host (e.g., `amazonaws.com`) is required by URL syntax but is not used
  by the provider. The provider connects to AWS Secrets Manager using the AWS SDK
  configuration.
</Note>

### Authentication

The provider loads the default AWS SDK configuration, then optionally overrides the region and credentials with values from the URL query parameters. When `accessKeyID` and `secretAccessKey` are not specified, the SDK resolves credentials from the standard chain (environment variables, shared credentials file, IAM roles, etc.).

<Tip>
  For production deployments, use IAM roles instead of static access keys. IAM
  roles automatically rotate credentials and do not require secrets to be stored
  on the host.
</Tip>

## Troubleshooting

**"AccessDeniedException" when starting the Orchestrator**
Verify that the IAM role or access keys have the `secretsmanager:GetSecretValue` permission for the configured secret ARN. Check the IAM policy attached to the role or user.

**"ResourceNotFoundException" for the secret name**
Confirm the secret name and region are correct. The secret must exist in the specified AWS region. Secret names are case-sensitive.

**Secrets not resolving in YAML configuration**
Ensure the angle bracket reference matches the secret name in AWS Secrets Manager. For JSON secrets, use the `<secretName:jsonKey>` format to retrieve a specific key. Secret names are case-sensitive.

## Related Pages

<CardGroup cols={2}>
  <Card title="Secret Providers" icon="vault" href="/reference/orchestrator/configuration/secret-providers">
    Overview of all secret providers
  </Card>

  <Card title="Azure Key Vault" icon="cloud" href="/reference/orchestrator/configuration/secret-providers/azure-key-vault">
    Cloud-native secrets for Azure deployments
  </Card>
</CardGroup>