From d8cbd5b5c59f0c66772df100a4b28d4e26450771 Mon Sep 17 00:00:00 2001 From: Dylan William Hardison Date: Fri, 22 May 2015 12:54:38 -0400 Subject: Bug 1144468: Bugzilla Auth Delegation via API Keys r=dkl,a=glob --- docs/en/rst/integrating/auth-delegation.rst | 30 +++++++++++++++++++++++++++++ docs/en/rst/integrating/index.rst | 1 + 2 files changed, 31 insertions(+) create mode 100644 docs/en/rst/integrating/auth-delegation.rst (limited to 'docs/en/rst/integrating') diff --git a/docs/en/rst/integrating/auth-delegation.rst b/docs/en/rst/integrating/auth-delegation.rst new file mode 100644 index 000000000..811da0d90 --- /dev/null +++ b/docs/en/rst/integrating/auth-delegation.rst @@ -0,0 +1,30 @@ +.. _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, they will be redirected to `http://app.example.org/callback` via a GET request + with two additional parameters: `client_api_key` and `client_api_login`. +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 ` 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 -- cgit v1.2.3-24-g4f1b