#2415 doc: more info about permission system
Merged 2 years ago by tkopecek. Opened 2 years ago by tkopecek.
tkopecek/koji issue2234  into  master

@@ -0,0 +1,60 @@ 

+ ===============

+ Access Controls

+ ===============

+ 

+ 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

+ ===========================

+ 

+ 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 found at :ref:`auth-config`

+ 

+ Allowed SCMs

+ ============

+ 

+ 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 the ``allowed_scms`` option are covered under :ref:`scm-config`

+ 

+ 

+ Hub Policies

+ ============

+ 

+ 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

+ 

+ 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.

+ 

+ For more details see :doc:`defining_hub_policies`.

+ 

+ User Permissions

+ ================

+ 

+ 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.

file modified
+1
@@ -22,6 +22,7 @@ 

      :maxdepth: 2

  

      HOWTO

+     access_controls

      permissions

      defining_hub_policies

      external_repo_server_bootstrap

file modified
+11 -5
@@ -12,8 +12,10 @@ 

  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 <defining_hub_policies>`.

+ Custom permissions can used as the required permission for a tag, or they can be

+ referenced in :doc:`hub policies <defining_hub_policies>`. Note, that you need

+ to first understand the policy mechanism as most permissions are reflected in

+ policy rules.

  

  

  Permission management
@@ -48,11 +50,15 @@ 

    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

@@ -1314,6 +1314,9 @@ 

  * 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

  ----------------------------

  

Note, that you need to first understand policy mechanism as most permissions are reflected in policy rules.

grammar: need a "the" before "policy mechanism"

but, moreso, I'm not sure that just referencing the policy doc is enough clarification where. Some of our access controls are simple permission checks and others are policy checks (that may themselves check a permission)

1 new commit added

  • doc: access control
2 years ago

updated + added acces control page

The access control doc is a big broader than I expected, but I guess it makes sense to mention auth and cover allows_scms. However, the "Perimeter" section seems like it maybe belongs elsewhere. It's good stuff to document, but I feel like it's distracting from the main point.

I think policies and permissions should be the highlight here.

Only builders from createrepo channel (and runroot if you're using that plugin)
should have mounted koji volumes in read-write mode.

This is not true. The createrepo builders only require read-only mounts. The runroot plugin is the only place where read-write mounts are used on builders.

There is whole document :doc:defining_hub_policies covering this.

grammar: need an article before "whole document". I.e. "There is a whole document"

However, I'd just say something simpler like: "See the :doc:defining_hub_policies document for details."

Hub policies are core system of access controls. It can define specialized

grammar: agreement. "Hub policies" is plural. "It" is singular. Or perhaps "it" refers to something else, if so it is unclear what. Perhaps, "Policies govern many actions ranging from..."

Also, it's probably worth clarifying that some only some policies are allow/deny policies (like package_list and build_from_srpm). Others, like channel and volume, govern different parts of Koji behavior.

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.

I'm not sure what the first sentence is saying. I guess we dont want to repeat too much of the permissions doc, but we should say something. Maybe something like:

The permissions system allows admins to grant named permissions to individual users. These permissions govern access to various features of Koji. Permission checks can also be used in policies.

1 new commit added

  • minor fixes
2 years ago

Metadata Update from @tkopecek:
- Pull-request tagged with: doc, no_qe

2 years ago

1 new commit added

  • doc updates
2 years ago

Commit 44db1bc fixes this pull-request

Pull-Request has been merged by tkopecek

2 years ago