Organizations and Groups

The Chef Infra Server uses role-based access control (RBAC) to restrict access to objects—nodes, environments, roles, data bags, cookbooks, and so on. This ensures that only authorized user and/or Chef Infra Client requests to the Chef Infra Server are allowed. Access to objects on the Chef Infra Server is fine-grained, allowing access to be defined by object type, object, group, user, and organization. The Chef Infra Server uses permissions to define how a user may interact with an object, after they have been authorized to do so.

The Chef Infra Server uses organizations, groups, and users to define role-based access control:

When a user makes a request to the Chef Infra Server using the Chef Infra Server API, permission to perform that action is determined by the following process:

1. Check if the user has permission to the object type
2. If no, recursively check if the user is a member of a security group that has permission to that object
3. If yes, allow the user to perform the action

Permissions are managed using the Chef management console add-on in the Chef Infra Server web user interface.

Organizations

A single instance of the Chef Infra Server can support many organizations. Each organization has a unique set of groups and users. Each organization manages a unique set of nodes, on which a Chef Infra Client is installed and configured so that it may interact with a single organization on the Chef Infra Server.

A user may belong to multiple organizations under the following conditions:

• Role-based access control is configured for each organization
• For a single user to interact with the Chef Infra Server using knife from the same chef-repo, that user may need to edit their config.rb file before that interaction

Using multiple organizations within the Chef Infra Server ensures that the same toolset, coding patterns and practices, physical hardware, and product support effort is being applied across the entire company, even when:

• Multiple product groups must be supported—each product group can have its own security requirements, schedule, and goals
• Updates occur on different schedules—the nodes in one organization are managed completely independently from the nodes in another
• Individual teams have competing needs for object and object types—data bags, environments, roles, and cookbooks are unique to each organization, even if they share the same name

Permissions

Permissions are used in the Chef Infra Server to define how users and groups can interact with objects on the server. Permissions are configured for each organization.

Object Permissions

The Chef Infra Server includes the following object permissions:

Global Permissions

The Chef Infra Server includes the following global permissions:

These permissions set the default permissions for the following Chef Infra Server object types: clients, cookbooks, data bags, environments, groups, nodes, roles, and sandboxes.

Client Key Permissions

Keys should have DELETE, GRANT, READ and UPDATE permissions.

Use the following code to set the correct permissions:

#!/usr/bin/env ruby
require 'chef/knife'

#previously knife.rb
Chef::Config.from_file(File.join(Chef::Knife.chef_config_dir, 'knife.rb'))

rest = Chef::ServerAPI.new(Chef::Config[:chef_server_url])

Chef::Node.list.each do |node|
  %w(read update delete grant).each do |perm|
    ace = rest.get("nodes/#{node[0]}/_acl")[perm]
    ace['actors'] << node[0] unless ace['actors'].include?(node[0])
    rest.put("nodes/#{node[0]}/_acl/#{perm}", perm => ace)
    puts "Client \"#{node[0]}\" granted \"#{perm}\" access on node \"#{node[0]}\""
  end
end

Save it as a Ruby script—chef_server_permissions.rb, for example—in the .chef/scripts directory located in the chef-repo, and then run a knife command similar to:

knife exec chef_server_permissions.rb

Knife ACL

The knife plugin knife-acl provides a fine-grained approach to modifying permissions, by wrapping API calls to the _acl endpoint and makes such permission changes easier to manage.

knife-acl and the Chef Manage browser interface are incompatible. After engaging knife-acl, you will need to discontinue using the Chef Manage browser interface from that point forward due to possible incompatibilities.

Groups

The Chef Infra Server includes the following default groups:

Example Default Permissions

The following sections show the default permissions assigned by the Chef Infra Server to the admins, billing_admins, clients, and users groups.

admins

The admins group is assigned the following:

billing_admins

The billing_admins group is assigned the following:

billing_admins

The billing_admins group is assigned the following:

clients

The clients group is assigned the following:

public_key_read_access

The public_key_read_access group controls which users and clients have read permissions to the following endpoints:

• GET /clients/CLIENT/keys
• GET /clients/CLIENT/keys/KEY
• GET /users/USER/keys
• GET /users/USER/keys/

By default, the public_key_read_access assigns all members of the users and clients group permission to these endpoints:

users

The users group is assigned the following:

users

The users group is assigned the following:

chef-validator

The chef-validator is allowed to do the following at the start of a Chef Infra Client run. After the Chef Infra Client is registered with Chef Infra Server, that Chef Infra Client is added to the clients group:

Server Admins

The server-admins group is a global group that grants its members permission to create, read, update, and delete user accounts, with the exception of superuser accounts. The server-admins group is useful for users who are responsible for day-to-day administration of the Chef Infra Server, especially user management using the knife user subcommand. Before members can be added to the server-admins group, they must already have a user account on the Chef Infra Server.

Scenario

The following user accounts exist on the Chef Infra Server: pivotal (a superuser account), alice, bob, carol, and dan. Run the following command to view a list of users on the Chef Infra Server:

chef-server-ctl user-list

and it returns the same list of users:

pivotal
alice
bob
carol
dan

Alice is a member of the IT team whose responsibilities include day-to-day administration of the Chef Infra Server, in particular managing the user accounts on the Chef Infra Server that are used by the rest of the organization. From a workstation, Alice runs the following command:

knife user list -c ~/.chef/alice.rb

and it returns the following error:

ERROR: You authenticated successfully to <chef_server_url> as alice
       but you are not authorized for this action
Response: Missing read permission

Alice is not a superuser and does not have permissions on other users because user accounts are global to organizations in the Chef Infra Server. Let’s add Alice to the server-admins group:

chef-server-ctl grant-server-admin-permissions alice

and it returns the following response:

User alice was added to server-admins.

Alice can now create, read, update, and delete user accounts on the Chef Infra Server, even for organizations to which Alice is not a member. From a workstation, Alice re-runs the following command:

knife user list -c ~/.chef/alice.rb

which now returns:

pivotal
alice
bob
carol
dan

Alice is now a server administrator and can use the following knife subcommands to manage users on the Chef Infra Server:

• knife user-create
• knife user-delete
• knife user-edit
• knife user-list
• knife user-show

For example, Alice runs the following command:

knife user edit carol -c ~/.chef/alice.rb

and the $EDITOR opens in which Alice makes changes, and then saves them.

Superuser Accounts

Superuser accounts may not be managed by users who belong to the server-admins group. For example, Alice attempts to delete the pivotal superuser account:

knife user delete pivotal -c ~/.chef/alice.rb

and the following error is returned:

ERROR: You authenticated successfully to <chef_server_url> as user1
       but you are not authorized for this action
Response: Missing read permission

Alice’s action is unauthorized even with membership in the server-admins group.

Manage server-admins Group

Membership of the server-admins group is managed with a set of chef-server-ctl subcommands:

• chef-server-ctl grant-server-admin-permissions
• chef-server-ctl list-server-admins
• chef-server-ctl remove-server-admin-permissions

Add Members

The grant-server-admin-permissions subcommand is used to add a user to the server-admins group. Run the command once for each user added.

This subcommand has the following syntax:

chef-server-ctl grant-server-admin-permissions USER_NAME

where USER_NAME is the user to add to the list of server administrators.

For example:

chef-server-ctl grant-server-admin-permissions bob

returns:

User bob was added to server-admins. This user can now list,
read, and create users (even for orgs they are not members of)
for this Chef Infra Server.

Remove Members

The remove-server-admin-permissions subcommand is used to remove a user from the server-admins group. Run the command once for each user removed.

This subcommand has the following syntax:

chef-server-ctl remove-server-admin-permissions USER_NAME

where USER_NAME is the user to remove from the list of server administrators.

For example:

chef-server-ctl remove-server-admin-permissions bob

returns:

User bob was removed from server-admins. This user can no longer
list, read, and create users for this Chef Infra Server except for where
they have default permissions (such as within an org).

List Membership

The list-server-admins subcommand is used to return a list of users who are members of the server-admins group.

This subcommand has the following syntax:

chef-server-ctl list-server-admins

and will return a list of users similar to:

pivotal
alice
bob
carol
dan

Manage Organizations

Use the org-create, org-delete, org-list, org-show, org-user-add and org-user-remove commands to manage organizations.

org-create

The org-create subcommand is used to create an organization. (The validation key for the organization is returned to STDOUT when creating an organization with this command.)

Syntax

This subcommand has the following syntax:

chef-server-ctl org-create ORG_NAME "ORG_FULL_NAME" (options)

where:

• The name must begin with a lower-case letter or digit, may only contain lower-case letters, digits, hyphens, and underscores, and must be between 1 and 255 characters. For example: chef.
• The full name must begin with a non-white space character and must be between 1 and 1023 characters. For example: "Chef Software, Inc.".

Options

This subcommand has the following options:

-a USER_NAME, --association_user USER_NAME

Associate a user with an organization and add them to the admins and billing_admins security groups.

-f FILE_NAME, --filename FILE_NAME

Write the ORGANIZATION-validator.pem to FILE_NAME instead of printing it to STDOUT.

org-delete

The org-delete subcommand is used to delete an organization.

Syntax

This subcommand has the following syntax:

chef-server-ctl org-delete ORG_NAME

org-list

The org-list subcommand is used to list all of the organizations currently present on the Chef Infra Server.

Syntax

This subcommand has the following syntax:

chef-server-ctl org-list (options)

Options

This subcommand has the following options:

-a, --all-orgs

Show all organizations.

-w, --with-uri

Show the corresponding URIs.

org-show

The org-show subcommand is used to show the details for an organization.

Syntax

This subcommand has the following syntax:

chef-server-ctl org-show ORG_NAME

org-user-add

The org-user-add subcommand is used to add a user to an organization.

Syntax

This subcommand has the following syntax:

chef-server-ctl org-user-add ORG_NAME USER_NAME (options)

Options

This subcommand has the following options:

--admin

Add the user to the admins group.

org-user-remove

The org-user-remove subcommand is used to remove a user from an organization.

Syntax

This subcommand has the following syntax:

chef-server-ctl org-user-remove ORG_NAME USER_NAME (options)