Creating enterprise-managed authorization policy templates

Create predefined authorization policies for your enterprise that enable a source service to access a target service based on a set of assigned roles. In an authorization, the source service is the service that is granted access to the target service. A source service can be in the same account where the authorization is created or in another account. The target service is the service that you are granting permission to be accessed by the source service based on the roles that you assign. The target service is always in the account where the authorization is created.

Example authorization policy templates.
Source	Target	Description
This account	Child account	Service in the enterprise account gets access to a service in the child account where the template is assigned.
Assigned account(s)	Child account	Service in the assigned child account gets access to another service in the same child account.
Specific account	Child account	Service in the specified child account gets access to a service in the child account where the template is assigned.

Review the following scenarios to understand how authorization policy templates simplify the creation and management of many authorization policies:

Replicating authorization relationships in various child accounts in an enterprise.
- For example, an enterprise that uses the service "File Storage for VPC" might want to establish a disaster recovery pattern by enabling cross-region replication of critical data. To enable data replication, you must create an authorization policy template and assign it in each child account. The authorization policy grants the file service in one VPC access to interact with the file service of another VPC located in a different geographical region in the same account. You can create an authorization policy template and specify "File Storage for VPC" for both the source and target. For a detailed example of this authorization policy template, review the examples in this topic. For more information, see Establishing service-to-service authorizations for File Storage for VPC.
Allowing a service instance in an enterprise account to access resources in many child accounts.
- For example, an enterprise might want a centralized data store, where the volumes are encrypted by using encryption keys that reside in child accounts. You can create an authorization policy template to define a service-to-service authorization between the source service, "Block Storage" service in an enterprise account, and the target service, "Key Management Service" in a child account. When you assign this template to child accounts, authorization policies are automatically created in each child accounts that grant the "Block Storage" service access to the "Key Management Service".

Creating an authorization policy template in the console

To create an authorization policy template, complete the following steps:

Go to Manage > Access (IAM) > Templates in the console.
Select Authorizations and click Create.
Enter a name and description for the authorization template that describes its purpose for enterprise users.
Enter a description for the enterprise-managed authorization policy that describes its purpose for child account users.
Click Create.

Next complete the following steps to build the authorization rules:

Go to Authorization to specify the details of the authorization policy.
Select the account from which the source service requests access to another service. For this example select Assigned account(s), but there are a few options to consider:
1. This account: The single, root enterprise account
2. Assigned account(s): When you assign the authorization template to a child account, the source account is populated to the same account as the target child account, which holds the resource being accessed.
3. Specific account: A single specific account within the enterprise.
The target is always in the child account where the template is assigned. The source can be the same child account as the target (Assigned account), the root enterprise account (This account) or a specific account in the enterprise (Specific account).
Next you select the source service and resources. For this example, select VPC Infrastructure Services from the list. Click Next.
1. Select the scope by clicking Specific resources.
2. Click Select an attribute.
3. From the list, select Resource type.
4. In the next field, select File Storage for VPC.
5. Click Next.
For the target service, select VPC Infrastructure Services from the list. Click Next.
1. Select the scope by clicking Specific resources.
2. Click Select an attribute.
3. From the list, select Resource type.
4. In the next field, select File Storage for VPC.
5. Click Next.
Select the role Editor.
Click Review and Save.
The template is now ready to commit and assign to child accounts.

This example creates authorization policies that help enable data replication in various child accounts where the template is assigned.

Templates are valuable only if they are generic enough to apply to multiple accounts. The previous example specifies File Storage for VPC for both the source and target, but does not include specific instance IDs because those are specific to the resources in each child account.

Deleting an authorization policy template in the console

Deleting an authorization policy template deletes all version of the template. You can delete an authorization policy template that's referenced in a Draft or Committed state. You cannot delete authorization policy templates that are in Assigned state, you must unassign it first.

To delete a policy template in the console, complete the following steps:

Go to Manage > Access (IAM) > Templates in the IBM Cloud.
Click Authorizations.
Click the Actions icon > Delete template.
Confirm that you want to delete the template.

Deleting an authorization policy template version in the console

To delete only a specific version, complete the following steps:

Go to Manage > Access (IAM) > Templates in the IBM Cloud.
Click Authorizations.
Click the Actions icon > Delete version.
Confirm that you want to delete the version.

Create an authorization policy template by using the CLI

To create an authorization policy template, complete the following steps in the CLI:

Create a JSON file that configures the definition of the authorization policy template. For more information about the attributes that you can use in your JSON file, see the IAM Policy Management API.

The following example JSON file specifies the name and description of the template and the account_id of the enterprise account. Then, the authorization policy definition is defined. This authorization template grants an Editor role between all "File Storage for VPC" in the assigned accounts.

    {
      "name": "VPC_REGIONAL_REPLICATOR",
      "description": "Grant Editor Role between VPC File Storage to enable regional replication",
      "account_id": "ENTERPRISE_ROOT_ACCOUNT_ID",
      "policy": {
        "type": "authorization",
        "description": "Grant Editor on VPC File Storage",
        "control": {
            "grant": {
            "roles": [
              {
                "role_id": "crn:v1:bluemix:public:iam::::role:Editor"
              }
            ]
          }
        },
        "subject":
          {
            "attributes": [
              {
                "key": "serviceName",
                "operator": "stringEquals",
                "value": "is"
              },
              {
                "key": "resourceType",
                "operator": "stringEquals",
                "value": "share"
              }
            ]
          }
        ,
        "resource":
          {
            "attributes": [
              {
                "key": "serviceName",
                "operator": "stringEquals",
                "value": "is"
              },
              {
                "key": "resourceType",
                "operator": "stringEquals",
                "value": "share"
              }
            ]
          }
      }
}

Use the authorization-policy-template-create command as shown in the following sample request:

 ibmcloud iam authorization-policy-template-create --file /path/to/vpc-share-authorization-template.json

Updating an authorization policy template by using the CLI

You can update the roles, target, source, name, and description for an authorization template at any time before you commit it.

To update an authorization template by using the CLI, complete the following steps:

Update your JSON file with the new authorization template definition. For more information about the attributes that you can use in your JSON file, see the IAM Policy Management API.

When you update the template name, you update the name for every version.
Use the authorization-policy-template-version-update command as shown in the following sample request:
```
 iam  authorization-policy-template-version-update VPC_REGIONAL_REPLICATOR 1 --file /path/to/vpc-share-authorization-template-updated.json
```
This updates version 1 of the VPC_REGIONAL_REPLICATOR authorization template by referring to the updated JSON file.

When you update an existing template, remove the "account_id"

If you need to make updates after you commit the template, create a new version.

Committing an authorization template version by using the CLI

Review the authorization template and commit it so that no further changes can be made to the version. This way, the Template Assignment Administrator can be sure that they assign the version only when you confirm that it's ready.

Review the authorization policy template before you commit it by using the authorization-policy-template-version method to view the specific version.
```
ibmcloud iam authorization-policy-template-version VPC_REGIONAL_REPLICATOR 1
```
To commit an authorization template by using the CLI, use the authorization-policy-template-version-commit method as shown in the following sample request:
```
ibmcloud iam authorization-policy-template-version-commit  VPC_REGIONAL_REPLICATOR 1
```

Assigning access with an authorization template by using the CLI

Assign an authorization template by using the CLI to an account within the enterprise to create the underlying authorization policies in that account.

Create an authorization template by using the authorization-policy-assignment-create command as shown in the following sample request:
```
 iam authorization-policy-assignment-create  VPC_REGIONAL_REPLICATOR 1  --target-type Account --target <<ACCOUNT_ID>>
```
Use the authorization-policy-assignment command to see or refresh the status of the assignment as shown:
```
 iam authorization-policy-assignment <<POLICY_ASSIGNMENT_GUID>>
```

It might take a few seconds for the assignment to create the underlying resources and display the appropriate status.

Unassigning an authorization template by using the CLI

Unassigning an authorization policy assignment removes all the underlying resources that assignment created within the child accounts. To unassign an authorization template by using the CLI, complete the following command:

Use the authorization-policy-assignment-delete command to run an unassignment against a particular authorization policy assignment.
```
 iam authorization-policy-assignment-delete <<POLICY_ASSIGNMENT_GUID>>
```

Creating a version of an access policy template by using the CLI

As access requirements evolve for teams in your enterprise, you might need to create another version of an authorization template to meet new needs. To create a new authorization template version by using the CLI, complete the following steps:

Edit your JSON file to include any updates to the authorization template definition. For more information about the attributes that you can use in your JSON file, see the IAM Policy Management API

Use the authorization-policy-template-version-create command as shown in the following sample request:

ibmcloud iam authorization-policy-template-version-create VPC_REGIONAL_REPLICATOR --file /path/to/vpc-share-authorization-template-updated_v2.json

Deleting a version of an authorization policy template by using the CLI

You can delete a particular version of an authorization policy template that's referenced in a Draft or Committed state. You cannot delete authorization policy templates that are in Assigned state, you must unassign it first.

To delete a version of an authorization policy template in the CLI, complete the following steps:

Get the ID and version of the authorization policy template by using the authorization-policy-template command as shown in the following sample request:
```
ibmcloud iam authorization-policy-templates
```
Delete the particular version by using the authorization-policy-template-version-delete command as shown in the following sample request:
```
ibmcloud iam authorization-policy-template-version-delete VPC_REGIONAL_REPLICATOR 2
```

This example deletes version 2 of the VPC_REGIONAL_REPLICATOR policy template.