Sentinel Policies

»Challenge

ACL policies are path-based and present the following challenges:

• Cannot grant permissions based on logic other than paths
• Paths are merged in ACL policies which could potentially cause a conflict as the number of policies grows

What if the policy requirement was to grant read permission on secret/orders path only if the request came from an IP address within a certain CIDR?

»Solution

Use Sentinel Role Governing Policies (RGPs) and Endpoint Governing Policies (EGPs) to fulfill more complex policy requirements.

Sentinel can access properties of the incoming requests and make a decision based on a certain set of conditions. Available properties include:

• request - Information about the request itself (path, operation type, parameters, etc.)
• token - Information about the token being used (creation time, attached policies, etc.)
• identity - Identity entities and all related data
• mfa - Information about successful MFA validations

Sentinel is a language framework for policy built to be embedded in Vault Enterprise to enable fine-grained, logic-based policy decisions which cannot be fully handled by the ACL policies.

EGPs and RGPs can be defined using Sentinel:

• EGPs are tied to particular paths (e.g. aws/creds/)
• RGPs are tied to particular tokens, identity entities, or identity groups

»Prerequisites

To perform the tasks described in this tutorial, you need to have a Vault Enterprise environment.

»Policy requirements

Since this tutorial demonstrates the creation of policies, log in with highly privileged token such as root.

The specific required policy capabilities are as follows.

# To list policies
path "sys/policies/*"
{
  capabilities = ["list"]
}

# Create and manage EGPs
path "sys/policies/egp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Create and manage RGPs
path "sys/policies/rgp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# To list policies
path "sys/policies/*"
{
  capabilities = ["list"]
}

# Create and manage EGPs
path "sys/policies/egp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Create and manage RGPs
path "sys/policies/rgp/*"
{
  capabilities = ["create", "read", "update", "delete", "list"]
}

»Lab setup

Export an environment variable for the vault CLI to address the Vault Enterprise server.

Example:

$ export VAULT_ADDR="http://127.0.0.1:8200"

$ export VAULT_ADDR="http://127.0.0.1:8200"

Export an environment variable for the vault CLI to authenticate with the Vault Enterprise server.

Example:

$ export VAULT_TOKEN="hvs.AGvcQ6XuMDwPYB5OpQUYr3Rf"

$ export VAULT_TOKEN="hvs.AGvcQ6XuMDwPYB5OpQUYr3Rf"

»Write Sentinel Policies

»Anatomy of a Sentinel Policy

import "<library>"

<variable> = <value>

main = rule {
     <conditions_to_evaluate>
}

import "<library>"

<variable> = <value>

main = rule {
     <conditions_to_evaluate>
}

• import - Enables your policy to access reusable libraries. There are a set of built-in imports available to help define your policy rules.

• main (required) - Every Sentinel policy must have a main rule which is evaluated to determine the result of a policy.

• rule - A first-class construct in Sentinel. It describes a set of conditions resulting in either true or false. Refer to the Boolean Expressions for the full list of available operators in writing rules.

• <variable> - Variables are dynamically typed in Sentinel. You can define its value explicitly or implicitly by the host system or function.

»Endpoint Governing Policies (EGPs)

Write endpoint governing policies (EGPs) that fulfill the following requirements:

1. Any incoming request against the "secret/accounting/*" to be performed during the business hours (7:00 am to 6:00 pm during the work days).

2. Any create, update and delete operations against Key/Value secret engine (mounted at "secret") must come from an internal IP of 122.22.3.4/32 CIDR.

»Requirement #1: Check for the business hours

import "time"

# Expect requests to only happen during work days (Monday through Friday)
# 0 for Sunday and 6 for Saturday
workdays = rule {
    time.now.weekday > 0 and time.now.weekday < 6
}

# Expect requests to only happen during work hours (7:00 am - 6:00 pm)
workhours = rule {
    time.now.hour > 7 and time.now.hour < 18
}

main = rule {
    workdays and workhours
}

import "time"

# Expect requests to only happen during work days (Monday through Friday)
# 0 for Sunday and 6 for Saturday
workdays = rule {
    time.now.weekday > 0 and time.now.weekday < 6
}

# Expect requests to only happen during work hours (7:00 am - 6:00 pm)
workhours = rule {
    time.now.hour > 7 and time.now.hour < 18
}

main = rule {
    workdays and workhours
}

»Requirement #2: Check for the IP address

The main has conditional rule (when precond) to ensure that the rule gets evaluated only if the request is relevant.

import "sockaddr"
import "strings"

# Only care about create, update, and delete operations against secret path
precond = rule {
    request.operation in ["create", "update", "delete"] and
    strings.has_prefix(request.path, "secret/")
}

# Requests to come only from our private IP range
cidrcheck = rule {
    sockaddr.is_contained(request.connection.remote_addr, "122.22.3.4/32")
}

# Check the precondition before execute the cidrcheck
main = rule when precond {
    cidrcheck
}

import "sockaddr"
import "strings"

# Only care about create, update, and delete operations against secret path
precond = rule {
    request.operation in ["create", "update", "delete"] and
    strings.has_prefix(request.path, "secret/")
}

# Requests to come only from our private IP range
cidrcheck = rule {
    sockaddr.is_contained(request.connection.remote_addr, "122.22.3.4/32")
}

# Check the precondition before execute the cidrcheck
main = rule when precond {
    cidrcheck
}

»Simulate Sentinel policies

You can test the Sentinel policies prior to deployment in order to validate syntax and to document expected behavior.

1. Download the Sentinel simulator for your platform.

   Example for MacOS:

   $ wget https://releases.hashicorp.com/sentinel/0.18.11/sentinel_0.18.11_darwin_amd64.zip
   

   $ wget https://releases.hashicorp.com/sentinel/0.18.11/sentinel_0.18.11_darwin_amd64.zip
   

   Copy

2. Unzip the downloaded file.

   $ unzip sentinel_0.18.11_darwin_amd64.zip -d /usr/local/bin
   

   $ unzip sentinel_0.18.11_darwin_amd64.zip -d /usr/local/bin
   

   Copy

»Write the test cases

1. Create a sub-folder named test where cidr-check.sentinel and business-hrs.sentinel policies are located.

   Under the test folder, create a sub-folder for cidr-check.

   $ mkdir -p test/cidr-check
   

   $ mkdir -p test/cidr-check
   

   Copy

2. Create a sub-folder for business-hrs under the test directory.

   $ mkdir -p test/business-hrs
   

   $ mkdir -p test/business-hrs
   

   Copy

   NOTE: The test should be created under /test/<policy_name> folder.

3. Write a passing test case in a file named success.json under test/business-hrs directory.

   {
      "mock": {
         "time": {
            "now": {
            "weekday": 1,
            "hour": 12
            }
         }
      },
      "test": {
         "main": true
      }
   }
   

   test/business-hrs/success.json

   Copy

   {
      "mock": {
         "time": {
            "now": {
            "weekday": 1,
            "hour": 12
            }
         }
      },
      "test": {
         "main": true
      }
   }
   

   Under mock, you specify the mock test data. In this example, the weekday is set to 1 which is Monday and hour is set to 12 which is noon. Therefore the main should return true.

4. Write a failing test in a file named fail.json under test/business-hrs.

   {
      "mock": {
         "time": {
            "now": {
            "weekday": 0,
            "hour": 12
            }
         }
      },
      "test": {
         "main": false
      }
   }
   

   test/business-hrs/fail.json

   Copy

   {
      "mock": {
         "time": {
            "now": {
            "weekday": 0,
            "hour": 12
            }
         }
      },
      "test": {
         "main": false
      }
   }
   

   The mock data is set to Sunday at noon; therefore Therefore, the main should return false.

5. Similarly, write a passing test case for cidr-check policy, test/cidr-check/success.json.

   {
      "global": {
         "request": {
            "connection": {
            "remote_addr": "122.22.3.4"
            },
            "operation": "create",
            "path": "secret/orders"
         }
      }
   }
   

   test/cidr-check/success.json

   Copy

   {
      "global": {
         "request": {
            "connection": {
            "remote_addr": "122.22.3.4"
            },
            "operation": "create",
            "path": "secret/orders"
         }
      }
   }
   

   In this example, the global specifies the create operation is invoked on secret/orders endpoint which initiated from an IP address 122.22.3.4. Therefore the main should return true.

6. Write a failing test for cidr-check policy, test/cidr-check/fail.json.

   {
      "global": {
         "request": {
            "connection": {
            "remote_addr": "122.22.3.10"
            },
            "operation": "create",
            "path": "secret/orders"
         }
      },
      "test": {
         "precond": true,
         "main": false
      }
   }
   

   test/cidr-check/fail.json

   Copy

   {
      "global": {
         "request": {
            "connection": {
            "remote_addr": "122.22.3.10"
            },
            "operation": "create",
            "path": "secret/orders"
         }
      },
      "test": {
         "precond": true,
         "main": false
      }
   }
   

   This test will fail because of the IP address mismatch. However, the precond should pass since the requested operation is create and the targeted endpoint is secret/orders.

   The optional test definition adds more context to why the test should fail. The expected behavior is that the test fails because main returns false but precond should return true.

   Now, you have written both success and failure tests.

   ├── business-hrs.sentinel
   ├── cidr-check.sentinel
   └── test
      ├── business-hrs
      │   ├── fail.json
      │   └── success.json
      └── cidr-check
         ├── fail.json
         └── success.json
   

   ├── business-hrs.sentinel
   ├── cidr-check.sentinel
   └── test
      ├── business-hrs
      │   ├── fail.json
      │   └── success.json
      └── cidr-check
         ├── fail.json
         └── success.json
   

7. Execute the test.

   $ sentinel test
   

   $ sentinel test
   

   Copy

   Successful output:

   PASS - business-hrs.sentinel
   PASS - test/business-hrs/fail.json
   PASS - test/business-hrs/success.json
   PASS - cidr-check.sentinel
   PASS - test/cidr-check/fail.json
   PASS - test/cidr-check/success.json
   

   PASS - business-hrs.sentinel
   PASS - test/business-hrs/fail.json
   PASS - test/business-hrs/success.json
   PASS - cidr-check.sentinel
   PASS - test/cidr-check/fail.json
   PASS - test/cidr-check/success.json
   

   NOTE: If you want to see the tracing and log output for those tests, run the command with -verbose flag.

»Deploy EGP policies

Sentinel policies have three enforcement levels:

Since both policies are tied to specific paths, the policy type that you are going to create is Endpoint Governing Policies (EGPs).

»Verification

Once the policies are deployed, create, update and delete operations coming from an IP address other than 122.22.3.4 will be denied.

$ vault kv put secret/accounting/test acct_no="293472309423"

$ vault kv put secret/accounting/test acct_no="293472309423"

Expected failure output:

Error writing data to secret/accounting/test: Error making API request.

URL: PUT https://127.0.0.1:8200/v1/secret/accounting/test
Code: 403. Errors:

* 2 errors occurred:
  * egp standard policy "root/cidr-check" evaluation resulted in denial.

The specific error was:
<nil>

A trace of the execution for policy "root/cidr-check" is available:

Result: false

Description: Check the precondition before execute the cidrcheck

Rule "main" (byte offset 442) = false
  false (offset 314): sockaddr.is_contained(request.connection.remote_addr, "122.22.3.4/32")

Rule "cidrcheck" (byte offset 291) = false

Rule "precond" (byte offset 113) = true
  true (offset 134): request.operation in ["create", "update", "delete"]
  true (offset 194): strings.has_prefix(request.path, "secret/")

  * permission denied

Error writing data to secret/accounting/test: Error making API request.

URL: PUT https://127.0.0.1:8200/v1/secret/accounting/test
Code: 403. Errors:

* 2 errors occurred:
  * egp standard policy "root/cidr-check" evaluation resulted in denial.

The specific error was:
<nil>

A trace of the execution for policy "root/cidr-check" is available:

Result: false

Description: Check the precondition before execute the cidrcheck

Rule "main" (byte offset 442) = false
  false (offset 314): sockaddr.is_contained(request.connection.remote_addr, "122.22.3.4/32")

Rule "cidrcheck" (byte offset 291) = false

Rule "precond" (byte offset 113) = true
  true (offset 134): request.operation in ["create", "update", "delete"]
  true (offset 194): strings.has_prefix(request.path, "secret/")

  * permission denied

Similarly, you will get an error if any request is made outside of the business hours defined by the business-hrs policy.

»Role Governing Policies (RGPs)

RGPs are tied to client tokens or identities which is similar to ACL policies. Vault server evaluates the RGP attached to the token to determine whether to accept or reject the request.

»Scenario introduction

To demonstrate the use of RGP, you are going to create the following:

• Create ACL policies: secrets and admin, and sysops
• Enable a userpass auth method at userpass-test/ and create a user james and bob
• Create an entity named James Thomas
• Create an entity named Bob Smith
• Create a RGP policy named test-rgp
• Create a group named sysops with James Thomas and Bob Smith entities as its members
  • Attach sysops and test-rgp policies to the group

The sysops group has the sysops policy attached which grants permission to manage all policies. All group members inherits the group-level policies. (If you are not familiar with Vault Identities, refer to the Identity: Entities and Groups tutorial.)

Use role governing policy to restrict access to the admin policy such that James or user with Team Lead role can manage the admin policy. Other group members can manage all other policies but not the admin policy.

»Create the demo resources

1. Clone the learn-vault-sentinel repository.

   $ git clone https://github.com/hashicorp-education/learn-vault-sentinel.git
   

   $ git clone https://github.com/hashicorp-education/learn-vault-sentinel.git
   

   Copy

2. Change the working directory to learn-vault-sentinel.

   $ cd learn-vault-sentinel.git
   

   $ cd learn-vault-sentinel.git
   

   Copy

3. Make sure that the identity-setup.sh file is executable.

   $ chmod +x identity-setup.sh
   

   $ chmod +x identity-setup.sh
   

   Copy
   identity-setup.sh

   vault policy write secrets -<<EOF
   path "secret/*" {
      capabilities = [ "create", "read", "update", "delete" ]
   }
   EOF
   
   vault policy write admin -<<EOF
   path "auth/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   EOF
   
   vault policy write sysops -<<EOF
   path "sys/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   EOF
   
   vault auth enable -path="userpass-test" userpass
   vault write auth/userpass-test/users/james password="training" policies="secrets"
   vault write auth/userpass-test/users/bob password="training" policies="secrets"
   vault auth list -format=json | jq -r '.["userpass-test/"].accessor' > accessor_test.txt
   
   # Create 'James Thomas' entity
   vault write -format=json identity/entity name="James Thomas" policies="admin" \
      metadata=role="Team Lead" \
      | jq -r ".data.id" > entity_id_james.txt
   
   vault write identity/entity-alias name="james" \
      canonical_id=$(cat entity_id_james.txt) \
      mount_accessor=$(cat accessor_test.txt) 
   
   # Create Bob Smith entity
   vault write -format=json identity/entity name="Bob Smith" policies="admin" \
      metadata=role="Kubernetes Expert" \
      | jq -r ".data.id" > entity_id_bob.txt
   
   vault write identity/entity-alias name="bob" \
      canonical_id=$(cat entity_id_bob.txt) \
      mount_accessor=$(cat accessor_test.txt) 
   
   # Add an RGP policy
   cat <<EOF | base64 | vault write sys/policies/rgp/test-rgp policy=- enforcement_level="hard-mandatory"
   import "strings"
   
   precond = rule {
      strings.has_prefix(request.path, "sys/policies/acl/admin")
   }
   
   main = rule when precond {
      identity.entity.metadata.role is "Team Lead" or 
         identity.entity.name is "James Thomas"
   }
   EOF
   
   # Create 'sysops' group 
   vault write -format=json identity/group name="sysops" \
      policies="sysops, test-rgp" \
      member_entity_ids="$(cat entity_id_james.txt), $(cat entity_id_bob.txt)" \
      | jq -r ".data.id" > group_id_sysops.txt
   

   1 2 3 4 5 6 7 8 9 101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960vault policy write secrets -<<EOF
   path "secret/*" {
      capabilities = [ "create", "read", "update", "delete" ]
   }
   EOF
   
   vault policy write admin -<<EOF
   path "auth/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   EOF
   
   vault policy write sysops -<<EOF
   path "sys/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   EOF
   
   vault auth enable -path="userpass-test" userpass
   vault write auth/userpass-test/users/james password="training" policies="secrets"
   vault write auth/userpass-test/users/bob password="training" policies="secrets"
   vault auth list -format=json | jq -r '.["userpass-test/"].accessor' > accessor_test.txt
   
   # Create 'James Thomas' entity
   vault write -format=json identity/entity name="James Thomas" policies="admin" \
      metadata=role="Team Lead" \
      | jq -r ".data.id" > entity_id_james.txt
   
   vault write identity/entity-alias name="james" \
      canonical_id=$(cat entity_id_james.txt) \
      mount_accessor=$(cat accessor_test.txt) 
   
   # Create Bob Smith entity
   vault write -format=json identity/entity name="Bob Smith" policies="admin" \
      metadata=role="Kubernetes Expert" \
      | jq -r ".data.id" > entity_id_bob.txt
   
   vault write identity/entity-alias name="bob" \
      canonical_id=$(cat entity_id_bob.txt) \
      mount_accessor=$(cat accessor_test.txt) 
   
   # Add an RGP policy
   cat <<EOF | base64 | vault write sys/policies/rgp/test-rgp policy=- enforcement_level="hard-mandatory"
   import "strings"
   
   precond = rule {
      strings.has_prefix(request.path, "sys/policies/acl/admin")
   }
   
   main = rule when precond {
      identity.entity.metadata.role is "Team Lead" or 
         identity.entity.name is "James Thomas"
   }
   EOF
   
   # Create 'sysops' group 
   vault write -format=json identity/group name="sysops" \
      policies="sysops, test-rgp" \
      member_entity_ids="$(cat entity_id_james.txt), $(cat entity_id_bob.txt)" \
      | jq -r ".data.id" > group_id_sysops.txt
   

   Copy

   Notice that the test-rgp RGP policy is attached to the sysops group (line 58).

4. Run the identity-setup.sh script.

   $ ./identity-setup.sh
   
   Success! Uploaded policy: secrets
   Success! Uploaded policy: admin
   Success! Uploaded policy: sysops
   Success! Enabled userpass auth method at: userpass-test/
   Success! Data written to: auth/userpass-test/users/james
   Success! Data written to: auth/userpass-test/users/bob
   Key             Value
   ---             -----
   canonical_id    07f6868e-8a87-5141-1828-93097f59f424
   id              55972826-f3c8-2601-3acf-6568273672e2
   Key             Value
   ---             -----
   canonical_id    73decd4f-ae4c-1dc1-a1a9-a74068ef42c4
   id              20e36023-c181-cbbf-f225-df9592797f56
   Success! Data written to: sys/policies/rgp/test-rgp
   

   $ ./identity-setup.sh
   
   Success! Uploaded policy: secrets
   Success! Uploaded policy: admin
   Success! Uploaded policy: sysops
   Success! Enabled userpass auth method at: userpass-test/
   Success! Data written to: auth/userpass-test/users/james
   Success! Data written to: auth/userpass-test/users/bob
   Key             Value
   ---             -----
   canonical_id    07f6868e-8a87-5141-1828-93097f59f424
   id              55972826-f3c8-2601-3acf-6568273672e2
   Key             Value
   ---             -----
   canonical_id    73decd4f-ae4c-1dc1-a1a9-a74068ef42c4
   id              20e36023-c181-cbbf-f225-df9592797f56
   Success! Data written to: sys/policies/rgp/test-rgp
   

   Copy

»Review the created identities and policies

1. Examine the test-rgp policy.

   $ vault policy read test-rgp 
   

   $ vault policy read test-rgp 
   

   Copy

   Output:

   import "strings"
   
   precond = rule {
      strings.has_prefix(request.path, "sys/policies/acl/admin")
   }
   
   main = rule when precond {
      identity.entity.metadata.role is "Team Lead" or
         identity.entity.name is "James Thomas"
   }
   

   test-rgp

   Copy

   import "strings"
   
   precond = rule {
      strings.has_prefix(request.path, "sys/policies/acl/admin")
   }
   
   main = rule when precond {
      identity.entity.metadata.role is "Team Lead" or
         identity.entity.name is "James Thomas"
   }
   

   The precond checks the incoming request endpoint. If the request is targeted to sys/policies/acl/admin, Vault checks to see if the request was made by an entity named, James Thomas or has Team Lead role defined as its metadata. Refer to the Entity Properties documentation for the list of available properties.

2. Review the James Thomas entity details. The entity ID is stored in the entity_id_james.txt file by the script.

   $ vault read identity/entity/id/$(cat entity_id_james.txt)
   

   $ vault read identity/entity/id/$(cat entity_id_james.txt)
   

   Copy

   Example output:

   James Thomas entity has Team Lead role defined in its metadata.

   Key                    Value
   ---                    -----
   aliases                [map[canonical_id:5e8cba9e-b663-97e9-5e1f-b68248e53534 creation_time:2022-09-14T01:34:53.174277Z custom_metadata:map[] id:857fedd9-038b-8c16-ddff-3b891336699b last_update_time:2022-09-14T01:34:53.174277Z local:false merged_from_canonical_ids:<nil> metadata:<nil> mount_accessor:auth_userpass_fb364660 mount_path:auth/userpass-test/ mount_type:userpass name:james]]
   creation_time          2022-09-14T01:34:53.081739Z
   direct_group_ids       [87d8a8df-cfac-f6be-0ee7-bcf227ab098b]
   disabled               false
   group_ids              [87d8a8df-cfac-f6be-0ee7-bcf227ab098b]
   id                     5e8cba9e-b663-97e9-5e1f-b68248e53534
   inherited_group_ids    []
   last_update_time       2022-09-14T01:34:53.081739Z
   merged_entity_ids      <nil>
   metadata               map[role:Team Lead]
   mfa_secrets            map[]
   name                   James Thomas
   namespace_id           root
   policies               [admin]
   

   Key                    Value
   ---                    -----
   aliases                [map[canonical_id:5e8cba9e-b663-97e9-5e1f-b68248e53534 creation_time:2022-09-14T01:34:53.174277Z custom_metadata:map[] id:857fedd9-038b-8c16-ddff-3b891336699b last_update_time:2022-09-14T01:34:53.174277Z local:false merged_from_canonical_ids:<nil> metadata:<nil> mount_accessor:auth_userpass_fb364660 mount_path:auth/userpass-test/ mount_type:userpass name:james]]
   creation_time          2022-09-14T01:34:53.081739Z
   direct_group_ids       [87d8a8df-cfac-f6be-0ee7-bcf227ab098b]
   disabled               false
   group_ids              [87d8a8df-cfac-f6be-0ee7-bcf227ab098b]
   id                     5e8cba9e-b663-97e9-5e1f-b68248e53534
   inherited_group_ids    []
   last_update_time       2022-09-14T01:34:53.081739Z
   merged_entity_ids      <nil>
   metadata               map[role:Team Lead]
   mfa_secrets            map[]
   name                   James Thomas
   namespace_id           root
   policies               [admin]
   

3. Review the Bob Smith entity details. The entity ID is stored in entity_id_bob.txt.

   $ vault read identity/entity/id/$(cat entity_id_bob.txt)
   

   $ vault read identity/entity/id/$(cat entity_id_bob.txt)
   

   Copy

   Example output:

   Bob's functional role is Kubernetes expert.

   Key                    Value
   ---                    -----
   aliases                [map[canonical_id:83e66ad6-e6ee-d6ed-8063-e88d90dd4de3 creation_time:2022-09-14T23:30:46.079077Z custom_metadata:map[] id:437cc7a4-2e6d-3b2b-0bd6-d0f57c8e3644 last_update_time:2022-09-14T23:30:46.079077Z local:false merged_from_canonical_ids:<nil> metadata:<nil> mount_accessor:auth_userpass_427c2404 mount_path:auth/userpass-test/ mount_type:userpass name:bob]]
   creation_time          2022-09-14T23:30:45.958557Z
   direct_group_ids       [2652cb82-c798-3a42-1fc7-9c4005190ec5]
   disabled               false
   group_ids              [2652cb82-c798-3a42-1fc7-9c4005190ec5]
   id                     83e66ad6-e6ee-d6ed-8063-e88d90dd4de3
   inherited_group_ids    []
   last_update_time       2022-09-14T23:30:45.958557Z
   merged_entity_ids      <nil>
   metadata               map[role:Kubernetes Expert]
   mfa_secrets            map[]
   name                   Bob Smith
   namespace_id           root
   policies               [admin]
   

   Key                    Value
   ---                    -----
   aliases                [map[canonical_id:83e66ad6-e6ee-d6ed-8063-e88d90dd4de3 creation_time:2022-09-14T23:30:46.079077Z custom_metadata:map[] id:437cc7a4-2e6d-3b2b-0bd6-d0f57c8e3644 last_update_time:2022-09-14T23:30:46.079077Z local:false merged_from_canonical_ids:<nil> metadata:<nil> mount_accessor:auth_userpass_427c2404 mount_path:auth/userpass-test/ mount_type:userpass name:bob]]
   creation_time          2022-09-14T23:30:45.958557Z
   direct_group_ids       [2652cb82-c798-3a42-1fc7-9c4005190ec5]
   disabled               false
   group_ids              [2652cb82-c798-3a42-1fc7-9c4005190ec5]
   id                     83e66ad6-e6ee-d6ed-8063-e88d90dd4de3
   inherited_group_ids    []
   last_update_time       2022-09-14T23:30:45.958557Z
   merged_entity_ids      <nil>
   metadata               map[role:Kubernetes Expert]
   mfa_secrets            map[]
   name                   Bob Smith
   namespace_id           root
   policies               [admin]
   

»Verification

1. Login as james and store the generated token in james_token.txt

   $ vault login -method=userpass -path=userpass-test -field=token \
      username=james password=training > james_token.txt
   

   $ vault login -method=userpass -path=userpass-test -field=token \
      username=james password=training > james_token.txt
   

   Copy

2. Read the admin policy.

   $ VAULT_TOKEN=$(cat james_token.txt) vault policy read admin
   
   path "auth/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   

   $ VAULT_TOKEN=$(cat james_token.txt) vault policy read admin
   
   path "auth/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   

   Copy

   The command successfully returns the policy.

3. Login as bob and store the generated token in bob_token.txt

   $ vault login -method=userpass -path=userpass-test -field=token \
      username=bob password=training > bob_token.txt
   

   $ vault login -method=userpass -path=userpass-test -field=token \
      username=bob password=training > bob_token.txt
   

   Copy

4. Try to read the admin policy.

   $ VAULT_TOKEN=$(cat bob_token.txt) vault policy read admin
   

   $ VAULT_TOKEN=$(cat bob_token.txt) vault policy read admin
   

   Copy

   Output:

   Error reading policy named admin: Error making API request.
   
   URL: GET http://127.0.0.1:8200/v1/sys/policies/acl/admin
   Code: 403. Errors:
   
   * 2 errors occurred:
      * rgp standard policy "root/test-rgp" evaluation resulted in denial.
   
   The specific error was:
   <nil>
   
   A trace of the execution for policy "root/test-rgp" is available:
   
   Result: false
   
   Description: <none>
   
   Rule "main" (root/test-rgp:7:1) = false
   Rule "precond" (root/test-rgp:3:1) = true
      * permission denied
   

   Error reading policy named admin: Error making API request.
   
   URL: GET http://127.0.0.1:8200/v1/sys/policies/acl/admin
   Code: 403. Errors:
   
   * 2 errors occurred:
      * rgp standard policy "root/test-rgp" evaluation resulted in denial.
   
   The specific error was:
   <nil>
   
   A trace of the execution for policy "root/test-rgp" is available:
   
   Result: false
   
   Description: <none>
   
   Rule "main" (root/test-rgp:7:1) = false
   Rule "precond" (root/test-rgp:3:1) = true
      * permission denied
   

   Neither the Bob's entity metadata or the name matched that the main rule returned false. Therefore, the request was denied.

5. Read the token details.

   $ VAULT_TOKEN=$(cat bob_token.txt) vault token lookup
   
   Key                            Value
   ---                            -----
   accessor                       NfBU02DcEAVSJACJUkVmpOnK
   creation_time                  1663124784
   creation_ttl                   768h
   display_name                   userpass-test-bob
   entity_id                      6090ff87-e3d8-09f1-b8d8-94ec9a7bb05b
   expire_time                    2022-10-15T20:06:24.77325-07:00
   explicit_max_ttl               0s
   external_namespace_policies    map[]
   id                             hvs.CAESIEZ4R6stpJNirlgggzY0SknVO9YkFbUZ8OoUsuV32tL7Gh4KHGh2cy5Bc2NYaXVOQzJVemJTRjFzU1U2d0c2bjA
   identity_policies              [admin sysops test-rgp]
   issue_time                     2022-09-13T20:06:24.773255-07:00
   meta                           map[username:bob]
   num_uses                       0
   orphan                         true
   path                           auth/userpass-test/login/bob
   policies                       [default secrets]
   renewable                      true
   ttl                            767h44m29s
   type                           service
   

   $ VAULT_TOKEN=$(cat bob_token.txt) vault token lookup
   
   Key                            Value
   ---                            -----
   accessor                       NfBU02DcEAVSJACJUkVmpOnK
   creation_time                  1663124784
   creation_ttl                   768h
   display_name                   userpass-test-bob
   entity_id                      6090ff87-e3d8-09f1-b8d8-94ec9a7bb05b
   expire_time                    2022-10-15T20:06:24.77325-07:00
   explicit_max_ttl               0s
   external_namespace_policies    map[]
   id                             hvs.CAESIEZ4R6stpJNirlgggzY0SknVO9YkFbUZ8OoUsuV32tL7Gh4KHGh2cy5Bc2NYaXVOQzJVemJTRjFzU1U2d0c2bjA
   identity_policies              [admin sysops test-rgp]
   issue_time                     2022-09-13T20:06:24.773255-07:00
   meta                           map[username:bob]
   num_uses                       0
   orphan                         true
   path                           auth/userpass-test/login/bob
   policies                       [default secrets]
   renewable                      true
   ttl                            767h44m29s
   type                           service
   

   Copy

   The token details shows admin, sysops and test-rgp policies listed as identity_policies. Although the sysops policy permits access to the sys/* path, the test-rgp does not permit to read the admin policy unless the entity's name is "James Thomas" or has "Team Lead" defined in the entity metadata.

6. To verify, read the sysops policy with Bob's token.

   $ VAULT_TOKEN=$(cat bob_token.txt) vault policy read sysops
   
   path "sys/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   

   $ VAULT_TOKEN=$(cat bob_token.txt) vault policy read sysops
   
   path "sys/*" {
      capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
   }
   

   Copy

   Bob can access other policies.

»Challenge question

What can you do to allow Bob Smith to access the admin policy?

$ vault write identity/entity/id/$(cat entity_id_bob.txt) metadata=role="Team Lead"

$ vault write identity/entity/id/$(cat entity_id_bob.txt) metadata=role="Team Lead"

import "strings"

precond = rule {
    strings.has_prefix(request.path, "sys/policies/acl/admin")
}

main = rule when precond {
    identity.entity.metadata.role is "Team Lead" or 
        identity.entity.name is "James Thomas" or
         identity.entity.name is "Bob Smith" 
}

import "strings"

precond = rule {
    strings.has_prefix(request.path, "sys/policies/acl/admin")
}

main = rule when precond {
    identity.entity.metadata.role is "Team Lead" or 
        identity.entity.name is "James Thomas" or
         identity.entity.name is "Bob Smith" 
}

$ VAULT_TOKEN=$(cat bob_token.txt) vault policy read admin

path "auth/*" {
   capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}

$ VAULT_TOKEN=$(cat bob_token.txt) vault policy read admin

path "auth/*" {
   capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}

»Clean up

If you wish to clean up your environment after completing the tutorial, follow the steps in this section.

1. Delete the business-hrs policy.

   $ vault policy delete business-hrs
   

   $ vault policy delete business-hrs
   

   Copy

2. Delete the cidr-check policy.

   $ vault policy delete cidr-check
   

   $ vault policy delete cidr-check
   

   Copy

3. Delete the Sentinel test directory.

   $ rm -r test
   

   $ rm -r test
   

   Copy

4. Unset the VAULT_TOKEN environment variable.

   $ unset VAULT_TOKEN
   

   $ unset VAULT_TOKEN
   

   Copy

5. Unset the VAULT_ADDR environment variable.

   $ unset VAULT_ADDR
   

   $ unset VAULT_ADDR
   

   Copy

6. If you completed the Role Governing Policies (RGPs) section, run the clean-up.sh script provided by the learn-vault-sentinel repository.

   $ ./clean-up.sh
   

   $ ./clean-up.sh
   

   Copy

7. If you are running Vault locally in -dev mode, you can stop the Vault dev server by pressing Ctrl+C where the server is running. Or, execute the following command.

   $ pgrep -f vault | xargs kill
   

   $ pgrep -f vault | xargs kill
   

   Copy

»Next steps

You learned the basics of endpoint governing policies (EGPs) and role governing policies (RGPs). To learn more about Sentinel policies in Vault, continue onto the following tutorials:

• Sentinel HTTP Import
• Sentinel Validation Policies

»Help and reference

• Your First Sentinel Policy
• Sentinel documentation
• Vault Sentinel documentation
• Security and Fundamentals at Scale with Vault
• Identity - Entities and Groups tutorial
• Sentinel Properties