diff options
Diffstat (limited to 'docs/en/rst/integrating')
| -rw-r--r-- | docs/en/rst/integrating/auth-delegation.rst | 37 | ||||
| -rw-r--r-- | docs/en/rst/integrating/index.rst | 1 |
2 files changed, 38 insertions, 0 deletions
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 |