> ## 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.

# Manage Secrets

By the end of this guide, you will have a Maverics Orchestrator that retrieves all sensitive configuration values -- API keys, client secrets, certificates -- from your organization's secret management system rather than from files or environment variables.

<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>

## Why External Secret Providers?

Secrets are sensitive values that your Orchestrator needs to function -- things like identity provider client secrets, API keys for upstream services, TLS private keys, and database passwords. Storing these directly in configuration files or environment variables creates risk: anyone with access to the file system or process environment can read them, and they are easy to accidentally commit to version control.

External secret providers solve this problem by storing secrets in a dedicated, access-controlled system. The Orchestrator fetches secrets at runtime using authenticated API calls, which means the actual secret values never appear in your config files. Providers like HashiCorp Vault, AWS Secrets Manager, and Azure Key Vault also offer features like automatic rotation, audit logging, and fine-grained access policies -- giving you centralized control over who and what can access each secret.

## Prerequisites

* **A running Maverics Orchestrator** -- If you have not installed it yet, follow the [Quick Start guide](/guides/getting-started/quick-start) first.
* **Access to a secret provider** -- You need an account and appropriate permissions on one of the supported providers: [HashiCorp Vault](/reference/orchestrator/configuration/secret-providers/hashicorp-vault), [AWS Secrets Manager](/reference/orchestrator/configuration/secret-providers/aws-secrets-manager), [Azure Key Vault](/reference/orchestrator/configuration/secret-providers/azure-key-vault), [Delinea Secret Server](/reference/orchestrator/configuration/secret-providers/delinea), [CyberArk Conjur](/reference/orchestrator/configuration/secret-providers/conjur), [CyberArk CCP](/reference/orchestrator/configuration/secret-providers/cyberark-ccp), or a [Secret File](/reference/orchestrator/configuration/secret-providers/environment) for development.

## Integrate a Secret Provider

<Steps>
  <Step title="Choose your secret provider">
    The Maverics Orchestrator supports 7 secret provider types, each suited to different environments and organizational requirements.

    <Tabs>
      <Tab title="Console UI">
        <Info>
          **Console UI documentation is coming soon.** This section will walk you
          through configuring this component using the Maverics Console's visual
          interface, including step-by-step screenshots and field descriptions.
        </Info>

        <Frame caption="Secret provider selection in Maverics Console">
          <img src="https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max&auto=format&n=yo114yy_clZj7p9v&q=85&s=ea8d2ec72a69d5a8c7955d78abba6a30" alt="Secret provider selection screen in Maverics Console showing supported providers" width="800" height="400" data-path="images/placeholder.svg" />
        </Frame>
      </Tab>

      <Tab title="Configuration">
        <Note>
          Secret providers are not configured in YAML. They are configured via the `MAVERICS_SECRET_PROVIDER` environment variable or the `-secretProvider` CLI flag. The table below lists all supported providers.
        </Note>

        | Provider                                                                                          | URL Scheme                          | Best For                                                            |
        | ------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------- |
        | [HashiCorp Vault](/reference/orchestrator/configuration/secret-providers/hashicorp-vault)         | `hashivault://` or `hashivaults://` | Multi-cloud, on-premises -- dynamic secrets, automatic rotation     |
        | [AWS Secrets Manager](/reference/orchestrator/configuration/secret-providers/aws-secrets-manager) | `awssecretsmanager://`              | AWS-native deployments -- IAM integration, cross-region replication |
        | [Azure Key Vault](/reference/orchestrator/configuration/secret-providers/azure-key-vault)         | `azurekeyvault://`                  | Azure-native deployments -- managed identity, HSM backing           |
        | [Delinea Secret Server](/reference/orchestrator/configuration/secret-providers/delinea)           | `delinea://`                        | Enterprise PAM -- session recording, approval workflows             |
        | [CyberArk Conjur](/reference/orchestrator/configuration/secret-providers/conjur)                  | `conjur://`                         | DevOps-oriented secrets for CI/CD and containers                    |
        | [CyberArk CCP](/reference/orchestrator/configuration/secret-providers/cyberark-ccp)               | `cyberarkccp://`                    | CyberArk Central Credential Provider                                |
        | [Secret File](/reference/orchestrator/configuration/secret-providers/environment)                 | `secretfile://`                     | Development and testing -- local file-based secrets                 |

        For most production deployments, choose the provider that matches your cloud platform or existing secret management infrastructure.

        See [Secret Providers Reference](/reference/orchestrator/configuration/secret-providers) for detailed configuration documentation for each provider.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the secret provider">
    Secret providers are configured via the `MAVERICS_SECRET_PROVIDER` environment variable or the `-secretProvider` CLI flag -- not in YAML configuration. Only one secret provider may be active at a time.

    The Orchestrator authenticates to the secret provider at startup and maintains the connection for the lifetime of the process. If the connection drops, the Orchestrator retries automatically.

    <Tabs>
      <Tab title="Console UI">
        <Info>
          **Console UI documentation is coming soon.** This section will walk you
          through configuring this component using the Maverics Console's visual
          interface, including step-by-step screenshots and field descriptions.
        </Info>

        <Frame caption="Secret provider connection configuration in Maverics Console">
          <img src="https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max&auto=format&n=yo114yy_clZj7p9v&q=85&s=ea8d2ec72a69d5a8c7955d78abba6a30" alt="Secret provider connection configuration screen showing authentication fields" width="800" height="400" data-path="images/placeholder.svg" />
        </Frame>
      </Tab>

      <Tab title="Configuration">
        <Note>
          Secret providers are configured via environment variable or CLI flag, not in YAML. The examples below show shell commands for the three most common providers.
        </Note>

        **HashiCorp Vault:**

        ```bash theme={null}
        export MAVERICS_SECRET_PROVIDER="hashivault://vault.example.com:8200/secret/data/maverics?token=<VAULT_TOKEN>"
        ```

        **AWS Secrets Manager:**

        ```bash theme={null}
        export MAVERICS_SECRET_PROVIDER="awssecretsmanager://us-east-1"
        ```

        **Azure Key Vault:**

        ```bash theme={null}
        export MAVERICS_SECRET_PROVIDER="azurekeyvault://my-vault.vault.azure.net"
        ```

        You can also pass the provider via the CLI flag instead of an environment variable:

        ```bash theme={null}
        maverics \
          -config /etc/maverics/maverics.yaml \
          -secretProvider "hashivault://vault.example.com:8200/secret/data/maverics?token=<VAULT_TOKEN>"
        ```

        See [Secret Providers Reference](/reference/orchestrator/configuration/secret-providers) for provider-specific URL parameters and authentication options.
      </Tab>
    </Tabs>

    <Warning>
      The credentials used to connect to the secret provider itself (like a
      Vault token or Azure service principal) should have the minimum
      permissions needed -- typically read-only access to the specific secrets
      the Orchestrator uses. Follow the principle of least privilege.
    </Warning>
  </Step>

  <Step title="Reference secrets in your Orchestrator configuration">
    Once the secret provider is configured, replace hardcoded secret values in your Orchestrator configuration with secret references. A secret reference uses angle bracket syntax: `<namespace.key>`. The Orchestrator resolves these references at startup by fetching the value from the configured provider.

    <Tabs>
      <Tab title="Console UI">
        <Info>
          **Console UI documentation is coming soon.** This section will walk you
          through configuring this component using the Maverics Console's visual
          interface, including step-by-step screenshots and field descriptions.
        </Info>

        <Frame caption="Secret reference configuration in Maverics Console">
          <img src="https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max&auto=format&n=yo114yy_clZj7p9v&q=85&s=ea8d2ec72a69d5a8c7955d78abba6a30" alt="Secret reference configuration screen showing how to reference secrets in connector settings" width="800" height="400" data-path="images/placeholder.svg" />
        </Frame>
      </Tab>

      <Tab title="Configuration">
        Use `<namespace.key>` syntax to reference secrets anywhere a sensitive value is needed:

        ```yaml maverics.yaml theme={null}
        connectors:
          - name: my-idp
            type: oidc
            oauthClientID: "my-client-id"
            oauthClientSecret: <maverics.oidc-client-secret>
            oidcWellKnownURL: "https://idp.example.com/.well-known/openid-configuration"

        caches:
          - name: "shared-redis"
            type: "redis"
            redis:
              addresses:
                - "redis.example.com:6379"
              password: <maverics.redis-password>

        tls:
          "default":
            certFile: "/etc/maverics/certs/server.pem"
            keyFile: "/etc/maverics/certs/server-key.pem"
        ```

        In this example:

        * `<maverics.oidc-client-secret>` -- The `maverics` namespace and `oidc-client-secret` key map to the secret path in your provider
        * `<maverics.redis-password>` -- Same namespace, different key for the Redis password

        The Orchestrator resolves all `<namespace.key>` references during startup. The rest of the system works exactly the same -- the only difference is where the value comes from.
      </Tab>
    </Tabs>

    <Tip>
      Secret references work in any string field in the YAML configuration. Use them for client secrets, passwords, API keys, encryption keys, and any other sensitive value.
    </Tip>
  </Step>

  <Step title="Verify secrets are resolving">
    After configuring secret references, restart the Orchestrator and verify that it successfully retrieves all secrets from the provider. The Orchestrator resolves secret references during startup, so any issues will appear in the startup logs.

    Start (or restart) the Orchestrator:

    ```bash theme={null}
    maverics -config /etc/maverics/maverics.yaml
    ```

    Check the logs for successful secret resolution. The Orchestrator logs when it connects to the secret provider and when it resolves each secret reference. Look for confirmation that all secrets were retrieved without errors.

    Verify the health endpoint to confirm the Orchestrator started successfully with resolved secrets:

    ```bash theme={null}
    curl -s https://localhost:9443/status | jq .
    ```

    If the health endpoint returns `{"status": "up"}`, your secrets are resolving correctly -- the Orchestrator was able to use the retrieved credentials to connect to your identity providers and other services.

    <Check>
      **Success!** Your Orchestrator is retrieving secrets from your external
      provider at runtime. No sensitive values are stored in configuration files,
      and your secrets benefit from the provider's rotation, access control, and
      audit logging features.
    </Check>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Secret not found">
    The Orchestrator logs an error if it cannot find a secret at the referenced
    path in the provider. Verify that the secret path in your configuration
    exactly matches the path in your provider -- paths are case-sensitive and
    must include the full hierarchy (for Vault, this includes the mount path
    and secret path). Also check that the secret has been created in the
    provider before the Orchestrator tries to read it.
  </Accordion>

  <Accordion title="Authentication to secret provider fails">
    If the Orchestrator cannot authenticate to your secret provider, check that
    the connection credentials are correct and have not expired. For Vault,
    verify the token has not been revoked. For AWS, verify the IAM role or
    access keys have the correct permissions. For Azure, verify the service
    principal credentials and that the Key Vault access policy grants the
    necessary permissions. The Orchestrator logs the specific authentication
    error during startup.
  </Accordion>

  <Accordion title="Secret rotation not picking up new values">
    By default, the Orchestrator resolves secrets at startup. If your provider
    rotates a secret while the Orchestrator is running, the Orchestrator
    continues using the previously fetched value until it is restarted. For
    production deployments that require seamless rotation, check whether your
    secret provider supports a notification mechanism or configure the
    Orchestrator's secret refresh interval to periodically re-fetch values.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={2}>
  <Card title="Security Overview" icon="shield-halved" href="/guides/security/overview">
    Return to the Security guides hub for TLS, secrets, policies, and compliance
  </Card>

  <Card title="Secret Providers Reference" icon="key" href="/reference/orchestrator/configuration/secret-providers">
    Detailed configuration for each supported provider -- Vault, AWS, Azure, Delinea, CyberArk Conjur, CyberArk CCP, and Secret File
  </Card>

  <Card title="Configure TLS" icon="lock" href="/guides/security/tls">
    Store TLS certificates and private keys as secrets for secure certificate management
  </Card>

  <Card title="Operations Guides" icon="gears" href="/guides/operations/overview">
    Deploy and monitor the Orchestrator in production -- including secret management best practices
  </Card>
</CardGroup>