auth delegation docs

4 files changed, 44 insertions, 1 deletions

diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst
index 7f376bbf2..0e7829051 100644
--- a/docs/en/rst/administering/parameters.rst
+++ b/docs/en/rst/administering/parameters.rst
@@ -190,6 +190,9 @@ password_complexity
 password_check_on_login
     If set, Bugzilla will check that the password meets the current complexity rules and minimum length requirements when the user logs into the Bugzilla web interface. If it doesn't, the user would not be able to log in, and will receive a message to reset their password.
 
+auth_delegation
+    If set, Bugzilla will allow other websites to request API keys from its own users. See :ref:`auth-delegation`.
+
 .. _param-attachments:
 
 Attachments
diff --git a/docs/en/rst/api/core/v1/general.rst b/docs/en/rst/api/core/v1/general.rst
index 06ef5b2fb..814592f58 100644
--- a/docs/en/rst/api/core/v1/general.rst
+++ b/docs/en/rst/api/core/v1/general.rst
@@ -110,9 +110,11 @@ There are two ways to authenticate yourself:
 
 You can specify ``Bugzilla_api_key`` or simply ``api_key`` as an argument to
 any call, and you will be logged in as that user if the key is correct and has
-not been revoked. You can set up an API key by using the 'API Key' tab in the
+not been revoked. You can set up an API key by using the :ref:`API Keys tab <api-keys>` in the
 Preferences pages.
 
+API keys may also be requested via :ref:`Authentication Delegation <auth-delegation>`.
+
 **Login and Password**
 
 You can specify ``Bugzilla_login`` and ``Bugzilla_password`` or simply
diff --git a/docs/en/rst/integrating/auth-delegation.rst b/docs/en/rst/integrating/auth-delegation.rst
new file mode 100644
index 000000000..d7557e682
--- /dev/null
+++ b/docs/en/rst/integrating/auth-delegation.rst
@@ -0,0 +1,37 @@
+.. _auth-delegation:
+
+Authentication Delegation via API Keys
+######################################
+
+Bugzilla provides a mechanism for web apps to request (with the user's consent)
+an API key. API keys allow the web app to perform any action as the user and are as
+a result very powerful. Because of this power, this feature is disabled by default.
+
+Authentication Flow
+-------------------
+
+The authentication process begins by directing the user to th the Bugzilla site's auth.cgi.
+For the sake of this example, our application's URL is `http://app.example.org`
+and the Bugzilla site is `http://bugs.example.org`.
+
+1. Provide a link or redirect the user to `http://bugs.example.org/auth.cgi?callback=http://app.example.org/callback&description=app%description`
+2. Assuming the user is agreeable, the following will happen:
+   1. Bugzilla will issue a POST request to `http://app.example.org/callback`
+      with a the request body data being a JSON object with keys `client_api_key` and `client_api_login`.
+   2. The callback, when responding to the POST request must return a JSON object with a key `result`. This result
+      is intended to be a unique token used to identify this transaction.
+   3. Bugzilla will then cause the useragent to redirect (using a GET request) to `http://app.example.org/callback`
+      with additional query string parameters `client_api_login` and `callback_result`.
+   4. At this point, the consumer now has the api key and login information. Be sure to compare the `callback_result` to whatever result was initially sent back
+      to Bugzilla.
+3. Finally, you should check that the API key and login are valid, using the :ref:`rest_user_valid_login` REST
+   resource.
+
+Your application should take measures to ensure when receiving a user at your
+callback URL that you previously redirected them to Bugzilla. The simplest method would be ensuring the callback url always has the
+hostname and path you specified, with only the query string parameters varying.
+
+The description should include the name of your application, in a form that will be recognizable to users.
+This description is used in the :ref:`API Keys tab <api-keys>` in the Preferences page.
+
+The API key passed to the callback will be valid until the user revokes it.
diff --git a/docs/en/rst/integrating/index.rst b/docs/en/rst/integrating/index.rst
index 816ffe8e5..794bc0ad8 100644
--- a/docs/en/rst/integrating/index.rst
+++ b/docs/en/rst/integrating/index.rst
@@ -20,3 +20,4 @@ explains how to use the available mechanisms for integration and customization.
    templates
    extensions
    apis
+   auth-delegation