diff --git a/docs/base_user.yaml b/docs/base_user.yaml new file mode 100644 index 0000000000..6840297a4d --- /dev/null +++ b/docs/base_user.yaml @@ -0,0 +1,182 @@ +authz: + # policies automatically given to anyone, even if they are not authenticated + anonymous_policies: + - open_data_reader + + # policies automatically given to authenticated users (in addition to their other policies) + all_users_policies: + - open_data_reader + + groups: + # can CRUD programs and projects and upload data files + - name: data_submitters + policies: + - services.sheepdog-admin + - data_upload + - MyFirstProject_submitter + users: + - username1@gmail.com + + # can create/update/delete indexd records + - name: indexd_admins + policies: + - indexd_admin + users: + - username1@gmail.com + + resources: + - name: workspace + - name: data_file + - name: services + subresources: + - name: sheepdog + subresources: + - name: submission + subresources: + - name: program + - name: project + - name: open + - name: programs + subresources: + - name: MyFirstProgram + subresources: + - name: projects + subresources: + - name: MyFirstProject + + policies: + - id: workspace + description: be able to use workspace + resource_paths: + - /workspace + role_ids: + - workspace_user + - id: data_upload + description: upload raw data files to S3 + role_ids: + - file_uploader + resource_paths: + - /data_file + - id: services.sheepdog-admin + description: CRUD access to programs and projects + role_ids: + - sheepdog_admin + resource_paths: + - /services/sheepdog/submission/program + - /services/sheepdog/submission/project + - id: indexd_admin + description: full access to indexd API + role_ids: + - indexd_admin + resource_paths: + - /programs + - id: open_data_reader + role_ids: + - reader + - storage_reader + resource_paths: + - /open + - id: all_programs_reader + role_ids: + - reader + - storage_reader + resource_paths: + - /programs + - id: MyFirstProject_submitter + role_ids: + - reader + - creator + - updater + - deleter + - storage_reader + - storage_writer + resource_paths: + - /programs + + roles: + - id: file_uploader + permissions: + - id: file_upload + action: + service: fence + method: file_upload + - id: workspace_user + permissions: + - id: workspace_access + action: + service: jupyterhub + method: access + - id: sheepdog_admin + description: CRUD access to programs and projects + permissions: + - id: sheepdog_admin_action + action: + service: sheepdog + method: '*' + - id: indexd_admin + description: full access to indexd API + permissions: + - id: indexd_admin + action: + service: indexd + method: '*' + - id: admin + permissions: + - id: admin + action: + service: '*' + method: '*' + - id: creator + permissions: + - id: creator + action: + service: '*' + method: create + - id: reader + permissions: + - id: reader + action: + service: '*' + method: read + - id: updater + permissions: + - id: updater + action: + service: '*' + method: update + - id: deleter + permissions: + - id: deleter + action: + service: '*' + method: delete + - id: storage_writer + permissions: + - id: storage_creator + action: + service: '*' + method: write-storage + - id: storage_reader + permissions: + - id: storage_reader + action: + service: '*' + method: read-storage + +clients: + wts: + policies: + - all_programs_reader + - open_data_reader + +users: + username1@gmail.com: {} + username2: + tags: + name: John Doe + email: johndoe@gmail.com + policies: + - MyFirstProject_submitter + +cloud_providers: {} +groups: {} diff --git a/docs/user.yaml_guide.md b/docs/user.yaml_guide.md new file mode 100644 index 0000000000..a818e62278 --- /dev/null +++ b/docs/user.yaml_guide.md @@ -0,0 +1,219 @@ +# A guide to customizing authorization via user.yaml in Gen3 + +## Table of Contents + +- [Introduction](#introduction) +- [Format](#format) + - [Programs and projects CRUD access](#programs-and-projects-crud-access) + - [Notes](#notes) +- [Deprecated format](#deprecated-format) + - [For Gen3 Data Commons that do not use Arborist](#for-gen3-data-commons-that-do-not-use-arborist) + +## Introduction + +The `user.yaml` file is one way to get authorization information into Gen3. It is ingested via [Fence's `usersync` script](usersync.md). The format of this file is tightly coupled with the notions of resource, role and policy as defined by Gen3's policy engine, [Arborist](https://github.com/uc-cdis/arborist#arborist). For Gen3 Data Commons that do not use Arborist, refer to the [Deprecated format](#deprecated-format) section. + +The `user.yaml` file is usually hosted in S3 and configured via the `global.useryaml_s3path` setting of the Gen3 Data Commons manifest: +``` +{ + "global": { + "useryaml_s3path": "s3://bucket-name/path/to/user.yaml", + ... + }, + ... +} +``` + +A template, ready-to-use `user.yaml` file can be found [here](base_user.yaml). + +When updating your `user.yaml` file, you should use the [`gen3users` CLI](https://github.com/uc-cdis/gen3users#gen3users) to validate it before use. + +## Format + +``` +authz: + # policies automatically given to anyone, even if they are not authenticated + anonymous_policies: + - open_data_reader + + # policies automatically given to authenticated users (in addition to their other policies) + all_users_policies: [] + + groups: + - name: program1_readers + policies: + - program1_reader + users: + - username1@domain.com + + # resource tree + resources: + - name: open + - name: programs + subresources: + - name: program1 + + policies: + - id: open_data_reader + role_ids: + - reader + - storage_reader + resource_paths: + - /open + - id: program1_reader + description: Read access to program1 + role_ids: + - reader + - storage_reader + resource_paths: + - /programs/program1 + - id: program1_indexd_admin + description: Admin access to program1 + role_ids: + - indexd_admin + resource_paths: + - /programs/program1 + + # currently existing methods are `read`, `create`, `update`, + # `delete`, `read-storage` and `write-storage` + roles: + - id: reader + permissions: + - id: reader + action: + method: read + service: '*' + - id: storage_reader + permissions: + - id: storage_reader + action: + method: read-storage + service: '*' + - id: creator + permissions: + - id: creator + action: + method: create + service: '*' + - id: indexd_admin + permissions: + - id: indexd_admin + action: + method: '*' + service: indexd + +# OIDC clients +clients: + client1: + policies: + - open_data_reader + +# all users must be defined here, even if they are not granted +# any individual permissions outside of the groups they are in. +# additional arbitrary information can be added in `tags`. +users: + username1@domain.com: {} + username2: + tags: + name: John Doe + email: johndoe@domain.com + policies: + - program1_reader +``` + +### Programs and projects CRUD access + +``` +{"message":"You don't have access to this resource: Unauthorized: User must be Sheepdog program admin"} +``` + +If you are using Arborist and you get this error message when trying to create a program or a project, you need to add the following to your `user.yaml` file and grant the `services.sheepdog-admin` policy to admin users: + +- resources: +``` + - name: services + subresources: + - name: sheepdog + subresources: + - name: submission + subresources: + - name: program + - name: project +``` + +- role: +``` + # Sheepdog admin role + - id: sheepdog_admin + description: sheepdog admin role for program project crud + permissions: + - id: sheepdog_admin_action + action: + service: sheepdog + method: '*' +``` + +- policy: +``` + - id: services.sheepdog-admin + description: CRUD access to programs and projects + role_ids: + - sheepdog_admin + resource_paths: + - /services/sheepdog/submission/program + - /services/sheepdog/submission/project +``` + +### Notes + +- While Arborist itself allows granular and inherited access through use of its resource tree / paths, granular access control beyond the `program` and `project` in the current Gen3 graph is not supported at the moment. +- Arborist does not support policies granting access to a root resource `/`. + +## Deprecated format + +The global `cloud_providers` and `groups` sections are deprecated. + +The `users.admin` flag used below is the deprecated way of granting program and project CRUD access. + +The `users.projects` section used below is the deprecated way of providing access. We should now use `users.policies` for individual access and `groups` for group access. + +``` +users: + username1: + admin: true + projects: + - auth_id: program1 + privilege: + - read + - read-storage + - write-storage +``` + +### For Gen3 Data Commons that do not use Arborist + +When Arborist is not being used (which is when the deprecated `acl` field of [Indexd](https://github.com/uc-cdis/indexd) records is used for access control instead of the newer `authz` field), only the access granted to users through the deprecated `user.yaml` format will take effect. This is how you should configure your `user.yaml` if you are not using Arborist: + +``` +authz: + user_project_to_resource: + program1: /programs/program1 + + resources: + - name: programs + subresources: + - name: program1 + - name: program2 + +users: + username1: + projects: + - auth_id: program1 + privilege: + - read + - auth_id: program2 + resource: /programs/program2 + privilege: + - read +``` + +The `user_project_to_resource` section can be used to avoid specifying a resource path for each `users.projects.resource`. diff --git a/fence/blueprints/data/indexd.py b/fence/blueprints/data/indexd.py index 52e8675738..8a5212d249 100644 --- a/fence/blueprints/data/indexd.py +++ b/fence/blueprints/data/indexd.py @@ -389,6 +389,7 @@ def check_authorization(self, action): # have just the `uploader` field and no ACLs. in this just check that the # current user's username matches the uploader field if self.index_document.get("uploader"): + logger.info("Checking access using `uploader` value") username = None if flask.g.token: username = flask.g.token["context"]["user"]["name"]