From 409a071b5fccf0b41a06f7242a4ea00c86ebaa82 Mon Sep 17 00:00:00 2001 From: Tomas Kopecek Date: Aug 03 2020 13:32:27 +0000 Subject: [PATCH 1/4] doc: more info about permission system Fixes: https://pagure.io/koji/issue/2234 --- diff --git a/docs/source/permissions.rst b/docs/source/permissions.rst index f1c93b3..48776ba 100644 --- a/docs/source/permissions.rst +++ b/docs/source/permissions.rst @@ -12,8 +12,10 @@ It grants superuser access and can stand in for any other permission. Most of the built-in permissions control access to various hub calls. For example, the ``dist-repo`` permission allows access to create dist repos. -Custom permissions can used as the required permission for a tag, or they can -be referenced in :doc:`hub policies `. +Custom permissions can used as the required permission for a tag, or they can be +referenced in :doc:`hub policies `. Note, that you need +to first understand policy mechanism as most permissions are reflected in policy +rules. Permission management @@ -48,11 +50,15 @@ The following permissions govern access to key administrative actions. We recommend granting the smallest effective permission. ``host`` - Restricted permission for handling host-related management tasks. + Restricted admin permission for handling host-related management tasks. ``tag`` - Permission for adding/deleting/editing tags. - Allows use of the tagBuildBypass and untagBuildBypass API calls. + Permission for adding/deleting/editing tags. Allows use of the + ``tagBuildBypass`` and ``untagBuildBypass`` API calls also. Note, that this + name could be confusing as it is not related to tagging builds but to editing + tags themselves. Tagging builds (and adding/removing packages from package + lists for given tags) is handled by ``tag`` and ``package_list`` policies + respectively. ``target`` Permission for adding/deleting/editing targets From 6c5c40c6904bde974abe1664fcf55ea03803fa5e Mon Sep 17 00:00:00 2001 From: Tomas Kopecek Date: Aug 04 2020 10:26:52 +0000 Subject: [PATCH 2/4] doc: access control --- diff --git a/docs/source/access_controls.rst b/docs/source/access_controls.rst new file mode 100644 index 0000000..0d16bee --- /dev/null +++ b/docs/source/access_controls.rst @@ -0,0 +1,67 @@ +=============== +Access Controls +=============== + +Koji is complex system, so there are many places where some kind of access +control is used. Here is the documentation hub for all the mechanisms in place. + +Perimeter +========= + +This can't be covered here as it highly depends on architecture and usage of the +system. Nevertheless, the best option would be global (or company-wide) access +to web and hub https ports, so clients and builders can connect there. + +Builders should be restricted on external level (firewalls outside of builders +themselves) to contact only hub and allowed SCMs. There should be no allowed +access to the internet if there is no good reason to do that and these accessess +are monitored. Otherwise koji can't ensure reproducibility of the build (e.g. if +spec is downloading *something* from the internet - we're doomed). Secluded +intranet segment with nothing able to interfere here is a worthy thing. + +Only builders from createrepo channel (and runroot if you're using that plugin) +should have mounted koji volumes in read-write mode. Other builders don't need +that and from security/safety reasons it is not recommended to have it mounted +at all. + +User/Builder Authentication +=========================== + +Users (and builders) are authenticated via one of the following mechanisms. Most +preferred is GSSAPI/Kerberos authentication. Second best is authentication via +SSL certificates. Mostly for testing environments we also support authenticating via +username/password but it has its limitations which you should be aware of. + +Details can be find at :ref:`auth-config` + +SCM Permissions +=============== + +Most important data for koji are its inputs which equals to Source Control +Management systems (supported are CVS, SVN and GIT). Every production +environment should have limited set of trusted external sources. We're covering +this by ``alowed_scms`` option in builder's config. Admin can set there which +e.g. GIT repositories are allowed as inputs and can also instruct koji how to +create SRPM from such checkout. + +Details of ``alowed_scms`` option is covered under :ref:`scm-config` + + +Hub Policies +============ + +Hub policies are core system of access controls. It can define specialized +policies for many things ranging from permissions to tag specific builds to +specific tag to e.g. assigning builds to specific builders (channels) or storing +results on different disk volumes. + +There is whole document :doc:`defining_hub_policies` covering this. + +User Permissions +================ + +Specific chapter are user permissions. Every user can have set of permissions +which allow him to do some actions directly (typically ``admin`` permission) or +these permissions can be referenced in hub policies. + +See :doc:`permissions` for details. diff --git a/docs/source/index.rst b/docs/source/index.rst index ea429c9..d98229f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -22,6 +22,7 @@ Contents :maxdepth: 2 HOWTO + access_controls permissions defining_hub_policies external_repo_server_bootstrap diff --git a/docs/source/permissions.rst b/docs/source/permissions.rst index 48776ba..700f1be 100644 --- a/docs/source/permissions.rst +++ b/docs/source/permissions.rst @@ -14,8 +14,8 @@ For example, the ``dist-repo`` permission allows access to create dist repos. Custom permissions can used as the required permission for a tag, or they can be referenced in :doc:`hub policies `. Note, that you need -to first understand policy mechanism as most permissions are reflected in policy -rules. +to first understand the policy mechanism as most permissions are reflected in +policy rules. Permission management diff --git a/docs/source/server_howto.rst b/docs/source/server_howto.rst index b428750..26d9e7e 100644 --- a/docs/source/server_howto.rst +++ b/docs/source/server_howto.rst @@ -1314,6 +1314,9 @@ Additional Notes * It is not recommended that kojira run on the builders, as builders only should require read-only access to ``/mnt/koji``. + +.. _auth-config: + Authentication Configuration ---------------------------- From 3bc0a780d085f74d2d5b910b917dfbebd34d7ebe Mon Sep 17 00:00:00 2001 From: Tomas Kopecek Date: Aug 17 2020 11:49:11 +0000 Subject: [PATCH 3/4] minor fixes --- diff --git a/docs/source/access_controls.rst b/docs/source/access_controls.rst index 0d16bee..a0043bd 100644 --- a/docs/source/access_controls.rst +++ b/docs/source/access_controls.rst @@ -5,25 +5,6 @@ Access Controls Koji is complex system, so there are many places where some kind of access control is used. Here is the documentation hub for all the mechanisms in place. -Perimeter -========= - -This can't be covered here as it highly depends on architecture and usage of the -system. Nevertheless, the best option would be global (or company-wide) access -to web and hub https ports, so clients and builders can connect there. - -Builders should be restricted on external level (firewalls outside of builders -themselves) to contact only hub and allowed SCMs. There should be no allowed -access to the internet if there is no good reason to do that and these accessess -are monitored. Otherwise koji can't ensure reproducibility of the build (e.g. if -spec is downloading *something* from the internet - we're doomed). Secluded -intranet segment with nothing able to interfere here is a worthy thing. - -Only builders from createrepo channel (and runroot if you're using that plugin) -should have mounted koji volumes in read-write mode. Other builders don't need -that and from security/safety reasons it is not recommended to have it mounted -at all. - User/Builder Authentication =========================== @@ -50,10 +31,14 @@ Details of ``alowed_scms`` option is covered under :ref:`scm-config` Hub Policies ============ -Hub policies are core system of access controls. It can define specialized +Hub policies are core system of access controls. They can define specialized policies for many things ranging from permissions to tag specific builds to specific tag to e.g. assigning builds to specific builders (channels) or storing -results on different disk volumes. +results on different disk volumes. Policies allow user permissions (see below) +to be used in their rulesets. + +Only some policies are for access control (allow/deny permissions checks) while +others like channel policy governs different areas of koji. There is whole document :doc:`defining_hub_policies` covering this. From f405534d38ed5d8ce40ae06f9d8858a8ded0086b Mon Sep 17 00:00:00 2001 From: Mike McLean Date: Aug 26 2020 07:18:46 +0000 Subject: [PATCH 4/4] doc updates --- diff --git a/docs/source/access_controls.rst b/docs/source/access_controls.rst index a0043bd..201c264 100644 --- a/docs/source/access_controls.rst +++ b/docs/source/access_controls.rst @@ -2,7 +2,7 @@ Access Controls =============== -Koji is complex system, so there are many places where some kind of access +Koji is a complex system, so there are many places where some kind of access control is used. Here is the documentation hub for all the mechanisms in place. User/Builder Authentication @@ -13,40 +13,48 @@ preferred is GSSAPI/Kerberos authentication. Second best is authentication via SSL certificates. Mostly for testing environments we also support authenticating via username/password but it has its limitations which you should be aware of. -Details can be find at :ref:`auth-config` +Details can be found at :ref:`auth-config` -SCM Permissions -=============== +Allowed SCMs +============ -Most important data for koji are its inputs which equals to Source Control -Management systems (supported are CVS, SVN and GIT). Every production -environment should have limited set of trusted external sources. We're covering -this by ``alowed_scms`` option in builder's config. Admin can set there which -e.g. GIT repositories are allowed as inputs and can also instruct koji how to -create SRPM from such checkout. +The ``allowed_scms`` option in builder's config controls which SCMs (Source Control Management +systems) are allowed for building. +We recommend that every production environment choose a limited set of trusted sources. -Details of ``alowed_scms`` option is covered under :ref:`scm-config` +Details of the ``allowed_scms`` option are covered under :ref:`scm-config` Hub Policies ============ -Hub policies are core system of access controls. They can define specialized -policies for many things ranging from permissions to tag specific builds to -specific tag to e.g. assigning builds to specific builders (channels) or storing -results on different disk volumes. Policies allow user permissions (see below) -to be used in their rulesets. +Hub policies are a powerful way for administrators to control Koji's behavior. +Koji's hub allows several different policies to be configured, some of which are +access control policies. + +An access control policy is consulted by the hub to determine if an action should be allowed. +Such policies return results of ``deny`` or ``allow``. + +Examples of access control polices are: + +* tag: control which tag operations are allowed +* package_list: control which package list updates are allowed +* cg_import: control which content generator imports are allowed +* vm: control which windows build tasks are allowed +* dist_repo: control which distRepo tasks are allowed +* build_from_srpm: control whether builds from srpm are allowed +* build_from_repo_id: control whether builds from user-specified repos ids are allowed -Only some policies are for access control (allow/deny permissions checks) while -others like channel policy governs different areas of koji. +Note that not all policies are access control policies. +The ``channel`` and ``volume`` policies are used to control which channels tasks go to +and which volumes build are stored on. -There is whole document :doc:`defining_hub_policies` covering this. +For more details see :doc:`defining_hub_policies`. User Permissions ================ -Specific chapter are user permissions. Every user can have set of permissions -which allow him to do some actions directly (typically ``admin`` permission) or -these permissions can be referenced in hub policies. +Every user can have a set of permissions which allow them to perform some actions directly. +These permissions may be checked directly by the hub, or they may be referenced in policies. See :doc:`permissions` for details.