conjur-asset-policy 0.8.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d3f421be05da2eced0b95bfa1028a1a3e01695f
-  data.tar.gz: 73121a9f79529fae31f28c8f7ed08842b8481bd8
+  metadata.gz: 64cf9174fc3ed6a86366f2f46c052952c054440e
+  data.tar.gz: 1f02801a02ae8d60b28c78faa1d254872778d2ea
 SHA512:
-  metadata.gz: 857b7d9be7f6a76d6721b51c8a479fb78ad125efbbf76ade98d10671e6b7cfc561c4b39a5dc5466b0801a482aed09c2feab439cff839532565a89e7d56a2e7f7
-  data.tar.gz: 1208b5fefe05b10c7d7c7b212f76cbda8344eaaf141b9c3d62181720db172a8056bc18f15b8122b8a7cdbbdd7ec4532afac6faa63678dc5387d52a479c04e7f8
+  metadata.gz: 1744445bfee08b4c08f0dc5bbde0931d744559659a348e4158e1863b571b1a699f37c8292942e8171d5156076a07558f59abccf7fd3516dbeed00695a99b5e8d
+  data.tar.gz: 29dede5e8aaab32f3fd7ecf4915908da281b15b3896984c388252cd332ba8cc1dad16e45dd8711bd535de8343d11f5c9f722296b5e0721753537c9626302850a

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 0.11.0
+
+* Enable management of user public keys.
+* Properly escape resource ids with spaces in them.
+
+# 0.10.0
+
+* Granting a layer to a host also gives permissions to the layer managed roles.
+* Revoking a layer from a host also revokes permissions from the layer managed roles.
+
+# 0.9.0
+
+* Rename `!managed-role` to `!automatic-role`, while maintaining backwards compatibility.
+
 # 0.8.3
 
 * When re-loading a policy, properly apply `--as-group` and `--as-role` by changing the ownership of top-level records as needed.

data/Gemfile

@@ -7,3 +7,4 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'simplecov', require: false
+gem 'conjur-asset-authn-local', git: 'https://github.com/conjurinc/conjur-asset-authn-local.git', branch: 'master'

data/ci/test.sh

@@ -8,6 +8,7 @@ cd /src/conjur-asset-policy
 bundle
 
 export CONJUR_AUTHN_LOGIN=admin
-export CONJUR_AUTHN_API_KEY=secret
+
+ruby -ryaml -e "conf = YAML.load(File.read('/etc/conjur.conf')); conf['plugins'] = [ 'policy', 'authn-local' ]; File.write('/etc/conjur.conf', YAML.dump(conf))"
 
 bundle exec rake jenkins || true

data/lib/conjur-asset-policy-version.rb

@@ -1,7 +1,7 @@
 module Conjur
   module Asset
     module Policy
-      VERSION = "0.8.3"
+      VERSION = "0.11.0"
     end
   end
 end

data/lib/conjur-asset-policy.rb

@@ -14,6 +14,7 @@ end
 require 'rest-client'
 
 require 'conjur/api/patches/role'
+require 'conjur/api/patches/user'
 
 require 'conjur/policy/logger'
 require 'conjur/policy/invalid'

data/lib/conjur/api/patches/user.rb

@@ -0,0 +1,9 @@
+require 'conjur/api'
+
+class Conjur::User
+  # The attribute synchronization expects a +public_keys+ method on the User, so add one.
+  # The expected form is a list, so split the raw pubkeys result on newlines.
+  def public_keys
+    conjur_api.public_keys(login).split("\n")
+  end
+end

data/lib/conjur/command/policy.rb

@@ -54,7 +54,7 @@ class Conjur::Command::Policy < Conjur::DSLCommand
     actions = []
     records.each do |record|
       executor_class = Conjur::Policy::Executor.class_for(record)
-      executor = executor_class.new(record, actions)
+      executor = executor_class.new(api, record, actions)
       executor.execute
     end
     Conjur::Policy::HTTPExecutor.new(api).execute actions
@@ -155,7 +155,21 @@ command. Therefore, a policy can be loaded in three steps, if desired:
         end
 
         records = Conjur::Policy::Resolver.resolve(records, Conjur.configuration.account, ownerid, options[:namespace])
-        plan = Conjur::Policy::Planner.plan(records, api)
+        plan_api = if api.privilege == "elevate"
+          # Check if the user has 'reveal'
+          # In order to do this, the 'elevate' privilege must be removed, otherwise the permission
+          # check always returns 'true'
+          naked_api = api.dup
+          naked_api.privilege = nil
+          if naked_api.global_privilege_permitted?("reveal")
+            api.with_privilege("reveal")
+          else
+            api
+          end
+        else
+          api
+        end
+        plan = Conjur::Policy::Planner.plan(records, plan_api)
 
         if options[:"dry-run"]
           case options[:"format"]

data/lib/conjur/policy/executor.rb

@@ -28,8 +28,15 @@ module Conjur
               Conjur::Policy::Executor::CreateRecord
             end
           else
-            class_name = action.class.name.split("::")[-1]
-            Conjur::Policy::Executor.const_get(class_name)
+            action_name = action.class.name.split("::")[-1]
+            if action.respond_to?(:record)
+              type_name = action.record.class.short_name
+            end
+            begin
+              Conjur::Policy::Executor.const_get([ action_name, type_name ].compact.join)
+            rescue NameError
+              Conjur::Policy::Executor.const_get(action_name)
+            end
           end
         end
       end
@@ -66,7 +73,7 @@ module Conjur
       
       def create path, parameters
         request = Net::HTTP::Post.new [ @base_path, path ].join('/')
-        request.set_form_data to_params(parameters)
+        set_request_body request, parameters
         send_request request
       end
 
@@ -74,7 +81,7 @@ module Conjur
       
       def update path, parameters
         request = Net::HTTP::Put.new [ @base_path, path ].join('/')
-        request.set_form_data to_params(parameters)
+        set_request_body request, parameters
         send_request request
       end
       
@@ -82,7 +89,9 @@ module Conjur
       
       def delete path, parameters
         uri = URI.parse([ @base_path, path ].join('/'))
-        uri.query = [uri.query, parameters.to_query].compact.join('&') 
+        unless parameters.blank?
+          uri.query = [uri.query, parameters.to_query(nil)].compact.join('&') 
+        end
         request = Net::HTTP::Delete.new [ uri.path, '?', uri.query ].join
           
         send_request request
@@ -114,9 +123,17 @@ module Conjur
         # empty
       end
       
+      def set_request_body request, params
+        if params.is_a?(String)
+          request.body = params
+        else
+          request.set_form_data to_params(params)
+        end
+      end
+      
       # Convert parameter keys to rails []-style keys
       def to_params params
-        params.inject({}) do |memo,entry|
+        Array(params).inject({}) do |memo,entry|
           key, value = entry
           if value.is_a?(Array)
             key = "#{key}[]"

data/lib/conjur/policy/executor/base.rb

@@ -1,14 +1,18 @@
 module Conjur::Policy
   module Executor
+    require 'conjur/escape'
+    
     # Builds a list of execution actions for a statement. The statement
     # is an object from Conjur::Policy::Types. Each execution action is
     # an HTTP method, a request path, and request parameters.
     class Base
       include Conjur::Policy::Logger
+      include Conjur::Escape
       
-      attr_reader :statement, :actions
+      attr_reader :api, :statement, :actions
       
-      def initialize statement, actions
+      def initialize api, statement, actions
+        @api = api
         @statement = statement
         @actions = actions
       end
@@ -23,12 +27,12 @@ module Conjur::Policy
       
       def resource_path record = nil
         record ||= self.statement
-        [ "authz", record.account, "resources", record.resource_kind, record.id ].join('/')
+        [ "authz", record.account, "resources", record.resource_kind, path_escape(record.id) ].join('/')
       end
 
       def role_path record = nil
         record ||= self.statement
-        [ "authz", record.account, "roles", record.role_kind, record.id ].join('/')
+        [ "authz", record.account, "roles", record.role_kind, path_escape(record.id) ].join('/')
       end
     end
     
@@ -47,7 +51,17 @@ module Conjur::Policy
         [ "authz", annotate_record.account,
             "annotations",
             annotate_record.resource_kind,
-            CGI.escape(annotate_record.id) ].join('/')
+            path_escape(annotate_record.id) ].join('/')
+      end
+    end
+    
+    module PublicKeys
+      def public_key_path
+        [ "pubkeys", CGI.escape(record.id) ].join('/')
+      end
+      
+      def attribute_names
+        super - [ :public_key ]
       end
     end
   end

data/lib/conjur/policy/executor/create.rb

@@ -38,7 +38,7 @@ module Conjur::Policy::Executor
       {
         record.id_attribute => record.id
       }.tap do |params|
-        custom_attrs = record.custom_attribute_names.inject({}) do |memo, attr|
+        custom_attrs = attribute_names.inject({}) do |memo, attr|
           value = record.send(attr)
           memo[attr.to_s] = value if value
           memo
@@ -47,6 +47,28 @@ module Conjur::Policy::Executor
         params["ownerid"] = record.owner.roleid if record.owner
       end
     end
+    
+    def attribute_names
+      record.custom_attribute_names
+    end
+  end
+  
+  # Sync the user's public keys using the Pubkeys service. POSTing the 
+  # public keys to the User service won't have any effect.
+  class CreateUser < CreateRecord
+    include PublicKeys
+    
+    def execute
+      super
+      
+      Array(record.public_keys).each do |key|
+        action({
+          'method' => 'post',
+          'path' => public_key_path,
+          'parameters' => key
+        })
+      end
+    end
   end
 
   # When creating a host factory, the +roleid+ and +layer+ are required.

data/lib/conjur/policy/executor/grant.rb

@@ -1,6 +1,23 @@
 module Conjur::Policy::Executor
   class Grant < Base
     def execute
+      if statement.role.is_a?(Conjur::Policy::Types::Layer) && statement.member.role.is_a?(Conjur::Policy::Types::Host)
+        add_host_to_layer
+      else
+        grant_role_to_member
+      end
+    end
+    
+    def add_host_to_layer
+      parameters = { "hostid" => statement.member.role.roleid }
+      action({
+        'method' => 'post',
+        'path' => "layers/#{fully_escape statement.role.id}/hosts",
+        'parameters' => parameters
+      })
+    end
+    
+    def grant_role_to_member
       parameters = { "member" => statement.member.role.roleid }
       parameters['admin_option'] = statement.member.admin unless statement.member.admin.nil?
       action({
@@ -10,4 +27,4 @@ module Conjur::Policy::Executor
       })
     end
   end
-end
+end

data/lib/conjur/policy/executor/revoke.rb

@@ -1,6 +1,22 @@
 module Conjur::Policy::Executor
   class Revoke < Base
     def execute
+      if statement.role.is_a?(Conjur::Policy::Types::Layer) && statement.member.is_a?(Conjur::Policy::Types::Host)
+        remove_host_from_layer
+      else
+        revoke_role_from_member
+      end
+    end
+    
+    def remove_host_from_layer
+      action({
+        'method' => 'delete',
+        'path' => "layers/#{fully_escape statement.role.id}/hosts/#{fully_escape statement.member.roleid}",
+        'parameters' => {}
+      })
+    end
+    
+    def revoke_role_from_member
       action({
         'method' => 'delete',
         'path' => "#{role_path(statement.role)}?members",

data/lib/conjur/policy/executor/update.rb

@@ -3,29 +3,70 @@ module Conjur::Policy::Executor
     include Annotate
     
     def execute
-      statement.record.custom_attribute_names.each do |attr|
-        value = statement.record.send(attr)
-        action({ 
-          'method' => 'put',
-          'path' => update_path,
-          'parameters' => { attr.to_s => value }
-        })
+      attribute_names.each do |attr|
+        value = record.send(attr)
+        if value
+          action({ 
+            'method' => 'put',
+            'path' => update_path,
+            'parameters' => { attr.to_s => value }
+          })
+        end
       end
       
       annotate
     end
 
     def kind_path
-      statement.record.resource_kind.pluralize
+      record.resource_kind.pluralize
     end
     
     def update_path
-      require 'cgi'
-      [ kind_path, CGI.escape(statement.record.id) ].join('/')
+      [ kind_path, fully_escape(statement.record.id) ].join('/')
     end
     
     def annotate_record
+      record
+    end
+    
+    def record
       statement.record
     end
+
+    def attribute_names
+      record.custom_attribute_names
+    end
+  end
+  
+  class UpdateUser < Update
+    include PublicKeys
+    
+    def execute
+      super
+
+      if record.public_keys
+        (Array(record.public_keys) - user.public_keys).each do |key|
+          action({
+            'method' => 'post',
+            'path' => public_key_path,
+            'parameters' => key
+          })
+        end
+        (user.public_keys - Array(record.public_keys)).each do |key|
+          action({
+            'method' => 'delete',
+            'path' => [ public_key_path, CGI.escape(key_name(key)) ].join('/')
+          })
+        end
+      end
+    end
+    
+    def user
+      api.user record.id
+    end
+
+    def key_name key
+      key.split(' ')[-1]
+    end
   end
 end

data/lib/conjur/policy/logger.rb

@@ -6,7 +6,7 @@ module Conjur::Policy::Logger
       
       require 'logger'
       self.logger = Logger.new(STDERR)
-      self.logger.level = Logger::INFO
+      self.logger.level = (ENV['DEBUG'] == "true" ? Logger::DEBUG : Logger::INFO)
     end
   end
 end

data/lib/conjur/policy/planner.rb

@@ -19,7 +19,7 @@ module Conjur
               ensure
                 planner.plan = nil
               end
-            end        
+            end
           end
         end
         

data/lib/conjur/policy/planner/base.rb

@@ -22,34 +22,13 @@ module Conjur
         end
         
         def role_record fullid
-          account, kind, id = fullid.split(':', 3)
-          if kind == '@'
-            Conjur::Policy::Types::ManagedRole.build fullid
-          else
-            if record_class = record_type(kind)
-              record_class.new.tap do |record|
-                record.account = account
-                unless record.is_a?(Conjur::Policy::Types::Variable)
-                  record.kind = kind if record.respond_to?(:kind=)
-                end
-                record.id = id
-              end
-            else
-              Conjur::Policy::Types::Role.new(fullid)
-            end
-          end
+          detect_record fullid, Conjur::Policy::Types::Role
         end
         
-        def record_type kind
-          begin
-            Conjur::Policy::Types.const_get(kind.classify)
-          rescue NameError
-            nil
-          end
+        def resource_record fullid
+          detect_record fullid, Conjur::Policy::Types::Resource
         end
-        
-        alias resource_record role_record
-        
+
         def resource
           api.resource(record.resourceid)
         end
@@ -158,7 +137,7 @@ module Conjur
         
         def create_record
           log { "Creating #{record}" }
-
+            
           create = Conjur::Policy::Types::Create.new
           create.record = record
           
@@ -179,6 +158,36 @@ module Conjur
           plan.resources_created.add(record.resourceid) if record.resource?
           action create
         end
+        
+        protected
+        
+        def detect_record fullid, raw_type
+          account, kind, id = fullid.split(':', 3)
+          if kind == '@'
+            Conjur::Policy::Types::AutomaticRole.build fullid
+          else
+            if record_class = record_type(kind, raw_type)
+              record_class.new.tap do |record|
+                record.account = account
+                unless record.is_a?(Conjur::Policy::Types::Variable)
+                  record.kind = kind if record.respond_to?(:kind=)
+                end
+                record.id = id
+              end
+            else
+              Conjur::Policy::Types::Role.new(fullid)
+            end
+          end
+        end
+        
+        def record_type kind, raw_type
+          return raw_type if kind == '!'
+          begin
+            Conjur::Policy::Types.const_get(kind.classify)
+          rescue NameError
+            nil
+          end
+        end
       end
     end
   end

data/lib/conjur/policy/planner/facts.rb

@@ -121,7 +121,13 @@ module Conjur
         # Each permission is yielded to the block.
         def resource_permissions resource, privileges, &block
           permissions = begin
-            JSON.parse(api.resource(resource.resourceid).get)['permissions'] 
+            resource = JSON.parse(api.resource(resource.resourceid).get)
+            # Malformed resource ids can be interpreted as a resource search
+            if resource.is_a?(Array)
+              []
+            else 
+              resource['permissions']
+            end
           rescue RestClient::ResourceNotFound
             if api.resource(resource.resourceid).exists?
               $stderr.puts "WARNING: Unable to fetch permissions of resource #{resource.resourceid}. Use 'elevate' mode, or at least 'reveal' mode, for policy management."

data/lib/conjur/policy/resolver.rb

@@ -85,7 +85,7 @@ module Conjur
             id = id[1..-1]
           else
             if record.respond_to?(:resource_kind) && record.resource_kind == "user"
-              id = [ id, namespace ].compact.join('@')
+              id = [ id, user_namespace ].compact.join('@')
             else
               id = [ namespace, id ].compact.join('/')
             end
@@ -109,6 +109,10 @@ module Conjur
       
       protected
       
+      def user_namespace
+        namespace.gsub('/', '-') if namespace
+      end
+      
       def substitute! id
         SUBSTITUTIONS.each do |k,v|
           next unless value = send(v)

data/lib/conjur/policy/types/base.rb

@@ -400,9 +400,9 @@ module Conjur
         end
       end
       
-      module ManagedRoleDSL
-        def managed_role record, role_name
-          ManagedRole.new(record, role_name)
+      module AutomaticRoleDSL
+        def automatic_role record, role_name
+          AutomaticRole.new(record, role_name)
         end
       end
     end

data/lib/conjur/policy/types/create.rb

@@ -8,7 +8,11 @@ Create a record of any type.
 A record can be a [Role](#reference/role) or a [Resource](#reference/resource).
 
 Creating records can be done explicitly using this node type, or
-implicitly. Examples of both are given immeditely below.
+implicitly. Examples of both are given immediately below.
+    
+When a record is created explicitly, it's an error if the record already exists.
+When a record is created implicitly, the record will be found-or-created, and its
+state (owner, fields and annotations) will be updated to match the policy declaration.
 )
 
     self.example = %(

data/lib/conjur/policy/types/deny.rb

@@ -2,8 +2,13 @@ module Conjur::Policy::Types
   class Deny < Base
 
     self.description = %(
-Deny privileges on a [Resource](#reference/resource). (compare:
-[Revoke](#reference/revoke) for [Roles](#reference/role))
+Deny privilege(s) on a [Resource](#reference/resource) to a role.
+Once a privilege is denied, permission checks performed by the role
+will return `false`.
+
+If the role does not hold the privilege, this statement is a nop.
+
+See also: [Revoke](#reference/revoke) for [Roles](#reference/role)
 )
 
     self.example = %(

data/lib/conjur/policy/types/give.rb

@@ -5,7 +5,9 @@ module Conjur::Policy::Types
 
     self.description = %(
 Give ownership of a resource to a [Role](#reference/role).
-(compare: [Grant](#reference/grant))
+    
+When the owner role performs a permission check on an owned resource, the
+result is always `true`.
 
 [More](/key_concepts/rbac.html) on role-based access control in Conjur.
 )

data/lib/conjur/policy/types/grant.rb

@@ -5,13 +5,37 @@ module Conjur::Policy::Types
     attribute :replace, kind: :boolean, singular: true, dsl_accessor: true
 
     include RoleMemberDSL
-    include ManagedRoleDSL
+    include AutomaticRoleDSL
 
     self.description = %(
-Grant one [Role](#reference/role) to another.
-(compare: [Give](#reference/give) for [Resources](#reference/resource))
+Grant one [Role](#reference/role) to another. When role A is granted to role B, 
+then role B is said to "have" role A. The set of all memberships of role B
+will include A. The set of direct members of role A will include role B.
+    
+If the role is granted with `admin` option, then the grantee (role B),
+in addition to having the role, can also grant and revoke the role
+to other roles.
+
+The only limitation on role grants is that there may never be a cycle 
+in the role graph. For example, if role A is granted to role B, then role B
+cannot be granted to role A.
+
+Several types of Conjur records are roles. For example, Users, Groups,
+Hosts and Layers are all roles. This means they can be granted to and 
+revoked from each other. For example, when a Group is granted to a User, 
+the User gains all the privileges of the Group. (Note: "Adding" a User to 
+a Group is just another way to say that the Group role is granted to the User).
+
+Some `grant` operations have additional semantics beyond the role grant:
+    
+* When a Layer is granted to a Host, the automatic roles on the Layer are granted
+    privileges on the Host. Specifically, the `observe` role is given `read` privilege,
+    `use_host` is given `execute`, and `admin_host` is given `update`. The `admin`
+    option is ignored.
 
 [More](/key_concepts/rbac.html) on role-based access control in Conjur.
+    
+See also: [Permit](#reference/permit) for [Resources](#reference/resource)
 )
 
     self.example = %(

data/lib/conjur/policy/types/member.rb

@@ -9,6 +9,11 @@ module Conjur::Policy::Types
 
     self.description = %(
 Designate the members of a [Role](#reference/role) such as a [Group](#reference/group).
+    
+The member indicates the "grantee" (which role will gain the role grant), as well as the
+`admin` option which determines whether the grantee can grant/revoke the role to other roles.
+
+The default value for `admin` is `false`.
 )
 
     self.example = %(

data/lib/conjur/policy/types/permit.rb

@@ -8,14 +8,23 @@ module Conjur
         attribute :replace, kind: :boolean, singular: true, dsl_accessor: true
 
         self.description = %(
-Give permissions on a [Resource](#reference/resource) to a [Role](#reference/role). (contrast: [Deny](#reference/deny))
+Give permissions on a [Resource](#reference/resource) to a [Role](#reference/role). 
 
-The permissions are:
-1. read (see the resource)
-2. execute (use the resource)
-3. update (make changes to the resource)
+Once a privilege is given, permission checks performed by the role
+will return `true`.
 
+Note that permissions are not "inherited" in the same way that roles are.
+If role A is granted to role B, then role B "inherits" all the privileges held 
+by role A. If role A can `execute` a variable, then role B can as well.
+The privileges on each resource are distinct, regardless of how they are named.
+If role A has `execute` privilege on a resource called `dev`, the role does **not**
+gain any privileges on a resource called `dev/password`. Role-based access control
+is explicit in this way to avoid unintendend side-effects from the way that 
+resources are named.
+        
 [More](/key_concepts/rbac.html) on role-based access control in Conjur.
+        
+See also: [Deny](#reference/deny)
 )
 
         self.example = %(

data/lib/conjur/policy/types/policy.rb

@@ -92,23 +92,43 @@ module Conjur
         include ActsAsRole
 
         self.description = %(
-Create a versioned policy.
+Create a policy. A policy is composed of the following:
+        
+* **id** A unique id, which can be prefixed by a `namespace`.
+* **body** A set of records such as variables, groups and layers which are "owned" by the policy.
+        
+Under the hood, a Policy is actually a role *and* a resource.
+The role is a role whose kind is "policy", and it has the specified `id`. By default
+the policy role is granted, with `admin` option, to the `--as-group` or `--as-role` option which is specified
+when the policy is loaded. The policy resource is a resource whose kind is "policy", and
+whose owner is the policy role.
+        
+All the records declared in the `body` of the policy are also owned by the policy role
+by default. As a result, the role specified by `--as-group` or `--as-role` has full
+ownership and management of everything defined in the policy.
+
+Policies should be self-contained; they should not generally make any reference to 
+records from outside the policy. This way, the policy can be loaded with different
+`--as-group`, `--as-role`, and `--namespace` options to serve different functions in the workflow.
+For example, if a policy is loaded into the `dev` namespace with `--as-group dev-admin`, 
+then a "dev" version of the policy is created with full management assigned to the `dev-admin` group.
 
 [See above](#example) for an example of a complete policy.
 )
 
         self.example = %(
-- !user operator
-
 - !policy
     id: example/v1
-    owner: !user operator
     body:
-    - !variable secret
+    - &secrets
+      - !variable secret
+        
+    - !layer
+        
     - !grant
-        role: !user operator
-        permissions: [ read, execute, update ]
-        resource: !variable secret
+        role: !layer
+        permissions: [ read, execute ]
+        resources: *secrets
 )
 
         def role

data/lib/conjur/policy/types/records.rb

@@ -115,23 +115,26 @@ module Conjur
         attribute :owner, kind: :role, singular: true, dsl_accessor: true
 
         self.description = %(
-Create a custom role.
-
-From our [role-based access control guide](/key_concepts/rbac.html):
-
-> The purpose of a role is to have privileges and to initiate
-> transactions.
-> 
-> A role may represent a person, a group, a non-human user (“robot”)
-> such as a virtual machine or process, or a group of other roles.
-> 
-> In addition to having privileges, a role can be granted to another
-> role.
-> 
-> When a role is granted, the receiving role gains all the privileges
-> of the granted role. In addition, it gains all the roles which are
-> held by the granted role; role grants are fully inherited.
+Create a custom role. 
 
+The purpose of a role is to have privileges and to initiate
+transactions.
+
+A role may represent a person, a group, a non-human user (“robot”)
+such as a virtual machine or process, or a group of other roles.
+
+In addition to having privileges, a role can be granted to another
+role.
+
+When a role is granted, the receiving role gains all the privileges
+of the granted role. In addition, it gains all the roles which are
+held by the granted role; role grants are fully inherited.
+        
+Typically, roles are not defined directly.
+Rather, records that behave as roles, such as Users, Groups,
+Hosts and Layers are used instead.
+
+See also: [role-based access control guide](/key_concepts/rbac.html)
 )
 
         self.example = %(
@@ -164,22 +167,23 @@ From our [role-based access control guide](/key_concepts/rbac.html):
         self.description = %(
 Create a custom Resource.
 
-From our [role-based access control guide](/key_concepts/rbac.html):
+Resources are the entities on which permissions are defined. A
+resource id is an arbitrary, unique string which identifies the
+protected asset.
 
-> Resources are the entities on which permissions are defined. A
-> resource id is an arbitrary, unique string which identifies the
-> protected asset.
-> 
-> Examples: database password, virtual machine or
-> server (for SSH access management), web service endpoint
+Examples: database password, virtual machine or
+server (for SSH access management), web service endpoint
 
-From our [CLI reference](/cli#annotating-resources):
+Any Conjur resource can be annotated with a key-value pair. This
+makes organization and discovery easier since annotations can be
+searched on and are shown in the Conjur UI. Automation workflows
+like rotation and expiration are based on annotations.
 
-> Any Conjur resource can be annotated with a key-value pair. This
-  makes organization and discovery easier since annotations can be
-  searched on and are shown in the Conjur UI. Automation workflows
-  like rotation and expiration are based on annotations.
+Typically, resources are not defined directly.
+Rather, records that behave as resources, such as Users, Groups,
+Hosts, Layers, Variables and Webservices are used instead.
 
+See also: [role-based access control guide](/key_concepts/rbac.html)
 )
 
         self.example = %(
@@ -203,25 +207,38 @@ From our [CLI reference](/cli#annotating-resources):
         include ActsAsRole
         
         self.description = %(
-Create a [Role](#reference/role) representing a human user. (For virtual machines, scripts, and other infrastructure, [Host](#reference/host) is a more appropriate role.)
+Create a [Role](#reference/role) representing a human user. 
+
+Users have several specific attributes:
 
-See also: [Users](/reference/services/directory/user) in our service reference.
+* **uidnumber** An integer which is the user's uid number for SSH access to Hosts. The `uidnumber` must
+  be unique across the Conjur system.
+* **public_keys** Stores public keys for the user, which can be retrieved through the 
+  [PubKeys API](http://docs.conjur.apiary.io/#reference/pubkeys/show/show-keys-for-a-user).
+  Public keys loaded through the Policy markup are strictly additive. To remove public keys, use the
+  API or the CLI.
+
+For virtual machines, scripts, and other infrastructure, create [Host](#reference/host) identities instead.
 )
 
         self.example = %(
 - !user robert
     uidnumber: 1208
+    public_keys:
+    - ssh-rsa AAAAB3NzaC1yc2EAAAAD...+10trhK5Pt robert@home
+    - ssh-rsa AAAAB3NzaC1yc2EAAAAD...+10trhK5Pt robert@work
     annotations:
       public: true
       can_predict_movement: false
 )
-        
+
         attribute :uidnumber, kind: :integer, singular: true, dsl_accessor: true
-        
+        attribute :public_key, kind: :string, dsl_accessor: true
+
         def id_attribute; 'login'; end
         
         def custom_attribute_names
-          [ :uidnumber ]
+          [ :uidnumber, :public_key ]
         end
       end
       
@@ -234,21 +251,17 @@ See also: [Users](/reference/services/directory/user) in our service reference.
         self.description = %(
 Create a Group record.
 
-From our [CLI reference](/cli#users-groups):
-
-> Users are organized into groups in Conjur. Every user other than
-  'admin' should be in a group. When a user becomes a member of a
-  group they inherit the group's privileges. You can delegate members
-  of the group to be admins. This means that they can add and remove
-  other members of the group. The owner of a group is automatically an
-  admin.
-
-See also: [User](#reference/user) type, [Groups](/reference/services/directory/group) in our service reference.
+Users are organized into groups in Conjur. Every user other than
+'admin' should be in a group. When a user becomes a member of a
+group they inherit the group's privileges. You can delegate members
+of the group to be admins. This means that they can add and remove
+other members of the group. The owner of a group is automatically an
+admin.
 )
 
         self.example = %(
-- !user sysop
-- !user db-admin
+- !user alice
+- !user bob
 
 - !group ops
     gidnumber: 110
@@ -256,9 +269,9 @@ See also: [User](#reference/user) type, [Groups](/reference/services/directory/g
 - !grant
     role: !group ops
     members:
-    - !user sysop
+    - !user alice
     - !member
-        role: !user db-admin
+        role: !user bob
         admin: true
 )
         def custom_attribute_names
@@ -271,9 +284,13 @@ See also: [User](#reference/user) type, [Groups](/reference/services/directory/g
         include ActsAsRole
 
         self.description = %(
-Create a Host record and resource.
-
-See also: [Layer](#reference/layer) type, [machine identity](/key_concepts/machine_identity.html), [Host](/reference/services/directory/host) in our service reference.
+Create a Host record.
+        
+A Host is an identity which represents a machine or code; for example, a 
+Server, VM, job or container.
+        
+Hosts can be long-lasting, and managed through the Conjur host factory, or 
+ephemeral, and managed through Conjur oAuth (aka authn-tv).
 )
 
         self.example = %(
@@ -294,15 +311,11 @@ See also: [Layer](#reference/layer) type, [machine identity](/key_concepts/machi
         self.description = %(
 Create a Layer record.
 
-From our [CLI reference](/cli#hosts-layers):
-
-> Host are organized into layers in Conjur. Hosts can be added and
-  removed from layers, and map logically to your infrastructure. A
-  host can be a single machine, but it could also be an application or
-  Docker container - where several different applications are running
-  on the same machine or VM.
-
-See also: [Host](#reference/host) type, [Layers](/reference/services/directory/layer) in our service reference.
+Host are organized into layers in Conjur. Hosts can be added and
+removed from layers, and map logically to your infrastructure. A
+host can be a single machine, but it could also be an application or
+Docker container - where several different applications are running
+on the same machine or VM.
 )
 
         self.example = %(
@@ -310,10 +323,10 @@ See also: [Host](#reference/host) type, [Layers](/reference/services/directory/l
 - !host AM
 - !host GLaDOS
 
-- !layer bad_hosts
+- !layer evil-hosts
 
 - !grant
-    role: !layer bad_hosts
+    role: !layer evil-hosts
     members:
       - !host ProteusIV
       - !host AM
@@ -330,19 +343,15 @@ See also: [Host](#reference/host) type, [Layers](/reference/services/directory/l
         self.description = %(
 Create a Variable resource to hold a secret value.
 
-From our [CLI reference](/cli#variables):
-
-> Variables are containers for secrets in Conjur. They can hold any
-> value. You can annotate resources and also assign them a kind, a
-> signifier as to what type of value they hold. Variable values are
-> versioned and assigning a value during variable creation is
-> optional. When fetching a value, the latest version is returned by
-> default.
-> 
-> Variables are resources; you assign roles privileges to them as
-> desired.
+Variables are containers for secrets in Conjur. They can hold any
+ascii-armored value. You can annotate resources and also assign them a kind, a
+signifier as to what type of value they hold. Variable values are
+versioned and assigning a value during variable creation is
+optional. When fetching a value, the latest version is returned by
+default.
 
-See also: [Variables](https://developer.conjur.net/reference/services/directory/variable) in the service reference.
+Variables are resources; you assign roles privileges to them as
+desired.
 )
 
         self.example = %(
@@ -366,18 +375,15 @@ See also: [Variables](https://developer.conjur.net/reference/services/directory/
         self.description = %(
 Create a [Resource](#reference/resource) representing a web service endpoint.
 
-From our [role-based access control guide](/key_concepts/rbac.html):
-
-> Web services endpoints are represented in Conjur as a webservice
-> resource. Permission grants are pretty straightforward: an input
-> HTTP request path is mapped to a webservice resource. The HTTP
-> method is mapped to an RBAC privilege. A permission check is
-> performed, according to the following transaction:
-> 
-> * `role` incoming role on the HTTP request
-> * `privilege` read, update, or delete according to HTTP verb
-> * `resource` web service resource id
+Web services endpoints are represented in Conjur as a webservice
+resource. Permission grants are straightforward: an input
+HTTP request path is mapped to a webservice resource. The HTTP
+method is mapped to an RBAC privilege. A permission check is
+performed, according to the following transaction:
 
+* `role` incoming role on the HTTP (typically, Conjur access token on the request Authorization header)
+* `privilege` read, update, or delete according to HTTP verb
+* `resource` web service resource id
 )
 
         self.example = %(
@@ -397,9 +403,8 @@ From our [role-based access control guide](/key_concepts/rbac.html):
         include ActsAsResource
 
         self.description = %(
-Create a host-factory service for bootstrapping [Hosts](#reference/host) into a [Layer](#reference/layer).
-
-See also: [Host Factory](/reference/services/host_factory) in our service reference.
+Create a host-factory service for automatically creating [Hosts](#reference/host) 
+and enrolling them into one or more [Layer](#reference/layer)s.
 )
 
         self.example = %(
@@ -425,7 +430,7 @@ See also: [Host Factory](/reference/services/host_factory) in our service refere
         end
       end
       
-      class ManagedRole < Base
+      class AutomaticRole < Base
         include ActsAsRole
         
         def initialize record = nil, role_name = nil
@@ -437,13 +442,16 @@ See also: [Host Factory](/reference/services/host_factory) in our service refere
         attribute :role_name, kind: :string, singular: true
 
         self.description = %(
-Some [Roles](#reference/role) are created automatically. For historical reasons, these are given the type `managed-role`.
+Some [Roles](#reference/role) are created automatically by a containing record. 
+        
+These roles are accessed by using the `automatic-role`
+type, which identifies the containing record (e.g. a Layer), and the name of the automatic role (e.g. `use_host`).
 
-These roles are:
+The automatic roles of a Layer are:
 
-* `use_host`, for allowing SSH access
-* `admin_host`, for allowing admin (root) login.
-* `observe`
+* `use_host`, for allowing SSH access to each host as the `users` primary group.
+* `admin_host`, for allowing SSH access to each host as the `conjurers` primary group.
+* `observe`, for `read` privileges on the hosts.
 )
 
         self.example = %(
@@ -452,22 +460,22 @@ These roles are:
 - !group line-cooks
 - !layer kitchen
 
-# no need to create MangedRoles; they are automatic.
+# There's no need to create automatic roles explicitly
 
 - !grant
-    role: !managed-role
+    role: !automatic-role
       record: !layer kitchen
       role_name: use_host
     member: !group line-cooks
 
 - !grant
-    role: !managed-role
+    role: !automatic-role
       record: !layer kitchen
       role_name: admin_host
     member: !user chef
 
 - !grant
-    role: !managed-role
+    role: !automatic-role
       record: !layer kitchen
       role_name: observe
     member: !user owner

data/lib/conjur/policy/types/retire.rb

@@ -7,21 +7,19 @@ module Conjur
         self.description = %(
 Move a Role or Resource to the attic.
 
-From our [CLI reference](/cli#retiring):
+When you no longer need a role or resource in Conjur, you `retire` it.
+This is different than deleting it. When you retire an item, all of
+its memberships and privileges are revoked and its ownership is
+transferred to the `attic` user. This is a special user in Conjur that
+is created when you first bootstrap your Conjur endpoint. By
+retiring rather than deleting items, the integrity of the immutable
+audit log is preserved.
 
-> When you no longer need a role or resource in Conjur, you `retire` it.
-> This is different than deleting it. When you retire an item, all of
-> its memberships and privileges are revoked and its ownership is
-> transferred to the `attic` user. This is a special user in Conjur that
-> is created when you first bootstrap your Conjur endpoint. By
-> retiring rather than deleting items, the integrity of the immutable
-> audit log is preserved.
-> 
-> You can unretire items by logging in as the
-> 'attic' user and transferring their ownership to another role. The
-> 'attic' user's API key is stored as a variable in Conjur at
-> `conjur/users/attic/api-key`. It is owned by the 'security_admin'
-> group. )
+You can unretire items by logging in as the
+'attic' user and transferring their ownership to another role. The
+'attic' user's API key is stored as a variable in Conjur at
+`conjur/users/attic/api-key`. It is owned by the 'security_admin'
+group. )
 
         self.example = %(
 - !retire

data/lib/conjur/policy/types/revoke.rb

@@ -8,6 +8,12 @@ module Conjur
         self.description = %(
 Remove a [Role](#reference/role) grant. (contrast: [Grant](#reference/grant))
 
+Some `revoke` operations have additional semantics beyond the role revocation:
+        
+* When a Layer is revoked from a Host, the automatic roles on the Layer are denied their
+    privileges on the Host. Specifically, the `observe` role is denied `read` privilege,
+    `use_host` is denied `execute`, and `admin_host` is denied `update`.
+
 See also: [role-based access control guide](/key_concepts/rbac.html).
 )
 

data/lib/conjur/policy/types/update.rb

@@ -3,9 +3,12 @@ module Conjur::Policy::Types
     attribute :record
 
     self.description = %(
-Make changes to an existing record's attributes.
+Make explicit changes to an existing record's attributes and/or annotations.
 
-For example, you can change annotations on a [Resource](#reference/resource), the `uidnumber` of a [User](#reference/user), etc.
+For example, you can change annotations on a [Resource](#reference/resource), or the `uidnumber` of a [User](#reference/user).
+    
+Generally, Update is not used explicitly. Instead, an update is performed by the create-or-replace behavior of
+statements such as User, Group, Host, Layer, etc.
 )
 
     self.example = %(

data/lib/conjur/policy/yaml/handler.rb

@@ -350,6 +350,7 @@ module Conjur
         def start_mapping *args
           log {"#{indent}start mapping #{args}"}
           anchor, tag, _ = args
+          tag = "!automatic-role" if %w(!managed-role !managed_role).include?(tag)
           value = handler.start_mapping tag
           anchor anchor, value
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: conjur-asset-policy
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.11.0
 platform: ruby
 authors:
 - Kevin Gilpin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-22 00:00:00.000000000 Z
+date: 2016-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: safe_yaml
@@ -189,6 +189,7 @@ files:
 - lib/conjur-asset-policy-version.rb
 - lib/conjur-asset-policy.rb
 - lib/conjur/api/patches/role.rb
+- lib/conjur/api/patches/user.rb
 - lib/conjur/command/policy.rb
 - lib/conjur/policy/doc.rb
 - lib/conjur/policy/executor.rb