diff options
| -rw-r--r-- | Bugzilla/WebService/Server/REST/Resources/User.pm | 5 | ||||
| -rw-r--r-- | Bugzilla/WebService/User.pm | 66 | ||||
| -rw-r--r-- | docs/en/rst/api/core/v1/user.rst | 35 | ||||
| -rw-r--r-- | docs/en/rst/integrating/auth-delegation.rst | 6 |
4 files changed, 109 insertions, 3 deletions
diff --git a/Bugzilla/WebService/Server/REST/Resources/User.pm b/Bugzilla/WebService/Server/REST/Resources/User.pm index b9ecc21ba..7d494064d 100644 --- a/Bugzilla/WebService/Server/REST/Resources/User.pm +++ b/Bugzilla/WebService/Server/REST/Resources/User.pm @@ -67,6 +67,11 @@ sub _rest_resources { } }, }, + qr{^/whoami$}, { + GET => { + method => 'whoami' + } + } ]; return $rest_resources; } diff --git a/Bugzilla/WebService/User.pm b/Bugzilla/WebService/User.pm index 2d3f5f185..5812fbed2 100644 --- a/Bugzilla/WebService/User.pm +++ b/Bugzilla/WebService/User.pm @@ -52,6 +52,7 @@ use constant PUBLIC_METHODS => qw( offer_account_by_email update valid_login + whoami ); use constant MAPPED_FIELDS => { @@ -430,6 +431,16 @@ sub mfa_enroll { return $provider->enroll(); } +sub whoami { + my ($self, $params) = @_; + my $user = Bugzilla->login(LOGIN_REQUIRED); + return filter $params, { + id => $self->type('int', $user->id), + real_name => $self->type('string', $user->name), + name => $self->type('email', $user->login), + }; +} + 1; __END__ @@ -1084,3 +1095,58 @@ illegal to pass a group name you don't belong to. =item REST API call added in Bugzilla B<5.0>. =back + +=head2 whoami + +=over + +=item B<Description> + +Allows for validating a user's API key, token, or username and password. +If sucessfully authenticated, it returns simple information about the +logged in user. + +=item B<Params> (none) + +=item B<Returns> + +On success, a hash containing information about the logged in user. + +=over + +=item id + +C<int> The unique integer ID that Bugzilla uses to represent this user. +Even if the user's login name changes, this will not change. + +=item real_name + +C<string> The actual name of the user. May be blank. + +=item name + +C<string> The login name of the user. + +=back + +=item B<Errors> + +=over + +=item 300 (Invalid Username or Password) + +The username does not exist, or the password is wrong. + +=item 301 (Account Disabled) + +The account has been disabled. A reason may be specified with the +error. + +=item 305 (New Password Required) + +The current password is correct, but the user is asked to change +his password. + +=back + +=back diff --git a/docs/en/rst/api/core/v1/user.rst b/docs/en/rst/api/core/v1/user.rst index e27211a7f..7f835cc8a 100644 --- a/docs/en/rst/api/core/v1/user.rst +++ b/docs/en/rst/api/core/v1/user.rst @@ -378,3 +378,38 @@ and not in 'editusers' group, you will only be returned the ``id``, ``name``, returned are filtered based on your permission to bless each group. The ``saved_searches`` and ``saved_reports`` items are only returned if you are querying your own account, even if you are in the editusers group. + +.. _rest_user_whoami: + +Who Am I +-------- + +Allows for validating a user's API key, token, or username and password. +If sucessfully authenticated, it returns simple information about the +logged in user. + +**Request** + +.. code-block:: text + + GET /rest/whoami + +**Response** + +.. code-block:: js + + { + "id" : "1234", + "name" : "user@bugzulla.org", + "real_name" : "Test User", + } + +========== ====== ===================================================== +name type description +========== ====== ===================================================== +id int The unique integer ID that Bugzilla uses to represent + this user. Even if the user's login name changes, + this will not change. +real_name string The actual name of the user. May be blank. +name string string The login name of the user. +========== ====== ===================================================== diff --git a/docs/en/rst/integrating/auth-delegation.rst b/docs/en/rst/integrating/auth-delegation.rst index 403f01e2f..bff460e4a 100644 --- a/docs/en/rst/integrating/auth-delegation.rst +++ b/docs/en/rst/integrating/auth-delegation.rst @@ -12,9 +12,9 @@ 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`. +and the Bugzilla site is `http://bugzilla.mozilla.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` +1. Provide a link or redirect the user to `http://bugzilla.mozilla.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`. @@ -24,7 +24,7 @@ and the Bugzilla site is `http://bugs.example.org`. 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 +3. Finally, you should check that the API key and login are valid, using the :ref:`rest_user_whoami` REST resource. Your application should take measures to ensure when receiving a user at your |