server_orgs.md

+++ title = "RBAC: Organizations and Groups" draft = false gh_repo = "chef-server" aliases = ["/server_orgs.html", "/auth_authorization.html"] product = ["client", "server"]

[menu] [menu.server] title = "Organizations & Groups" identifier = "server/users/server_orgs.md Organizations & Groups" parent = "server/users" weight = 20 +++

{{< readfile file="content/server/reusable/md/server_rbac.md" >}}

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

Feature	Description
	An organization is the top-level entity for role-based access control in the Chef Infra Server. Each organization contains the default groups (admins, clients, and users, plus billing_admins for the hosted Chef Infra Server), at least one user and at least one node (on which the Chef Infra Client is installed). The Chef Infra Server supports multiple organizations. The Chef Infra Server includes a single default organization that is defined during setup. Additional organizations can be created after the initial setup and configuration of the Chef Infra Server.
	A group is used to define access to object types and objects in the Chef Infra Server and also to assign permissions that determine what types of tasks are available to members of that group who are authorized to perform them. Groups are configured per-organization. Individual users who are members of a group will inherit the permissions assigned to the group. The Chef Infra Server includes the following default groups: admins, clients, and users. For users of the hosted Chef Infra Server, an additional default group is provided: billing_admins.
	A user is any non-administrator human being who will manage data that is uploaded to the Chef Infra Server from a workstation or who will log on to the Chef management console web user interface. The Chef Infra Server includes a single default user that is defined during setup and is automatically assigned to the admins group.
	A client is an actor that has permission to access the Chef Infra Server. A client is most often a node (on which the Chef Infra Client runs), but is also a workstation (on which knife runs), or some other machine that is configured to use the Chef Infra Server API. Each request to the Chef Infra Server that is made by a client uses a private key for authentication that must be authorized by the public key on the Chef Infra Server.

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 per-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 prior to 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

{{< readfile file="content/server/reusable/md/server_rbac_permissions.md" >}}

Object Permissions

{{< readfile file="content/server/reusable/md/server_rbac_permissions_object.md" >}}

Global Permissions

The Chef Infra Server includes the following global permissions:

Permission	Description
Create	Use the Create global permission to define which users and groups may create the following server object types: cookbooks, data bags, environments, nodes, roles, and tags. This permission is required for any user who uses the knife [object] create argument to interact with objects on the Chef Infra Server.
List	Use the List global permission to define which users and groups may view the following server object types: cookbooks, data bags, environments, nodes, roles, and tags. This permission is required for any user who uses the knife [object] list argument to interact with objects on the Chef Infra Server.

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

{{< note >}}

This is only necessary after migrating a client from one Chef Infra Server to another. Permissions must be reset for client keys after the migration.

{{< /note >}}

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.

{{< readfile file="content/reusable/md/EOL_manage.md" >}}

knife-acl and the Chef Manage browser interface are incompatible. After engaging knife-acl, you will need to stop using the Chef Manage browser interface from that point forward because they are incompatible.

Groups

The Chef Infra Server includes the following default groups:

Group	Description
admins	The admins group defines the list of users who have administrative rights to all objects and object types for a single organization.
billing_admins	The billing_admins group defines the list of users who have permission to manage billing information. This permission exists only for the hosted Chef Infra Server.
clients	The clients group defines the list of nodes on which a Chef Infra Client is installed and under management by Chef. In general, think of this permission as "all of the non-human actors---Chef Infra Client, in nearly every case---that get data from, and/or upload data to, the Chef server". Newly-created Chef Infra Client instances are added to this group automatically.
public_key_read_access	The public_key_read_access group defines which users and clients have read permissions to key-related endpoints in the Chef Infra Server API.
users	The users group defines the list of users who use knife and the Chef management console to interact with objects and object types. In general, think of this permission as "all of the non-admin human actors who work with data that is uploaded to and/or downloaded from the Chef server".

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.

{{< note >}}

The creator of an object on the Chef Infra Server is assigned create, delete, grant, read, and update permission to that object.

{{< /note >}}

admins

The admins group is assigned the following:

Group	Create	Delete	Grant	Read	Update
admins	yes	yes	yes	yes	yes
clients	yes	yes	yes	yes	yes
users	yes	yes	yes	yes	yes

billing_admins

The billing_admins group is assigned the following:

billing_admins

The billing_admins group is assigned the following:

Group	Create	Delete	Read	Update
billing_admins	no	no	yes	yes

clients

The clients group is assigned the following:

Object	Create	Delete	Read	Update
clients	no	no	no	no
cookbooks	no	no	yes	no
cookbook_artifacts	no	no	yes	no
data	no	no	yes	no
environments	no	no	yes	no
nodes	yes	no	yes	no
organization	no	no	yes	no
policies	no	no	yes	no
policy_groups	no	no	yes	no
roles	no	no	yes	no
sandboxes	no	no	no	no

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:

Group	Create	Delete	Grant	Read	Update
admins	no	no	no	no	no
clients	yes	yes	yes	yes	yes
users	yes	yes	yes	yes	yes

users

The users group is assigned the following:

Object	Create	Delete	Read	Update
clients	no	yes	yes	no
cookbooks	yes	yes	yes	yes
cookbook_artifacts	yes	yes	yes	yes
data	yes	yes	yes	yes
environments	yes	yes	yes	yes
nodes	yes	yes	yes	yes
organization	no	no	yes	no
policies	yes	yes	yes	yes
policy_groups	yes	yes	yes	yes
roles	yes	yes	yes	yes
sandboxes	yes	no	no	no

chef-validator

{{< readfile file="content/reusable/md/security_chef_validator.md" >}}

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:

Object	Create	Delete	Read	Update
clients	yes	no	no	no

Server Admins

{{< readfile file="content/server/reusable/md/server_rbac_server_admins.md" >}}

Scenario

{{< readfile file="content/server/reusable/md/server_rbac_server_admins_scenario.md" >}}

Superuser Accounts

{{< readfile file="content/server/reusable/md/server_rbac_server_admins_superusers.md" >}}

Manage server-admins Group

{{< readfile file="content/server/reusable/md/ctl_chef_server_server_admin.md" >}}

Add Members

{{< readfile file="content/server/reusable/md/ctl_chef_server_server_admin_grant_user.md" >}}

Remove Members

{{< readfile file="content/server/reusable/md/ctl_chef_server_server_admin_remove_user.md" >}}

List Membership

{{< readfile file="content/server/reusable/md/ctl_chef_server_server_admin_list.md" >}}

Manage Organizations

{{< readfile file="content/server/reusable/md/ctl_chef_server_org.md" >}}

org-create

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_create.md" >}}

Syntax

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_create_syntax.md" >}}

Options

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_create_options.md" >}}

org-delete

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_delete.md" >}}

Syntax

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_delete_syntax.md" >}}

org-list

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_list.md" >}}

Syntax

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_list_syntax.md" >}}

Options

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_list_options.md" >}}

org-show

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_show.md" >}}

Syntax

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_show_syntax.md" >}}

org-user-add

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_user_add.md" >}}

Syntax

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_user_add_syntax.md" >}}

Options

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_user_add_options.md" >}}

org-user-remove

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_user_remove.md" >}}

Syntax

{{< readfile file="content/server/reusable/md/ctl_chef_server_org_user_remove_syntax.md" >}}