knife ACL

Description

This is an Opscode supported knife plugin which provides some user/group ACL operations for Enterprise Chef. All commands assume a working knife configuration for an organization on Enterprise Chef.

User Specific Association Group

User Specific Association Groups (USAGs) are a mechanism to grant access to organization objects to users such that it is possible to quickly revoke the access without touching all objects in the organization.

Each USAG contains a single user. The USAG is then added to other groups or directly to the ACLs of an object as needed.

When the user is dissociated from an organization only the user's USAG needs to be deleted thereby quickly revoking access to all objects in the organization.

USAGs and their membership within other normal groups are not visible in the current management console's web interface.

STOP managing group membership with the web interface

USAGs are currently the correct way to add/remove users to/from groups in an organization.

Be warned, once you start managing a group's membership using knife-acl you should avoid managing that group's membership using the management console's web interface.

You can add USAGs to a group using knife-acl but if you click "Save Group" in the web interface then all USAGs will be removed from the group erasing any knife-acl work that was done on the group. This will happen even if no changes were made to the group's members in the web interface.

The "Users" group is a special group. When a user is associated with an organization the user's USAG is automatically made a member of the "Users" group. You can remove USAGs from the "Users" group using knife-acl but if you click "Save Group" in the web interface then all USAGs in the organization will be added back to the "Users" group erasing any knife-acl work that was done on the "Users" group. This will happen even if no changes were made to the group's members in the web interface.

Example: Manage a read-only Group

You can use these commands to manage a read-only group. To do so:

Run knife actor map to create/update a local actor map file actor-map.yaml:
```
knife actor map
```
Create a group that will hold read-only users:
```
knife group create read-only
```
For each user you wish to have read only access as defined by permissions given to the "read-only" group do the following:
```
knife group add actor read-only USER
knife group remove actor users USER
```

This adds the user to the 'read-only' group and removes them from the 'users' group which has more permissions by default (users are added to 'users' when added to an org).

Installation

This knife plugin is packaged as a gem. To install it, enter the following:

Gem installed chef-client on a workstation

gem install knife-acl

Opscode hosted Enterprise Chef (OHC) with an Omnibus-installed chef-client on a workstation

/opt/chef/embedded/bin/gem install knife-acl

Opscode Enterprise Chef (OPC) Directly on the active backend

as root: /opt/opscode/embedded/bin/gem install knife-acl

Subcommands

knife user list

Show a list of users associated with your org

knife actor map

Create a local map file actor-map.yaml" that maps users to their USAG and stores a list of clients.

This command creates a local cache of the user to USAG mapping as well as a local cache of clients and is used by the following commands:

knife group show,
knife group add actor, and
knife group remove actor.

knife group create

Create a new group.

knife group list

List groups in the org.

knife group show GROUP

Show the details membership details for GROUP. If you have run knife actor map, the user map file will be used to annotate USAGs so you can see what user they represent.

knife group add actor GROUP ACTOR

Add ACTOR to GROUP. ACTOR can be a user name or a client name. Requires an up-to-date actor map as created by knife actor map. The user's USAG will be added as a subgroup of GROUP if ACTOR is a user.

knife group remove actor GROUP ACTOR

Remove ACTOR from GROUP. Requires an up-to-date actor map as created by knife actor map. The user's USAG will be removed from the subgroups of GROUP if ACTOR is a user.

knife group destroy GROUP

Removes GROUP from the organization. All members of the group (both actors and groups) remain in the system, only GROUP is removed.

knife acl show OBJECT_TYPE OBJECT_NAME

Shows the ACL for the specified object. Objects are identified by the combination of their type and name.

Valid OBJECT_TYPE's are

clients
groups
containers
data
nodes
roles
cookbooks
environments

For example, use the following command to obtain the ACL for a node named "web.example.com":

knife acl show nodes web.example.com

knife acl add OBJECT_TYPE OBJECT_NAME PERM [group|client] NAME

Add the group or client with NAME to the PERM access control entry of the object. Objects are specified by the combination of their type and name. See the knife acl show documentation above for the permitted types.

Valid PERMs are:

create
read
update
delete
grant

For example, use the following command to give the superuser group the ability to delete the node called "api.example.com":

knife acl add node api.exmaple.com delete group superusers

knife acl remove OBJECT_TYPE OBJECT_NAME PERM [group|client] NAME

Remove group or client with NAME from the PERM access control entry of the specified object. Objects are specified by the combination of their type and name. See the knife acl show documentation above for the permitted types. See the knife acl add documentation abouve for the permitted PERMSs.

For example, use the following command to remove the superuser group's ability to delete the node called "api.example.com":

knife acl remove node api.exmaple.com delete group superusers

TODO

Feature: build group membership graph
Remove duplication in commands
Staleness detector for actor map
Improve error messages when actor map is missing
Don't save group if it will be a no-op

LICENSE

Unless otherwise specified all works in this repository are


Author	Seth Falcon ([email protected])
Copyright	Copyright (c) 2013--2014 Chef Software, Inc.
License	Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Apache 2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.