diff --git a/doc/authorization.rst b/doc/authorization.rst index 616dd0af636..c8766fe9927 100644 --- a/doc/authorization.rst +++ b/doc/authorization.rst @@ -2,76 +2,115 @@ Authorization ============= -.. note:: Authorization in ckan 2.0 works differently from previous versions. +.. versionchanged:: 2.0 + Previous versions of CKAN used a different authorization system. -Authorization in CKAN is controlled in a number of ways. +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, who can register new user +accounts, delete user accounts, or create, edit and delete datasets, groups and +organizations. -* Organizations -* Config settings +Authorization in CKAN can be controlled in three ways: -This document aims to explain them. +1. Organizations +2. Configuration file options +3. Authorization functions + +The following sections explain each of the three methods in turn. + +.. note:: + + 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. Organizations ------------- -From version 2.0 CKAN uses organizations as the primary way to control -access to datasets as well as giving permissions to users to perform actions -on datasets. Each dataset in CKAN can belong to a single organization. The -organization that the dataset belongs to controls the permissions for all -datasets that it owns. + +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. Datasets can be marked as public or private. Public datasets are visible to -all users. Private datasets can only be seen by members of the organization -that owns the dataset. Private datasets are not shown in general dataset -searches but are shown in dataset searches within the organization. +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. -Organizations have members. The members of an organization have a role. -Currently the roles available are. +When a user joins an organization, an organization admin gives them one of +three roles: member, editor or admin. -``Admin`` - Administrators of an organization can add or remove members of the - organization, as well as edit or delete the organization itself. They can - add, edit, view and delete datasets owned by the organization. Admins can - also make owned datasets public or private. When a user creates a new - organization, they automatically become the first administrator of that - organization. +An organization **admin** can: -``Editor`` - Editors of an organization can view, edit, add and delete datasets as well - as view any owned datasets. +* View the organization's private datasets +* Edit and delete the organization +* Edit and delete the organization's datasets +* Add new datasets to the organization +* Make datasets public or private. +* Add users to the organization, and choose whether to make the new user an + 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 -``Member`` - Members of an organization can view datasets belonging to an organization - including private datasets. +An **editor** can: +* View the organization's private datasets +* Add, edit and delete the organization's datasets -Config Settings ---------------- +A **member** of an organization can view the organization's private datasets. -Several configuration file options can be set to change the behavior of CKAN. -These include -``ckan.auth.anon_create_dataset`` - allows non registered users to create datasets, default: False +Configuration File Options +-------------------------- -``ckan.auth.create_dataset_if_not_in_organization`` - allow users who are not a member of any organization create datasets. - This depends on option ``create_unowned_dataset``, default: True +The following configuration file options can be used to customize CKAN's +authorization behavior: + +``ckan.auth.anon_create_dataset`` + Allow users to create datasets without registering and logging in, + default: false. ``ckan.auth.create_unowned_dataset`` - allow the creation of datasets not owned by an organization, default: True + Allow the creation of datasets not owned by any organization, default: true. + +``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. ``ckan.auth.user_create_groups`` - allow registered users to create their own group, default: True + Allow users to create groups, default: true. ``ckan.auth.user_create_organizations`` - allow registered users to create their own organization, default: True + Allow users to create organizations, default: true. ``ckan.auth.user_delete_groups`` - allow non system administrator users to delete groups, default: True + Allow users to delete groups, default: true. ``ckan.auth.user_delete_organizations`` - allow non system administrator users to delete organizations, default: True + Allow users to delete organizations, default: true. ``ckan.auth.create_user_via_api`` - allow non system administrator users to be created via the API, default: False + Allow new user accounts to be created via the API, default: false. + + +Authorization Functions +----------------------- + +Each logic function in CKAN has a corresponding authorization function. +These functions are in files in the `ckan/logic/auth` directory. These +functions are used to determine if the user has the permission to perform +the given action. Because CKAN allows these functions to be redefined by +extensions it is important never to directly call these functions but to +call them via the `ckan.logic.check_access()` function. If the user does +not have permission a `NotAuthorized` exception is raised. + +.. note:: extensions should access both `check_access` and `NotAuthorized` + via the plugins toolkit - see the section on Extensions for more details. + +Templates can access authorization functions via the `h.check_access()` +template helper function.