# Amazon Verified Permissions policy templates and template-linked policies
Policy templates and template-linked policies

In Verified Permissions, policy templates are policies with placeholders for the `principal`, `resource`, or both. Policy templates alone can't be used to handle authorization requests. To handle authorization requests, a *template-linked policy* must be created based on a policy template. Policy templates allow a policy to be defined once and then used with multiple principals and resources. Updates to the policy template are reflected across all policies that use the template. For more information, see [Cedar policy templates](https://docs.cedarpolicy.com/policies/templates.html) in the Cedar policy language Reference Guide.

You can optionally assign a policy template name to a policy template. Policy template names must be unique within the policy store and prefixed with `name/`. You can use a policy template name in place of the policy template ID in control plane operations that accept a `policyTemplateId` parameter. Only `GetPolicyTemplate` and `ListPolicyTemplates` return the name in the output. The following example uses a policy template name to retrieve a policy template with `GetPolicyTemplate`.

```
$ aws verifiedpermissions get-policy-template \
    --policy-template-id name/example-policy-template \
    --policy-store-id PSEXAMPLEabcdefg111111
```

For example, the following policy template provides `Read`, `Edit`, and `Comment` permissions for the principal and resource that use the policy template.

```
permit(
  principal == ?principal,
  action in [Action::"Read", Action::"Edit", Action::"Comment"],
  resource == ?resource
);
```

If you were to create a policy named `Editor` based on this template, when a principal is designated as an editor for a specific resource, your application would create a policy that provides permissions for the principal to read, edit, and comment on the resource.

Unlike static policies, template-linked policies are dynamic. Take the previous example, if you were to remove the `Comment` action from the policy template, any policy linked to, or based on, that template would be updated accordingly and the principals specified in the policies would no longer be able to comment on the corresponding resources.

For more template-linked policy examples, see [Amazon Verified Permissions example template-linked policies](policy-templates-example-policies.md).

# Creating Amazon Verified Permissions policy templates
Creating policy templates

You can create policy templates in Verified Permissions using the Amazon Web Services Management Console, the Amazon CLI, or the Amazon SDKs. Policy templates allow a policy to be defined once and then used with multiple principals and resources. Once you create a policy template you can then create template-linked policies to use the policy templates with specific principals and resources. For more information, see [Creating Amazon Verified Permissions template-linked policies](policy-templates-create-policy.md).

------
#### [ Amazon Web Services Management Console ]

**To create a policy template**

1. Open the [Verified Permissions console](https://console.amazonaws.cn/verifiedpermissions/). Choose your policy store.

1. In the navigation pane on the left, choose **Policy templates**.

1. Choose **Create policy template**.

1. In the **Details** section, type a **Policy template description**.

1. In the **Policy template body** section, use placeholders `?principal` and `?resource` to allow policies created based on this template to customize permissions they grant. You can choose **Format** to format the syntax of your policy template with the recommended spacing and indentation.

1. Choose **Create policy template**.

------
#### [ Amazon CLI ]

**To create a policy template**  
You can create a policy template by using the [CreatePolicyTemplate](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_CreatePolicyTemplate.html) operation. The following example creates a policy template with a placeholder for the principal.

The file `template1.txt` contains the following.

```
"VacationAccess"
permit(
    principal in ?principal,
    action == Action::"view",
    resource == Photo::"VacationPhoto94.jpg"
);
```

```
$ aws verifiedpermissions create-policy-template \
    --description "Template for vacation picture access" 
    --statement file://template1.txt 
    --policy-store-id PSEXAMPLEabcdefg111111
{
    "createdDate": "2023-05-18T21:17:47.284268+00:00",
    "lastUpdatedDate": "2023-05-18T21:17:47.284268+00:00",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "policyTemplateId": "PTEXAMPLEabcdefg111111"
}
```

**To create a policy template with a policy template name**  
You can optionally specify a policy template name when creating a policy template. The name must be unique for all policy templates within the policy store and prefixed with `name/`. You can use the name in place of the policy template ID.

```
$ aws verifiedpermissions create-policy-template \
    --description "Template for vacation picture access" \
    --statement file://template1.txt \
    --policy-store-id PSEXAMPLEabcdefg111111 \
    --name name/example-policy-template
{
    "createdDate": "2023-06-12T20:47:42.804511+00:00",
    "lastUpdatedDate": "2023-06-12T20:47:42.804511+00:00",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "policyTemplateId": "PTEXAMPLEabcdefg111111"
}
```

**Note**  
If you specify a name that is already associated with another policy template in the policy store, you receive a `ConflictException` error.

------

# Creating Amazon Verified Permissions template-linked policies
Creating template-linked policies

You can create template-linked policies, or policies that are based on a policy template, using the Amazon Web Services Management Console, Amazon CLI, or the Amazon SDKs. Template-linked policies stay linked to their policy templates. If you change the policy statement in the policy template, any policies linked to that template automatically use the new statement for all authorization decisions made from that moment forward.

For template-linked policy examples, see [Amazon Verified Permissions example template-linked policies](policy-templates-example-policies.md).

------
#### [ Amazon Web Services Management Console ]

**To create a template-linked policy by instantiating a policy template**

1. Open the [Verified Permissions console](https://console.amazonaws.cn/verifiedpermissions/). Choose your policy store.

1. In the navigation pane on the left, choose **Policies**.

1. Choose **Create policy** and then choose **Create template-linked policy**.

1. Choose the radio button next to the policy template to use and then choose **Next**.

1. Type the **Principal** and **Resource** to be used for this specific instance of the template-linked policy. The specified values are displayed in the **Policy statement preview** field.
**Note**  
The **Principal** and **Resource** values must have the same formatting as static policies. For example, to specify the `AdminUsers` group for the principal, type `Group::"AdminUsers"`. If you type `AdminUsers`, a validation error is displayed.

1. Choose **Create template-linked policy**.

   The new template-linked policy is displayed under **Policies**.

------
#### [ Amazon CLI ]

**To create a template-linked policy by instantiating a policy template**  
You can create a template-linked policy that references an existing policy template and that specifies values for any placeholders used by the template. 

The following example creates a template-linked policy that uses a template with the following statement:

```
permit(
    principal in ?principal,
    action == PhotoFlash::Action::"view",
    resource == PhotoFlash::Photo::"VacationPhoto94.jpg"
);
```

It also uses the following `definition.txt` file to supply the value for the `definition` parameter:

```
{
    "templateLinked": {
        "policyTemplateId": "PTEXAMPLEabcdefg111111",
        "principal": {
            "entityType": "PhotoFlash::User",
            "entityId": "alice"
        }
    }
}
```

The output shows both the resource, which it gets from the template, and the principal, which it gets from the definition parameter

```
$ aws verifiedpermissions create-policy \
    --definition file://definition.txt
    --policy-store-id PSEXAMPLEabcdefg111111
{
    "createdDate": "2023-05-22T18:57:53.298278+00:00",
    "lastUpdatedDate": "2023-05-22T18:57:53.298278+00:00",
    "policyId": "TPEXAMPLEabcdefg111111",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "policyType": "TEMPLATELINKED",
    "principal": {
        "entityId": "alice",
        "entityType": "PhotoFlash::User"
    },
    "resource": {
        "entityId": "VacationPhoto94.jpg",
        "entityType": "PhotoFlash::Photo"
    }
}
```

------

# Editing Amazon Verified Permissions policy templates
Editing policy templates

You can edit, or update, policy templates in Verified Permissions using the Amazon Web Services Management Console, the Amazon CLI, or the Amazon SDKs. Editing a policy template will automatically update the policies that are linked to, or based on, the template so take care when editing the policy templates and make sure you don’t accidentally introduce a change that breaks your application.

You can change the following elements of a policy template:
+ The `action` referenced by the policy template
+ A condition clause, such as `when` and `unless`

You can't change the following elements of a policy template. To change any of these elements you will need to delete and re-created the policy template.
+ The effect of a policy template from `permit` or `forbid`
+ The `principal` referenced by a policy template
+ The `resource` referenced by a policy template

------
#### [ Amazon Web Services Management Console ]

**To edit your policy templates**

1. Open the [Verified Permissions console](https://console.amazonaws.cn/verifiedpermissions/). Choose your policy store.

1. In the navigation pane on the left, choose **Policy templates**. The console displays all of the policy templates you created in the current policy store.

1. Choose the radio button next to a policy template to display details about the policy template, such as when the policy template was created, updated, and the policy template contents.

1. Choose **Edit** to edit your policy template. Update the **Policy description** and **Policy body** as necessary and then choose **Update policy template**.

1. You can delete a policy template by choosing the radio button next to a policy template and then choosing **Delete**. Choose **OK** to confirm deleting the policy template.

------
#### [ Amazon CLI ]

**To edit a policy template**  
You can create a static policy by using the [UpdatePolicy](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_UpdatePolicy.html) operation. The following example updates the specified policy template by replacing its policy body with a new policy defined in a file.

Contents of file `template1.txt`:

```
permit(
    principal in ?principal,
    action == Action::"view",
    resource in ?resource)
when {
    principal has department && principal.department == "research"
};
```

```
$ aws verifiedpermissions update-policy-template \
    --policy-template-id PTEXAMPLEabcdefg111111 \
    --description "My updated template description" \
    --statement file://template1.txt \ 
    --policy-store-id PSEXAMPLEabcdefg111111
{
    "createdDate": "2023-05-17T18:58:48.795411+00:00",
    "lastUpdatedDate": "2023-05-17T19:18:48.870209+00:00",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "policyTemplateId": "PTEXAMPLEabcdefg111111"
}
```

**To update the name of a policy template**  
You can set or update a policy template name when updating a policy template. The name must be unique for all policy templates within the policy store and prefixed with `name/`. If you don't include the name field in the update request, the existing name is unchanged. To remove a name, set it to an empty string.

```
$ aws verifiedpermissions update-policy-template \
    --policy-template-id PTEXAMPLEabcdefg111111 \
    --statement file://template1.txt \
    --policy-store-id PSEXAMPLEabcdefg111111 \
    --name name/example-policy-template
{
    "createdDate": "2023-05-17T18:58:48.795411+00:00",
    "lastUpdatedDate": "2023-05-17T19:18:48.870209+00:00",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "policyTemplateId": "PTEXAMPLEabcdefg111111"
}
```

------

# Amazon Verified Permissions example template-linked policies
Example template-linked policies

When you create a policy store in Verified Permissions using the **Sample policy store** method, your policy store is created with predefined policies, policy templates, and a schema for the sample project you chose. The following Verified Permissions template-linked policy examples can be used with the sample policy stores and their respective policies, policy templates, and schemas.

## PhotoFlash examples


The following example shows how you might create a template-linked policy that uses the policy template **Grant limited access to non-private shared photos** with an individual user and photo.

**Note**  
Cedar policy language considers an entity to be `in` itself. Therefore, `principal in User::"Alice"` is equivalent to `principal == User::"Alice"`.

```
permit (
 principal in PhotoFlash::User::"Alice",
 action in PhotoFlash::Action::"SharePhotoLimitedAccess",
 resource in PhotoFlash::Photo::"VacationPhoto94.jpg"
 );
```

The following example shows how you might create a template-linked policy that uses the policy template **Grant limited access to non-private shared photos** with an individual user and album.

```
permit (
 principal in PhotoFlash::User::"Alice",
 action in PhotoFlash::Action::"SharePhotoLimitedAccess",
 resource in PhotoFlash::Album::"Italy2023"
 );
```

The following example shows how you might create a template-linked policy that uses the policy template **Grant limited access to non-private shared photos** with a friend group and individual photo.

```
permit (
 principal in PhotoFlash::FriendGroup::"Jane::MySchoolFriends",
 action in PhotoFlash::Action::"SharePhotoLimitedAccess",
 resource in PhotoFlash::Photo::"VacationPhoto94.jpg"
 );
```

The following example shows how you might create a template-linked policy that uses the policy template **Grant limited access to non-private shared photos** with a friend group and album.

```
permit (
 principal in PhotoFlash::FriendGroup::"Jane::MySchoolFriends",
 action in PhotoFlash::Action::"SharePhotoLimitedAccess",
 resource in PhotoFlash::Album::"Italy2023"
 );
```

The following example shows how you might create a template-linked policy that uses the policy template **Grant full access to non-private shared photos** with a friend group and an individual photo.

```
permit (
 principal in PhotoFlash::UserGroup::"Jane::MySchoolFriends",
 action in PhotoFlash::Action::"SharePhotoFullAccess",
 resource in PhotoFlash::Photo::"VacationPhoto94.jpg"
 );
```

The following example shows how you might create a template-linked policy that uses the policy template **Block user from an account**.

```
forbid(
 principal == PhotoFlash::User::"Bob",
 action,
 resource in PhotoFlash::Account::"Alice-account"
 );
```

## DigitalPetStore examples


The DigitalPetStore sample policy store does not include any policy templates. You can view the policies included with the policy store by choosing **Policies** in the navigation pane on the left after creating the **DigitalPetStore** sample policy store.

## TinyToDo examples


The following example shows how you might create a template-linked policy that uses the policy template that gives viewer access for an individual user and task list.

```
permit (
    principal == TinyTodo::User::"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_h2aKCU1ts|5ae0c4b1-6de8-4dff-b52e-158188686f31|bob",
    action in [TinyTodo::Action::"ReadList", TinyTodo::Action::"ListTasks"],
    resource == TinyTodo::List::"1"
);
```

The following example shows how you might create a template-linked policy that uses the policy template that gives editor access for an individual user and task list.

```
permit (
    principal == TinyTodo::User::"https://cognito-idp.us-east-1.amazonaws.com/us-east-1_h2aKCU1ts|5ae0c4b1-6de8-4dff-b52e-158188686f31|bob",
    action in [
        TinyTodo::Action::"ReadList",
        TinyTodo::Action::"UpdateList",
        TinyTodo::Action::"ListTasks",
        TinyTodo::Action::"CreateTask",
        TinyTodo::Action::"UpdateTask",
        TinyTodo::Action::"DeleteTask"
    ],
    resource == TinyTodo::List::"1"
);
```