diff --git a/docs/source/access_controls.rst b/docs/source/access_controls.rst new file mode 100644 index 00000000..0d16beed --- /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 ea429c94..d98229fd 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 48776bae..700f1bed 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 b428750a..26d9e7eb 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 ----------------------------