Organizations and authorization

Organizations and authorization¶
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.
Authorization in CKAN can be controlled in four ways:

Organizations
Dataset collaborators
Configuration file options
Extensions

The following sections explain each of the four 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¶
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
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 dataset searches
unless the logged in user (or the user identified via an API key)
has permission to access them.
When a user joins an organization, an organization admin gives them one of
three roles: member, editor or admin.
A member can:

View the organization’s private datasets.

An editor can do everything a member can plus:

Add new datasets to the organization
Edit or delete any of the organization’s datasets
Make datasets public or private.

An organization admin can do everything as editor plus:

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

When a user creates a new organization, they automatically become the first
admin of that organization.

Dataset collaborators¶

Changed in version 2.9: Dataset collaborators were introduced in CKAN 2.9

In addition to traditional organization-based permissions, CKAN instances can also enable
the dataset collaborators feature, which allows dataset-level authorization. This provides
more granular control over who can access and modify datasets that belong to an organization,
or allows authorization setups not based on organizations. It works by allowing users with
appropriate permissions to give permissions to other users over individual datasets, regardless
of what organization they belong to.
Dataset collaborators are not enabled by default, you need to activate it by
setting ckan.auth.allow_dataset_collaborators to True.
By default, only Administrators of the organization a dataset belongs to can add collaborators
to a dataset. When adding them, they can choose between two roles: member and editor.
A member can:

View the dataset if it is private.

An editor can do everything a member can plus:

Make the dataset public or private.
Edit or delete the dataset (including assigning it to an organization)

In addition, if ckan.auth.allow_admin_collaborators is set to True, collaborators
can have another role: admin.
An admin collaborator can do everything an editor can plus:

Add collaborators to the dataset, and choose whether to make them a
member, editor or admin (if enabled)
Change the role of any collaborator in the dataset, including other admin users
Remove collaborators of any role from the dataset

If the ckan.auth.allow_admin_collaborators setting is turned off in a site where admin collaborators have already been created, existing collaborators with role admin will no longer be able to manage collaborators, but they will still be able to edit and access the datasets that they are assigned to (ie they will have the same permissions as an editor.
If the global ckan.auth.allow_dataset_collaborators setting is turned off in a site where collaborators have already been created, collaborators will no longer have permissions on the datasets they are assigned to, and normal organization-based permissions will be in place.

Warning
When turning off this setting, you must reindex all datasets to update the permission labels, in order to prevent access to private datasets to the previous collaborators.

By default, collaborators can not change the owner organization of a dataset unless they are admins or editors in both the source and destination organizations. To allow collaborators to change the owner organization even if they don’t belong to the source organization, set ckan.auth.allow_collaborators_to_change_owner_org to True.
Dataset collaborators can be used with other authorization settings to create custom authentication scenarios. For instance on instances where datasets don’t need to belong to an organization (both ckan.auth.create_dataset_if_not_in_organization and ckan.auth.create_unowned_dataset are True), the user that originally created a dataset can also add collaborators to it (allowing admin collaborators or not depending on the ckan.auth.allow_admin_collaborators setting). Note that in this case though, if the dataset is assigned to an organization, the original creator might no longer be able to access and edit, as organization permissions take precedence over collaborators ones.

Configuration File Options¶
The following configuration file options can be used to customize CKAN’s
authorization behavior:

ckan.auth.anon_create_dataset¶
Example:
ckan.auth.anon_create_dataset = False

Default value: False
Allow users to create datasets without registering and logging in.

ckan.auth.create_unowned_dataset¶
Example:
ckan.auth.create_unowned_dataset = False

Default value: True
Allow the creation of datasets not owned by any organization.

ckan.auth.create_dataset_if_not_in_organization¶
Example:
ckan.auth.create_dataset_if_not_in_organization = False

Default value: True
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¶
Example:
ckan.auth.user_create_groups = True

Default value: False
Allow users to create groups.

ckan.auth.user_create_organizations¶
Example:
ckan.auth.user_create_organizations = False

Default value: True
Allow users to create organizations.

ckan.auth.user_delete_groups¶
Example:
ckan.auth.user_delete_groups = False

Default value: True
Allow users to delete groups.

ckan.auth.user_delete_organizations¶
Example:
ckan.auth.user_delete_organizations = False

Default value: True
Allow users to delete organizations.

ckan.auth.create_user_via_api¶
Example:
ckan.auth.create_user_via_api = False

Default value: False
Allow new user accounts to be created via the API by anyone. When False only sysadmins are authorised.

ckan.auth.create_user_via_web¶
Example:
ckan.auth.create_user_via_web = True

Default value: True
Allow new user accounts to be created via the Web.

ckan.auth.roles_that_cascade_to_sub_groups¶
Example:
ckan.auth.roles_that_cascade_to_sub_groups = admin editor

Default value: admin
Makes role permissions apply to all the groups or organizations down the hierarchy from the groups or organizations that the role is applied to.
e.g. a particular user has the ‘admin’ role for group ‘Department of Health’. If you set the value of this option to ‘admin’ then the user will automatically have the same admin permissions for the child groups of ‘Department of Health’ such as ‘Cancer Research’ (and its children too and so on).

ckan.auth.public_user_details¶
Example:
ckan.auth.public_user_details = False

Default value: True
Restricts anonymous access to user information. If is set to False accessing users details when not logged in will raise a Not Authorized exception.

Note
This setting should be used when user registration is disabled (ckan.auth.create_user_via_web = False), otherwise users
can just create an account to see other users details.

ckan.auth.public_activity_stream_detail¶
Example:
ckan.auth.public_activity_stream_detail = True

Default value: False (however the default config file template sets it to True)
Restricts access to ‘view this version’ and ‘changes’ in the Activity Stream pages. These links provide users with the full edit history of datasets etc - what they showed in the past and the diffs between versions. If this option is set to False then only admins (e.g. whoever can edit the dataset) can see this detail. If set to True, anyone can see this detail (assuming they have permission to view the dataset etc).

ckan.auth.allow_dataset_collaborators¶
Example:
ckan.auth.allow_dataset_collaborators = True

Default value: False
Enables or disable collaborators in individual datasets. If True, in addition to the standard organization based permissions, users can be added as collaborators to individual datasets with different roles, regardless of the organization they belong to. For more information, check the documentation on Dataset collaborators.

Warning
If this setting is turned off in a site where there already were collaborators created, you must reindex all datasets to update the permission labels, in order to prevent access to private datasets to the previous collaborators.

ckan.auth.allow_admin_collaborators¶
Example:
ckan.auth.allow_admin_collaborators = True

Default value: False
Allows dataset collaborators to have the “Admin” role, allowing them to add more collaborators or remove existing ones. By default collaborators can only be managed by administrators of the organization the dataset belongs to. For more information, check the documentation on Dataset collaborators.

Warning
If this setting is turned off in a site where admin collaborators have been already created, existing collaborators with role “admin” will no longer be able to add or remove collaborators, but they will still be able to edit and access the datasets that they are assinged to.

ckan.auth.allow_collaborators_to_change_owner_org¶
Example:
ckan.auth.allow_collaborators_to_change_owner_org = True

Default value: False
Allows dataset collaborators to change the owner organization of the datasets they are collaborators on. Defaults to False, meaning that collaborators with role admin or editor can edit the dataset metadata but not the organization field.

ckan.auth.create_default_api_keys¶
Example:
ckan.auth.create_default_api_keys = True

Default value: False
Determines if a an API key should be automatically created for every user when creating a user account. If set to False (the default value), users can manually create an API token from their profile instead. See Authentication and API tokens: for more details.

Extensions¶
CKAN extensions can implement custom authorization rules by overriding the
authorization functions that CKAN uses. This is done by implementing the
IAuthFunctions plugin interface.
Dataset visibility is determined by permission labels stored in the
search index.
Implement the IPermissionLabels
plugin interface then rebuild your search index
to change your dataset visibility rules. There is no
no need to override the package_show auth function, it will inherit
these changes automatically.
To get started with writing CKAN extensions, see Extending guide.