Authenticating REST requests

Introduction

By default, requests to the Fisheye/Crucible REST interface are executed as the 'anonymous' user - i.e. as though no login has occurred. You'll often need to perform requests as a particular user. There are a number of ways of supplying REST requests with authentication credentials.

Basic authentication

Basic authentication adds a header to each request which contains a Base64 encoded username/password pair. See the Perl REST Client Tutorial for an example of using basic authentication from a REST client. Basic authentication has the disadvantage that every request must contain the username and password in unencrypted text.

Trusted applications

If you are making a request from a plugin inside another Atlassian application, you can add Trusted Applications headers to the request, by using the SAL RequestFactory service to create a request and calling addTrustedTokenAuthentication() to add the Trusted Application headers. Then if Fisheye/Crucible has been configured to trust the application your client plugin is installed in, the call will be made as a user with the same name as the remote user, assuming a user with the same name exists.

User token login

You can use the REST Authentication Service to get a login token which you can then use in other requests. The token should be passed as a parameter named FEAUTH, e.g. http://host:port/context/rest-service/reviews-v1?FEAUTH=admin:1:ac577aa07753052c09c25b4f88fb2c15 .

The advantages of token login over basic authentication are:

• Only the login request contains your password. Further requests just contain the token, which does not contain your password.
• A token can be revoked by logging out of Fisheye/Crucible.
• You don't need to add headers to requests.

API token login

Some specific REST API calls, that normally require administrator credentials, can be also authenticated using an API token. The REST API token is not tied to a specific user, and can be generated for the instance in the 'Security settings' section of the admin area. See Setting the REST API token for more information. Currently the token is used only for the /rest-service-fecru/admin/repositories-v1/REPOSITORY/scan request.

Note that there is a potential problem with using authentication tokens in REST. Although session tokens are not set to expire, it is possible for users to explicitly purge all their authenticated sessions on the Fisheye/Crucible logout page. Doing that will also delete the sessions of any REST client that runs under that user's username. If further requests are made using the deleted session token, or are made for a locked out user, Fisheye/Crucible will return a 401 error.