diff --git a/doc/authorization.rst b/doc/authorization.rst index 20b8d99ce29..8f3aa0f337c 100644 --- a/doc/authorization.rst +++ b/doc/authorization.rst @@ -1,242 +1,114 @@ -========================== -Set and Manage Permissions -========================== +============= +Authorization +============= -CKAN implements a fine-grained role-based access control system. +.. versionchanged:: 2.0 + Previous versions of CKAN used a different authorization system. -This section describes: +CKAN's authorization system controls which users are allowed to carry out which +actions on the site. All actions that users can carry out on a CKAN site are +controlled by the authorization system. For example, the authorization system +controls who can register new user accounts, delete user accounts, or create, +edit and delete datasets, groups and organizations. -* :ref:`permissions-overview`. An overview of the concepts underlying CKAN authorization: objects, actions and roles. -* :ref:`permissions-default`. The default permissions in CKAN. -* :ref:`permissions-manage`. Managing and setting permissions. -* :ref:`permissions-publisher-mode`. Suitable for systems where you want to limit write access to CKAN. +Authorization in CKAN can be controlled in three ways: -.. _permissions-overview: +1. Organizations +2. Configuration file options +3. Extensions -Overview --------- +The following sections explain each of the three methods in turn. -In a nutshell: for a particular **object** (e.g. a dataset) a CKAN **user** can be assigned a **role** (e.g. editor) which allows permitted **actions** (e.g. read, edit). +.. note:: -In more detail, these concepts are as follows: + An **organization admin** in CKAN is an administrator of a particular + organization within the site, with control over that organization and its + members and datasets. A **sysadmin** is an administrator of the site itself. + Sysadmins can always do everything, including adding, editing and deleting + datasets, organizations and groups, regardless of the organization roles and + configuration options described below. -* There are **objects** to which access can be controlled, such as datasets and groups. -* For each object there are a set of relevant **actions**, such as create and edit, which users can perform on the object. -* To simplify mapping users to actions and objects, actions are aggregated into a set of **roles**. For example, an editor role would automatically have edit and read actions. -* Finally, CKAN has registered **users**. +Organizations +------------- -Recent support for authorization profiles has been implemented using a publisher/group based profile that is described in :doc:`publisher-profile`. -Objects -+++++++ +Organizations are the primary way to control who can see, create and update +datasets in CKAN. Each dataset can belong to a single organization, and each +organization controls access to its datasets. -Permissions are controlled per object: access can be controlled for an individual -dataset, group or authorization group instance. Current objects include -**datasets**, dataset **groups**, **authorization groups** and the **system**. +Datasets can be marked as public or private. Public datasets are visible to +everyone. Private datasets can only be seen by logged-in users who are members +of the dataset's organization. Private datasets are not shown in general +dataset searches but are shown in dataset searches within the organization. -* A dataset is the basic CKAN concept of metadata about a dataset. -* A group of datasets can be set up to specify which users have permission to add or remove datasets from the group. -* Users can be assigned to authorization groups, to increase flexibility. Instead of specifying the privileges of specific users on a dataset or group, you can also specify a set of users that share the same rights. To do that, an authorization group can be set up and users can be added to it. Authorization groups are both the object of authorization (i.e. one can have several roles with regards to an authorization group, such as being allowed to read or edit it) and the subject of authorization (i.e. they can be assigned roles on other objects which will apply to their members, such as the group having edit rights on a particular group). -* Finally, the system object is special, serving as an object for assignments that do not relate to a specific object. For example, creating a dataset cannot be linked to a specific dataset instance, and is therefore a operation. +When a user joins an organization, an organization admin gives them one of +three roles: member, editor or admin. +An organization **admin** can: -Actions -+++++++ +* View the organization's private datasets +* Add new datasets to the organization +* Edit or delete any of the organization's datasets +* Make datasets public or private. +* Add users to the organization, and choose whether to make the new user a + member, editor or admin +* Change the role of any user in the organization, including other admin users +* Remove members, editors or other admins from the organization +* Edit the organization itself (for example: change the organization's title, + description or image) +* Delete the organization -**Actions** are defined in the Action enumeration in ``ckan/model/authz.py`` and currently include: **edit**, **change-state**, **read**, **purge**, **edit-permissions**, **create-dataset**, **create-group**, **create-authorization-group**, **read-site**, **read-user**, **create-user**. +An **editor** can: -As noted above, some of these (e.g. **read**) have meaning for any type of object, while some (e.g. **create-dataset**) can not be associated with any particular object, and are therefore only associated with the system object. +* View the organization's private datasets +* Add new datasets to the organization +* Edit or delete any of the organization's datasets -The **read-site** action (associated with the system object) allows or denies access to pages not associated with specific objects. These currently include: +A **member** can: - * Dataset search - * Group index - * Tags index - * Authorization Group index - * All requests to the API (on top of any other authorization requirements) +* View the organization's private datasets. -There are also some shortcuts that are provided directly by the authorization -system (rather than being expressed as subject-object-role tuples): - * A user given the **admin** right for the **system** object is a 'sysadmin' and can perform any action on any object. (A shortcut for creating a sysadmin is by using the ``paster sysadmin`` command.) - * A user given the **admin** right for a particular object can perform any action on that object. +Configuration File Options +-------------------------- -Roles -+++++ +The following configuration file options can be used to customize CKAN's +authorization behavior: -Each **role** has a list of permitted actions appropriate for a protected object. +``ckan.auth.anon_create_dataset`` + Allow users to create datasets without registering and logging in, + default: false. -Currently there are four basic roles: +``ckan.auth.create_unowned_dataset`` + Allow the creation of datasets not owned by any organization, default: true. - * **reader**: can read the object - * **anon_editor**: anonymous users (i.e. not logged in) can edit and read the object - * **editor**: can edit, read and create new objects - * **admin**: admin can do anything including: edit, read, delete, - update-permissions (change authorizations for that object) +``ckan.auth.create_dataset_if_not_in_organization`` + Allow users who are not members of any organization to create datasets, + default: true. ``create_unowned_dataset`` must also be true, otherwise + setting ``create_dataset_if_not_in_organization`` to true is meaningless. -You can add other roles if these defaults are not sufficient for your system. +``ckan.auth.user_create_groups`` + Allow users to create groups, default: true. -.. warning:: If the broad idea of these basic roles and their actions is not suitable for your CKAN system, we suggest you create new roles, rather than edit the basic roles. If the definition of a role changes but its name does not, it is likely to confuse administrators and cause problems for CKAN upgrades and extensions. +``ckan.auth.user_create_organizations`` + Allow users to create organizations, default: true. -.. note:: When you install a new CKAN extension, or upgrade your version of CKAN, new actions may be created, and permissions given to these basic roles, in line with the broad intention of the roles. +``ckan.auth.user_delete_groups`` + Allow users to delete groups, default: true. -Users -+++++ +``ckan.auth.user_delete_organizations`` + Allow users to delete organizations, default: true. -You can manage CKAN users via the command line with the ``paster user`` command - for more information, see :ref:`paster-user`. +``ckan.auth.create_user_via_api`` + Allow new user accounts to be created via the API, default: false. -There are two special *pseudo-users* in CKAN, **visitor** and **logged-in**. These are used to refer to special sets of users, respectively those who are a) not logged-in ("visitor") and b) logged-in ("logged-in"). -The ``default_roles`` config option in the CKAN config file lets you set the default authorization roles (i.e. permissions) for these two types of users. For more information, see :doc:`configuration`. +Extensions +---------- +CKAN allows extensions to change the authorization rules used. Please see +individual extensions for details. -.. _permissions-default: +.. todo:: -Default Permissions -------------------- - -CKAN ships with the following default permissions: - -* When a new dataset is created, its creator automatically becomes **admin** for it. This user can then change permissions for other users. -* By default, any other user (including both visitors and logged-ins) can read and write to this dataset. - -These defaults can be changed in the CKAN config - see ``default_roles`` in :doc:`configuration`. - - -.. _permissions-manage: - -Managing Permissions --------------------- - -The assignment of users and authorization groups to roles on a given -protected object (such as a dataset) can be done by 'admins' via the -'authorization' tab of the web interface (or by sysadmins via that -interface or the system admin interface). - -There is also a command-line authorization manager, detailed below. - -Command-line authorization management -+++++++++++++++++++++++++++++++++++++ - -Although the admin extension provides a Web interface for managing authorization, -there is a set of more powerful ``paster`` commands for fine-grained control -(see :doc:`paster`). - -The ``rights`` command is used to configure the authorization roles of -a specific user on a given object within the system. - -For example, to list all assigned rights in the system (which you can then grep if needed):: - - paster --plugin=ckan rights -c my.ini list - -The ``rights make`` command lets you assign specific permissions. For example, to give the user named **bar** the **admin** role on the dataset foo:: - - paster --plugin=ckan rights -c my.ini make bar admin dataset:foo - -As well as users and datasets, you can assign rights to other objects. These -include authorization groups, dataset groups and the system as a whole. - -For example, to make the user 'chef' a system-wide admin:: - - paster --plugin=ckan rights -c my.ini make chef admin system - -Or to allow all members of authorization group 'foo' to edit group 'bar':: - - paster --plugin=ckan rights -c my.ini make agroup:foo edit \ - group:bar - -To revoke one of the roles assigned using ``rights make``, the ``rights remove`` command -is available. For example, to remove **bar**'s **admin** role on the foo dataset:: - - paster --plugin=ckan rights -c my.ini remove bar admin dataset:foo - -The ``roles`` command lists and modifies the assignment of actions to -roles. - -To list all role assignments:: - - paster --plugin=ckan roles -c my.ini list - -To remove the 'create-package' action from the 'editor' role:: - - paster --plugin=ckan roles -c my.ini deny editor create-package - -And to re-assign 'create-package' to the 'editor' role:: - - paster --plugin=ckan roles -c my.ini allow editor create-package - -For more help on either of these commands, you can use ``--help`` (as described in :ref:`paster-help`):: - - paster --plugin=ckan roles --help - paster --plugin=ckan rights --help - - -.. _permissions-publisher-mode: - -Openness Modes --------------- - -CKAN instances can be configured to operate in a range of authorization modes, with varying openness to edit. Here are some examples with details of how to set-up and convert between them. - - -1. Anonymous Edit Mode -++++++++++++++++++++++ - -Anyone can edit and create datasets without logging in. This is the default for CKAN out of the box. - - - - -2. Logged-in Edit Mode -++++++++++++++++++++++ - -You need to log-in and create/edit datasets. Anyone can create an account. - -To operate in this mode: - -1. First, change the visitor (any non-logged in user) rights from being able to create and edit datasets to just reading them:: - - paster rights make visitor reader system - paster rights make visitor reader package:all - paster rights remove visitor anon_editor package:all - paster rights remove visitor anon_editor system - -2. Change the default rights for newly created datasets. Do this by using these values in your config file (see :doc:`configuration`):: - - ckan.default_roles.Package = {"visitor": ["reader"], "logged_in": ["editor"]} - ckan.default_roles.Group = {"visitor": ["reader"], "logged_in": ["editor"]} - ckan.default_roles.System = {"visitor": ["reader"], "logged_in": ["editor"]} - ckan.default_roles.AuthorizationGroup = {"visitor": ["reader"], "logged_in": ["editor"]} - - -3. Publisher Mode -+++++++++++++++++ - -This allows edits only from authorized users. It is designed for installations where you wish to limit write access to CKAN and orient the system around specific publishing groups (e.g. government departments or specific institutions). - -The key features are: - -* Datasets are assigned to a specific publishing group. -* Only users associated to that group are able to create or update datasets associated to that group. - -To operate in this mode: - -1. First, remove the general public's rights to create and edit datasets:: - - paster rights remove visitor anon_editor package:all - paster rights remove logged_in editor package:all - paster rights remove visitor anon_editor system - paster rights remove logged_in editor system - -2. If logged-in users have already created datasets in your system, you may also wish to remove their admin rights. For example:: - - paster rights remove bob admin package:all - -3. Change the default rights for newly created datasets. Do this by using these values in your config file (see :doc:`configuration`):: - - ckan.default_roles.Package = {"visitor": ["reader"], "logged_in": ["reader"]} - ckan.default_roles.Group = {"visitor": ["reader"], "logged_in": ["reader"]} - ckan.default_roles.System = {"visitor": ["reader"], "logged_in": ["reader"]} - ckan.default_roles.AuthorizationGroup = {"visitor": ["reader"], "logged_in": ["reader"]} - -Note you can also restrict dataset edits by a user's authorization group. + Insert cross-reference to ``IAuthFunctions`` docs. diff --git a/doc/organizations_and_groups.rst b/doc/organizations_and_groups.rst deleted file mode 100644 index 4518ade38cc..00000000000 --- a/doc/organizations_and_groups.rst +++ /dev/null @@ -1,240 +0,0 @@ -Organizations and Groups -======================== - -This file contains the essential use cases and user stories (but not all -possible use cases and user stories) for Organizations and Groups in CKAN. It -should give a sense of the purpose of these features and the difference between -Groups and Organizations. The file then gives some technical analysis of how -the features should be implemented. - -Use Cases ---------- - -**A site like thedatahub.org**: -You want users to be able to register new user accounts and start adding -datasets as quickly and easily as possible. You don't want them to have to join -an organization before they can add a dataset, or to have to choose an -organization when adding a dataset. You would turn on the option that creates a -default 'public' organization that datasets are added to if no other -organization is specified. - -**A site like data.gov.uk**: -They don't want just anyone to be able to register a user account and start -adding content. So you would turn off the default public organization, and new -users would have to be added to an organization by a sysadmin or organization -admin before they can start adding content. By having multiple organizations -with different admins, they can distribute the responsibility for giving users -permission to create content. - -**If we have organizations, then what are groups for?** -The main difference between organizations and groups are: - -1. A member of an organization can edit any of the datasets in that - organization. Members of groups do not get permission to edit the group's - datasets, only to add datasets to and remove datasets from the group. - -2. A dataset must belong to exactly one organization, but can belong no group - or to multiple groups. - -Organizations are more about controlling who has permission to add and edit -datasets, whereas groups are just about categorizing datasets. - -data.gov.uk or thedatahub.org could use groups if they wanted a way for the -public to organize datasets into categories, or if they wanted groups of people -to be able to create sets of data to work on collaboratively. For example at -hackdays people often start by putting relevant datasets into a group. With -groups, this kind of collaboration can be orthogonal to the authorization -around organizations. - -**What is the difference between groups and tags?** -Groups work like controlled tags. While anyone who can edit a dataset can -create a new tag, only sysadmins can create new groups. While anyone can add -any tag to a dataset, only sysadmins or members of a group can add a dataset -to that group. - - -User Stories ------------- - -Roles for the User Stories -`````````````````````````` - -These roles are used to describe users in the user stories below: - -**Sysadmin** - A CKAN sysadmin user. - -**Organization or Group Editor** - A CKAN user who is a member of an -organization or group with capacity _editor_. - -**Organization or Group Admin** - A CKAN user who is a member of an -organization or group with capacity _admin_. - -**User** - A CKAN user who is not a member of any particular organization -or group on the site. - -**Anyone** - Anyone in any of the above roles, or even a site visitor who is -not even logged in. - -User Stories that apply to both Organizations and Groups -```````````````````````````````````````````````````````` - -* **Anyone** can see a list of all the site's organizations. -* **Anyone** can see a list of all the site's groups. -* **Anyone** can see a list of all an organization's _public_ datasets -* **Anyone** can see a list of all a group's datasets (groups can't have - private datasets, they're all public) -* **Sysadmins** can create new organizations, and automatically become admins - of the organizations they create. -* **Sysadmins** can create new groups, and automatically becomes admins of the - groups they create. -* **Users** can create new organizations, if this is enabled in the config - file (boolean option), and will automatically become admin of the new - organization -* **Users** can create new groups, if this is enabled in the config - file (another boolean option), and will automatically become admin of the new - group -* **Organization admins** can add users to and remove users from an - organization that they are admin of. -* **Organization admins** can specify what role (editor or admin) each user who - is a member of the organization has. -* **Group admins** can add users to and remove users from a group that they - are admin of. -* **Group admins** can add specify what role (editor or admin) each - user who is a member of the group has. -* **Sysadmins** can add users to and remove users from any organization or - group, and set the role (editor or admin) of any user in any organization or - group. -* **Organization admins** and **sysadmins** can edit the organization's - metadata (name, description, etc.) -* **Group admins** and **sysadmins** can edit the group's metadata (name, - description, etc.) -* **Developers** can provide custom forms for groups and organizations, for - example to add custom metadata fields to groups or organizations. -* **Anyone** can see which users are members of groups. -* **Sysadmins** should decide if members of organizations should be visible to the public - globally throughout the site. If they are not visible to the public only syadmins and - orgainization admins should be able to see the members of the organization. - - -User Stories that apply to Organizations Only -````````````````````````````````````````````` - -* **Organization admins and editors** can see an organization's private - datasets. They should be able to see them in thier organization's search - results and have a facet of public/private so they can filter by them. -* **Organization admins and editors** can create new datasets that belong to - the organization, and choose whether they are public or private. -* **Organization admins and editors** can edit all datasets belonging to the - organization, including making the datasets public or private. -* **Organization admins and editors** can _only_ create datasets that belong to - one of the organizations they are a member of. They cannot create a dataset - that doesn't belong to any organization, and a dataset cannot belong to more - than one organization at a time. - -This last use story raises the question of whether it's possible for anyone to -create a dataset that doesnt belong to any organization, or whether everyone -has to join an organization before they can start adding datasets. - -The suggestion solution is a boolean config option that, if enabled, creates a -default 'public' organization that new datasets are added to if no other -organization is specified. Users who are not a member of an organization will -be able to add datasets to this default organization. - -* **Sysadmins** can move datasets from one organization to another. - -* **Sysadmins** can delete organizations, and this deletes all of the - organization's datasets. - -User Stories that apply to Groups Only -`````````````````````````````````````` - -* **Group editors and admins** can add datasets to and remove datasets from the - groups that they are members of. A dataset can belong to multiple groups at - once, or can belong to no groups. - -* **Sysadmins and Group Admins** can delete groups, but unlike with organizations this does not - delete the group's datasets. - -Joining Groups and Organizations -```````````````````````````````` - -User stories about how users can apply to join groups and organizations or can -request the creation of groups and organizations have been intentionally left -out. These user stories can be added later and are very likely to be instance -specific. (But note that by default according to the user stories above -sysadmins and, if enabled, normal users can create organizations and groups, -and sysadmins and organization and group admins can add users to organizations -and groups.) - -Hierarchies of Groups and Organizations -``````````````````````````````````````` - -Previous specifications and implementations of organizations supported -hierarchies in which organizations could be parents and children of each other. -We do not intend to support this in the new implementation, at least not at -first. - -Private Groups and Organizations -```````````````````````````````` - -Although we will support private datasets in organizations, we do not intend to -support private organizations or groups that cannot be seen by everyone, at -least not at first. - -Technical FAQ -============= - -**What is the data model for this groups/organization?** - - -The data model will not change from how it is currently:: - - +------------+ - | | - +---+ dataset | - +------------+ +-----------+ | | | - | | | +---+ +------------+ - | group +-----+ member | - | | | +---+ +------------+ - +------------+ +-----------+ | | | - +---+ user | - | | - +------------+ - -The group table has a "type" field specifying if the table is an "organization" -or a "group". - -Using the one 'group' table for both organizations and groups means you can't -have an organization and a group with the same name. This is probably a good -thing as it would be confusing for users anyway. - -The member table has field called capacity which should be used as follows: - -* When a dataset is a member of an Organization it must have capacity of - 'ozganization'. -* When a dataset is a member of a Group it must have capacity of 'member'. -* When a user is a member of a Group/Organization it must have capacity - of the users role eg. admin, editor, memeber - - -The package table has gained two new fields - -owner_org - the id of the owning organization -private - determines if the dataset is public or private -` -Config options -============== - -The following config options have been created. - -ckan.auth.user_create_organizations -ckan.auth.user_create_groups - -ckan.auth.create_user_via_api -ckan.auth.create_dataset_if_not_in_organization - -ckan.auth.anon_create_dataset -ckan.auth.user_delete_groups - -ckan.auth.user_delete_organizations -ckan.auth.create_unowned_dataset diff --git a/doc/publisher-profile.rst b/doc/publisher-profile.rst deleted file mode 100644 index 75b201969c9..00000000000 --- a/doc/publisher-profile.rst +++ /dev/null @@ -1,77 +0,0 @@ -============================== -Publisher Profile and Workflow -============================== - -.. versionadded:: 1.7 - -The Publisher/Organization workflow in CKAN is designed to support a setup in which datasets -are managed by a "Publisher" organization. Users can become members of one (or -more) Organizations and their membership determines what datasets they have access -to. - -Specifically, the workflow looks like: - -* A User joins or creates an Organization - - * If the user is the creator of the Organization then they become administrator of the Organization. - - * Otherwise they become a Member. - -* New Members must be added by the Organization Administrator, although anyone can request to join an Organization - -* User creates a dataset. On creation User must assign this dataset to a - specific organization (and can only assign to a organization of which User is a - member) - - * Other members of that Organization can then edit and update this dataset - -This setup is a natural one for many situations. For example: - - * Government. Organizations correspond to Departments or Ministries (or other - organizational groups) - - * Academia: Organizations again correspond to Departments or research groups - -Whilst organizations can currently belong to other organizations the publisher authorization profile currently only checks membership of the current organization. Future versions of this extension may provide a configuration option to apply authorization checks hierarchically. - -.. _publisher-configuration: - -Enabling and Configuring the Publisher Profile -============================================== - -To switch CKAN to use the authorization publisher profile you need to set the -following configuration option:: - - ckan.auth.profile = publisher - -Setting auth.profile to publisher will enable the publisher authorization -profile. Setting it to nothing, or if it is not present will force CKAN to use -the default profile. - -To enable the default organization and organization dataset forms you should include -the following plugins in your configuration file:: - - ckan.plugins = organizations organizations_dataset - -Technical Overview -================== - -* Organizations are a specialization of CKAN Groups. As such they retain many of - their features. -* Authorization for most actions is granted based on shared membership of a - group between the **user** and the **object** being manipulated. -* You can design custom forms for publisher sign up and editing. - -In more detail, these concepts are as follows: - -* :doc:`Domain Objects ` such as *groups*, *datasets* and *users* - can be added as members of groups. -* Each user within a group has a capacity with which it can interact with the - group, currently these are *editor* and *administrator*. -* Even though groups are hierarchical there must be an intersection of the - user's groups and the **object**'s groups for permission to be granted, as - long as the capacity is appropriate. For instance, being an *editor* within - a group does not necessarily grant authorization to edit the group. -* This means that individual permissions do not need to granted on a *user* by - *user* basis, instead the user can just be added to the appropriate group. -