Create and manage policies

Policies define a set of allowed actions. After a policy is defined, you can add it to roles giving users with those roles the corresponding privileges.

Define a custom policy

You can create a user-defined policy with a JSON file or string that defines the following:

One or more Chef 360 Platform API endpoints or routes
One or more HTTP methods
Whether those endpoints and methods are allowed or denied

You can group multiple sets of policy rights using more than one statement.

To define a policy, create a JSON file or string. For example,

{
  "version":"1.0",
  "name":"<POLICY_NAME>",
  "description":"<POLICY_DESCRIPTION>",
  "statements":[
    {
      "action":"<ACTION>",
      "routes":[
        "/resource/*"
      ],
      "verbs":[
        "get",
        "post",
        "put",
        "delete"
      ]
    }
  ]
}

Custom policy properties

A policy definition has the following properties:

version

The version of the policy format. This helps in maintaining and managing multiple versions of policies.

Data type: string

Example: "version": "1.0"

name

The name of the policy. It uniquely identifies the policy within the system.

Data type: string

Example: "name": "example-policy"

description

A brief description of what the policy allows or denies.

Data type: string

Example: "description": "Allows read access to Courier data"

statements

One or more statements that specifies what actions are allowed or denied.

Data type: array of objects

action

Defines the action that the policy permits or denies. Common actions include "Allow" or "Deny".

Data type: string

Example: "action": "Allow"

routes

Specifies the routes or endpoints that the policy applies to. You can use wildcards (*) to represent multiple matching routes. To get the list of API routes, see the API reference.

Data type: array of strings

Example: "routes": ["/resource/*"]

verbs

Defines the HTTP methods (verbs) that are allowed or denied by the policy. Common HTTP methods include "get", "post", "put", and "delete".

Data type: array of strings

Example: "verbs": ["get"]

Policy examples

The courier-tracker policy allows users to perform GET requests on any endpoint that matches the /courier/* route. This provides read-only access to Chef Courier-related data.

{
  "version":"1.0",
  "name":"courier-tracker",
  "description":"Allows read access to read data from the courier jobs",
  "statements":[
    {
      "action":"Allow",
      "routes":[
        "/courier/*"
      ],
      "verbs":[
        "get"
      ]
    }
  ]
}

Create a policy

To create a policy use the authz policy create-policy command and pass in the policy settings in a JSON string or file.

chef-platform-auth-cli authz policy create-policy --body '{
    "version": "1.0",
    "name": "courier-tracker",
    "description": "Allows read access to read data from the courier jobs",
    "statements": [
    {
      "action": "Allow",
      "routes": [
        "/courier/*"
      ],
      "verbs": [
        "get"
      ]
    }
    ]
}' --profile <PROFILE_NAME>

Replace <PROFILE_NAME> with a profile associated with the organization that you are adding the policy to.

The response is similar to the following:

{
  "item": {
    "id": "e12acd8a-da0c-4fee-bd9b-f31c9c280271",
    "definedBy": "user",
    "version": "1.0",
    "name": "courier-tracker",
    "description": "Allows read access to read data from the courier jobs",
    "status": "enabled",
    "statements": [
      {
        "action": "Allow",
        "routes": [
          "/courier/*"
        ],
        "verbs": [
          "get"
        ]
      }
    ]
  }
}

List policies

To list system policies and user-defined policies registered in the current organization, use the authz policy list-policy command.

chef-platform-auth-cli authz policy list-policy

The command returns user-defined policies by default.

Use --definedBy system to list system-defined policies:

chef-platform-auth-cli authz policy list-policy --definedBy system

The response is similar to the following:

{
  "items": [
    {
      "definedBy": "user",
      "description": "My tenant admin policy",
      "id": "710522af-dc74-4a2b-a975-053235a355ae",
      "name": "tenant-admin-policy1-756ky",
      "statements": [
        {
          "action": "Allow",
          "routes": [
            "/*"
          ],
          "variables": null,
          "verbs": [
            "*"
          ]
        }
      ],
      "status": "enabled",
      "version": "1.0"
    },
    {
      "definedBy": "user",
      "description": "My tenant admin policy",
      "id": "2e149447-7e16-4457-a2b5-654c256c542b",
      "name": "tenant-admin-policy1-cn94n",
      "statements": [
        {
          "action": "Allow",
          "routes": [
            "/*"
          ],
          "variables": null,
          "verbs": [
            "*"
          ]
        }
      ],
      "status": "enabled",
      "version": "1.0"
    }
  ]
}

Get policy details

To get details of a user-defined policy or a system-defined policy in an organization, use the authz policy get-policy command.

chef-platform-auth-cli authz policy get-policy --policyId <POLICY_ID>

The response is similar to the following:

{
  "item": {
    "definedBy": "user",
    "description": "My admin policy",
    "id": "ade1354a-3873-45ff-a8d6-ce60ef70e8e1",
    "name": "admin-policy1-7igyp",
    "statements": [
      {
        "action": "Allow",
       "routes": [
            "/platform/user-accounts/v1/identity/device/{}/enable",
            "/platform/user-accounts/v1/identity/device/{}/disable",
            "/platform/user-accounts/v1/self/api-token/{}/revoke",
            "/platform/user-accounts/v1/identity/self/credentials"
        ],
        "variables": null,
        "verbs": [
          "*"
        ]
      }
    ],
    "status": "enabled",
    "version": "1.0"
  }
}

Update a policy

To update an existing policy in the current organization, use the authz policy update-policy command. This method only allows you to update user-defined policies.

chef-platform-auth-cli authz policy update-policy --policyId <policy-id> --body '{
    "definedBy": "user",
    "description": "My admin policy",
    "id": "ade1354a-3873-45ff-a8d6-ce60ef70e912",
    "name": "admin-7igyp",
    "statements": [
      {
        "action": "Allow",
        "routes": [
          "/*"
        ],
        "variables": null,
        "verbs": [
          "*"
        ]
      }
    ],
    "status": "enabled",
    "version": "1.0"
  }'

The response is similar to the following:

{
  "item": {
    "definedBy": "user",
    "description": "My admin policy",
    "id": "ade1354a-3873-45ff-a8d6-ce60ef70e912",
    "name": "admin-7igyp",
    "statements": [
      {
        "action": "Allow",
        "routes": [
          "/*"
        ],
        "variables": null,
        "verbs": [
          "*"
        ]
      }
    ],
    "status": "enabled",
    "version": "1.0"
  }
}

Enable a policy

To enable a disabled policy, use the authz policy enable-policy command.

This enables enforcement of the policy. This operation can only be used to enable an already disabled user policy.

chef-platform-auth-cli authz policy enable-policy --policyId <POLICY_ID>

It returns the following response:

{
  "code": 200,
  "message": "enable-policy successful"
}

Disable a policy

To disable a policy, use the authz policy disable-policy command.

This deactivates policy enforcement. You can only use this command to disable an already-enabled user policy.

chef-platform-auth-cli authz policy disable-policy --policyId <POLICY_ID>

It returns the following response:

{
  "code": 200,
  "message": "disable-policy successful"
}

Delete a policy

To delete an existing policy under current organization, use the authz policy delete-policy command.

This only allows you to delete user-defined policies.

chef-platform-auth-cli authz policy delete-policy --policyId <POLICY_ID>

It returns the following response:

{
  "code": 200,
  "message": "delete-policy successful"
}