Authentication

HCL VersionVault OSLC-CM REST APIs support both Basic Access Authentication and OAuth for authenticating users.

Customers must be prepared to answer authentication challenges when attempting to access any resource. The only resource that is not protected is the list of schema repositories when running a GET request on the Base URI. Authentication challenges are accompanied by a 401 HTTP status code.

For most purposes, basic access authentication is fine. It's simpler to use and requires no setup. This method of authentication is not secure unless you use SSL.

OAuth requires some administrator set up, but has other advantages. It's more secure since consumers do not need to know a user's ID and password. Instead, they authenticate by using an access token that is created by HCL Compass. This token is good until the server restarts and can only be used by one consumer. OAuth can also be used to authenticate over non-secure connections, although for maximum security it is recommended to always use SSL.
Note: Basic access authentication as defined in RFC2617 does not support non-ASCII user IDs. If you have users with non-ASCII user IDs, you must use OAuth authentication.

Basic Access Authentication

When using basic access authentication, you specify your user name and password as a Base64 encoded string in the Authorization HTTP request header. This authentication method is not secure unless you use SSL.

Almost all browsers support basic access authentication. If you follow a HCL Compass OSLC URI in a browser, you are by the browser for your ID and password unless you already have an active session.

Most HTTP client libraries also support basic access authentication. This example specifies a user's ID and password by using Apache HTTP Client. 
HttpClient http = new HttpClient();
   Credentials credential = new UsernamePasswordCredentials("user", "password");
   http.getParams().setAuthenticationPreemptive(true);
   http.getState().setCredentials(AuthScope.ANY, credential);

Consult the documentation of the library that you use to learn how to work with the other HTTP client libraries.

OAuth Authentication

If you use OAuth for authentication, you want to use an OAuth library to sign requests. Many open source libraries for different programming languages are available at http://oauth.net/code/.
Note: Before you begin, you must familiarize yourself with the concepts of OAuth. The Beginner's Guide to OAuth is an excellent resource. A full primer on OAuth is outside the scope of this document, but some specifics are mentioned about how to use OAuth with HCL Compass. If you use OAuth for authentication, you need to use an OAuth library to sign requests. Many open source libraries for different programming languages are available at http://oauth.net/code/.

Registering OAuth Consumers

If you want to authenticate by using OAuth, you need to register your application as an OAuth consumer.

First log in toHCL Compass web as an administrator, then select "OAuth Consumer Management" from the "Site Administration" menu. When the dialog appears, you can enter your OAuth consumer details.

Table 1.
Property Description
Consumer Name A name for your application that is displayed to users.
Consumer Key The consumer key can be any value, but it must be unique.
Consumer Secret The customer secret is the shared secret between your application and HCL Compass. Compass uses this secret to validate that requests are really from your application. You can pick any secret.
Trusted If checked, HCL Compass might share authorization with other trusted consumers.
Note: CHCL Compassalso supports the Jazz™ capability of dynamically registering OAuth consumers that are described in RootServicesSpecAddendum2. The root services URI for HCL VersionVault is documented in Base URI.

Obtaining OAuth Tokens

To get an OAuth access token, you must:
  1. Request an OAuth request token from the oslc:oauthRequestTokenURI.
  2. Redirect the user to authorize access by using the oslc:authorizationURI.
  3. Exchange the OAuth request token for an access token by using the oslc:oauthAccessTokenURI.

These OAuth URIs are properties of the oslc:OAuthConfiguration resource that is defined in the service provider catalog for each database set.

The OAuth access token allows you to make requests on behalf of a user. The access token is good until the HCL Compass server restarts.

Signing Requests

You will need an OAuth library to help you sign requests using the access token. As an OAuth provider, HCL VersionVault supports the HMAC-SHA1 signature method and accepts Authorization OAuth parameters in the header, as part of the query string, and in the request body. See OAuth 1.0a: Parameter Transmission.