# Secret Entitlement with Policies

Once [secret stores](/admin/access/secret-stores.md) and [secret engines](/admin/secrets.md) are fully configured via the Admin UI or CLI, you may [create policies](/admin/access/policies/policy-creation.md) to entitle managed secrets to users and/or groups of users, as well as enforce fine-grained policy-based access control (PBAC) for the users who are entitled to access those managed secrets. Entitlement means using policies to allow specific users or groups of users to access and perform specific actions on managed secrets. Your policy statements can specify the users permitted to access specific secrets and what actions users are permitted to perform, such as reading, retrieving, rotating, or validating managed secrets. These policies can also include annotations (to require users to justify their actions, or receive an MFA challenge) and context-based conditions (such as access based on the user's location) for enhanced control and flexibility.

After such policies are saved, entitlements for managed secrets are shown in the Admin UI in **Settings** > **Secrets Management** > **Secrets** > **Entitlements**.

The sections that follow describe how to structure policy statements to allow users and/or groups to access and perform actions on managed secrets. For all other information about policies, please see [Policies](/admin/access/policies.md).

### Actions for Secrets Management

In a policy statement, StrongDM Secrets Management actions are set in the format `StrongDM::ManagedSecret::Action::"<ACTION>"`, where `<ACTION>` is the name of the action (for example, `StrongDM::ManagedSecret::Action::"rotate"`).

The possible actions for managed secrets are:

* `read`
* `retrieve`
* `rotate`
* `validate`

The `resource` in the policy statement also must be set as `resource is StrongDM::ManagedSecret`.

In the Policy Editor, if you are typing into the editing area directly, enter the action(s) (and resource) in the following way.

```cedar
permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"retrieve"],
    resource is StrongDM::ManagedSecret
);
```

If multiple actions on managed secrets are allowed, enter each action in the following way.

```cedar
permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
);
```

Actions for managed secrets may be set in policy statements in combination with [context](/admin/access/policies/policy-creation.md#context) and [annotations](/admin/access/policies/policy-creation.md#annotations). Examples are shown in the next section.

{% hint style="info" %}
Device Trust context is not supported by Secrets Management.
{% endhint %}

### Example Policy Statements for Entitlement and PBAC

This section provides some examples of policy statements that entitle managed secrets to users and groups, as well as enforce policy actions on managed secrets operations.

Allow users to conduct particular Secrets Management actions when the user's employeeNumber matches the managed secret's employeeNumber tag value:

```cedar
permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"validate", StrongDM::ManagedSecret::Action::"rotate"],
    resource is StrongDM::ManagedSecret
) when {
    principal.employeeNumber != "" &&
        resource.hasTag("employeeNumber") && resource.getTag("employeeNumber") == principal.employeeNumber
    };
```

Allow retrieval of managed secrets where the user's employeeNumber matches the value of the managed secret's employeeNumber tag:

```cedar
permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"retrieve"],
    resource is StrongDM::ManagedSecret
) when {
    principal.employeeNumber != "" &&
        resource.hasTag("employeeNumber") && resource.getTag("employeeNumber") == principal.employeeNumber
    };
```

Allow users with the "secrets-admin" role to perform public read/rotate/validate actions on managed secrets (note that the role value is the role ID rather than the role name in the example shown):

```cedar
permit (
    principal in StrongDM::Role::"r-5e367aa86759a7b8",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
);
```

Allow users with the "production-access" role to perform retrieve/public read/rotate/validate actions on managed secrets tagged with env=production:

```cedar
@justify("Please provide a reason to do this.")
permit (
    principal in StrongDM::Role::"r-3618ea926759a881",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.hasTag("env") && resource.getTag("env") == "production"
    };
```

Allow users with the "development-access" role to perform retrieve/public read/rotate/validate actions on managed secrets tagged with env=development:

```cedar
@justify("Please provide a reason to do this.")
permit (
    principal in StrongDM::Role::"r-496d29476759a8c6",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.hasTag("env") && resource.getTag("env") == "development"
    };
```

Allow users with the "staging-access" role to perform retrieve/public read/rotate/validate actions on managed secrets tagged with env=development:

```cedar
permit (
    principal in StrongDM::Role::"r-2725a45a6759a8ed",
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.hasTag("env") && resource.getTag("env") == "staging"
    };
```

Allow retrieve/public read/rotate/validate actions on managed secrets tagged with "owner" equal to the principal's email:

```cedar
permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    resource.hasTag("env") && resource.getTag("owner") == principal.email
};
```

Allow admins to access managed secrets:

```cedar
permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"rotate", StrongDM::ManagedSecret::Action::"validate"],
    resource is StrongDM::ManagedSecret
) when {
    principal.permissionLevel == "admin"
    };
```

Allow all Secrets Management actions on secrets tagged with foo=bar:

```cedar
permit (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"validate", StrongDM::Action::"rotate", StrongDM::ManagedSecret::Action::"retrieve"],
    resource is StrongDM::ManagedSecret
) when {
    resource.hasTag("foo") && resource.getTag("foo") == "bar"
};
```

Forbid access to managed secrets if there is an error:

```cedar
@error("this is a test")
forbid (
    principal,
    action in [StrongDM::ManagedSecret::Action::"read", StrongDM::ManagedSecret::Action::"retrieve"],
    resource
) when {
    context.network.clientIp.isInRange(ip("99.174.173.5/32"))
};
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.strongdm.com/admin/secrets/policy-secrets-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.