Merge ~andersson123/autopkgtest-cloud:api-key-howto into autopkgtest-cloud:master

[Tim Andersson]

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.

Adds more detail to the documentation regarding how an autopkgtest admin should create API keys.

[Tim Andersson (andersson123)]

I will look into other solutions for generating high enough entropy tokens - uuid isn't necessarily suited to be used as an API key, so some investigation is warranted

[Skia (hyask)]

As we discussed, I made a few research, and this [1] seems to indicate that UUID might not be the best solution.

[1]: https://security.stackexchange.com/questions/157270/using-v4-uuid-for-authentication

[Skia (hyask)]

Good for me! :-)

review: Approve

diff --git a/docs/administration.rst b/docs/administration.rst
index 6040a9c..39c01c6 100644
--- a/docs/administration.rst
+++ b/docs/administration.rst
@@ -222,8 +222,56 @@ 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