Skip to content

Koji User Management

All of these operations require Koji admin privileges. You can see what privileges you have by running osg-koji list-permissions --mine. If you don't see admin, you do not have Koji admin privileges.

As of March 2018, the people with admin privileges are:

  • Mat Selmeci
  • Carl Edquist
  • Brian Lin
  • Tim Cartwright
  • Tim Theisen

Adding a User

Adding a user requires two pieces of information about the user:

  • the DN of the cert they're using
  • their purpose for using Koji, e.g. what package(s) they are going to build, what repos they are going to build into, or whether they should have promotion abilities for certain repos

Koji only allows certs signed by one of the following CAs:

  • ESnet Root CA 1
  • CERN Trusted Certification Authority
  • CERN Grid Certification Authority
  • CILogon Basic CA 1 (note: Fermi certs are signed by this)
  • CILogon OSG CA 1

This is controlled by the /etc/pki/tls/CAs/allowed-cas-for-users.crt file, which contains the full cert chains for these CAs.


The file also contains the cert chains for the following two CAs, which are used for build hosts and automated users.

  • InCommon RSA Server CA

You can usually guess which CA signed the user's cert from their DN. If unsure, ask them for the output of:

$ openssl x509 -in <CERTFILE> -noout -issuer

If the CA is not one of the above ones, you will have to add the CA. Get permission to do this from the Software Manager, then follow the procedure on the koji-hub setup page.

The user's Koji username will be the first Common Name (CN) of their certificate subject. For example:

$ openssl x509 -in <CERTFILE> -noout -subject
subject= /DC=org/DC=cilogon/C=US/O=Fermi National Accelerator Laboratory/OU=People/CN=Matyas Selmeci/CN=UID:matyas

will result in the Koji username "Matyas Selmeci". To add the user, run

$ osg-koji add-user "<USERNAME>"

This will create the user but will give them no permissions.


It is effectively impossible to delete a user. If you get the name wrong, follow the instructions below for renaming a user below.

To give them permissions, use the command

$ osg-koji grant-permission <PERMISSION> "<USERNAME>"

Generally, the permissions you should give are (more explanation below):

  • most people should be given build and repo
  • HCC people should also be given hcc-build
  • S&R people should also be given software-team
  • Security people should also be given security-team
  • Ops people should also be given operations-team
  • other software devs should also be given software-contributor
  • few people should be given admin

To revoke permissions, use the command

$ osg-koji revoke-permission <PERMISSION> "<USERNAME>"

Permissions details

To list the available permissions, run

$ osg-koji list-permissions

The important permissions are:

  • repo: the ability to run osg-koji regen-repo. Should be given to anyone that builds or tests packages.
  • build: the ability to build (but not tag!) any package. Should be given to anyone that builds packages, including automated users. This perm is necessary but not sufficient for them to build into the development repos; it is enough to let them do scratch builds.
  • software-contributor: the ability to build into any of the development repos and promote into the osg-testing repos (but not any other repos). Should be given to people that build specific software but do not belong to the OSG S&R team or HCC.
  • operations-team: the ability to build into development and promote into testing the vo-client package. Should be given to people in OSG Operations.
  • security-team: the ability to build into development and promote into testing the *-ca-certs* packages. Should be given to people in OSG Security.
  • hcc-build: the ability to build and promote into any of the hcc tags. Should be given to people in Nebraska's Holland Computing Center.
  • software-team, release-team: the ability to build any package into any development tag, and promote to any tag. Current policy does not distinguish between these two permissions. Should be given to people on the S&R team.
  • admin: the ability to do anything (short of direct database or config manipulation). Should be given sparingly.

The grant-permission command can also be used to create new permissions; doing so is beyond the scope of this document. For further permission details, see the policy writing doc and /etc/koji-hub/hub.conf on

Handling User Cert Changes / Renaming a User

Koji users are identified by the first Common Name (CN) of their X.509 certificate. If this changes for a user (e.g. they get a cert from a new CA), someone with root access on will need to SSH there and do the following:

$ sudo /root/psql-kojidb
koji=> BEGIN;
koji=> SELECT * FROM users WHERE name='<OLDNAME>';
-- make sure you find one and exactly one person
koji=> UPDATE users SET name='<NEWNAME>' WHERE name='<OLDNAME>';
-- 1 row should have been updated
koji=> SELECT * FROM users;
-- sanity check; if everything looks ok, commit
koji=> COMMIT;
koji=> \q

If you mess up, do ROLLBACK; BEGIN; and try again.

Inform the user:

  • they can no longer use their old cert
  • if they aren't using a proxy for Koji auth, they must rerun osg-koji setup to fix their client.crt files
  • they must import their new cert into their browsers
  • they must clear their browser cache and cookies for before using the web interface (or else they'll get a Python stack trace when they try to connect)

Disabling and Enabling a User

Users cannot be deleted, but they can be disabled. We also put (disabled) in their username to let us easily distinguish between enabled and disabled users.

To disable a user, use the command:

$ osg-koji disable-user "<USERNAME>"

Follow the rename procedure above to change their name from <USERNAME> to <USERNAME> (disabled).

To enable a user, follow the rename procedure above to change their name from <USERNAME> (disabled) to <USERNAME>. Then, use the command:

$ osg-koji enable-user "<USERNAME>"