canonical-ubuntu-qa team mailing list archive

[Tim Andersson <mp+469839@xxxxxxxxxxxxxxxxxx>]

Tim Andersson has proposed merging ~andersson123/autopkgtest-cloud:api-key-howto into autopkgtest-cloud:master.

Commit message:
docs: detail how to create an API key

Currently, the docs only mention **how** an individual can use an API
key - there is no mention or guideline regarding how an admin should
create an API key for a requested user, group or bot.

This commit amends the issue by adding a new section which details how
an `autopkgtest-cloud` admin should create an API key.

Requested reviews:
  Canonical's Ubuntu QA (canonical-ubuntu-qa)

For more details, see:
https://code.launchpad.net/~andersson123/autopkgtest-cloud/+git/autopkgtest-cloud/+merge/469839

Adds more detail to the documentation regarding how an autopkgtest admin should create API keys.
-- 
Your team Canonical's Ubuntu QA is requested to review the proposed merge of ~andersson123/autopkgtest-cloud:api-key-howto into autopkgtest-cloud:master.

diff --git a/docs/administration.rst b/docs/administration.rst
index 6040a9c..aa3a643 100644
--- a/docs/administration.rst
+++ b/docs/administration.rst
@@ -222,8 +222,57 @@ Once those steps are done then the rows can be deleted from the database.
 * ``sqlite3 -header -column autopkgtest.db "DELETE FROM test WHERE test.release='impish';"``
 * ``sqlite3 -header -column autopkgtest.db "vacuum;"``
 
-API Key Integration
--------------------
+Creating a new API key
+----------------------
+
+API keys exist on the web workers with the following format:
+
+.. code-block:: bash
+
+  {"username": "api-key", "username": "api-key"}
+
+And so on and so forth. The ``username`` should be the launchpad username of the individual who is
+requesting an API key. This is not strict, however, and could potentially be anything, as long as the user
+attaches their API key using the correct name as provided by the Ubuntu Release Management Team. It just makes
+the most sense to just use launchpad usernames.
+
+The ``username`` can also potentially be a name to refer to a group of individuals sharing the same key, or a bot.
+
+The convention to create API keys has thus far been the following, utilising uuid4:
+
+.. code-block:: bash
+
+  python3 -c 'import uuid; print(uuid.uuid4())'
+
+We use python's uuid4 from the uuid library because:
+- uuid4 is generally accepted as having the strongest guarantee of uniqueness and security out of
+  all the uuid methods.
+- uuid4 isn't guaranteed in the documentation to be cryptographically secure, however, it utilises
+  [urandom](https://docs.python.org/3/library/os.html#os.urandom), which is declared as suitable for cryptographic use.
+
+DO NOT use a uuid4 function from another source - the python implementation is guaranteed to use a
+cryptographically secure random string generator, so for ``autopkgtest-cloud`` API tokens just use
+what's detailed above. Other implementations may waver from this.
+
+Once the ``uuid`` for the api key has been created, add it to:
+
+.. code-block:: bash
+
+  /home/$STAGE-proposed-migration-environment/.local/share/mojo/LOCAL/mojo-$STAGE-proposed-migration/production/external-web-requests-api-keys.json
+
+Where ``$STAGE`` is either ``prod`` or ``stg``.
+
+After this, do a ``mojo run`` to deploy the altered file.
+
+Alternatively, if a ``mojo run`` is for some reason, undesirable at the time, one can also directly add the new api key to the following file on the web units:
+
+``/home/ubuntu/external-web-requests-api-keys.json``
+
+The api keys are loaded for each request, so there's no need to restart ``apache2``.
+
+
+Using API Keys
+--------------
 
 Requests can be requested by using an API key instead of authenticating using SSO.
 To do so, attach a cookie to whatever script is making the test request, with the name