Authenticating

This section provides information about authentication, signing in, and signing out when using the ALM Octane SDKs, REST API, and OData.

Overview

You can sign in using the following methods:

Authentication method Used for Description
JSON authentication with user credentials or API access keys
  • REST API

  • SDKs

Use the sign_in resource to authenticate using user credentials or API access keys. For details, see JSON authentication (sign_in).

For details on granting API access, see the information about setting up API access in the ALM Octane User Guide.

Basic authentication
  • REST API

  • SDKs

  • OData

To use basic authentication, enable basic authentication and send a header with user credentials for each request.

For details, see Basic authentication.

Non-authenticated access
  • REST API

It is possible for your REST API to navigate to an entity URL when not yet authenticated, such as when copying a URL or sending an email with a link to an entity. After prompting for authentication, you are redirected to the details of the entity.

Specify entity-navigation as follows: 

http[s]://<hostname>/ui/entity-navigation?p=<shared_space_id>/<workspace_id>&entityType=work_item&id=<id>

After authentication, this redirects to: 

http[s]://<hostname>/ui/?p=<shared_space_id>/<workspace_id>#/entity-navigation?entityType=work_item&id=<id>

Back to top

JSON authentication (sign_in)

JSON authentication uses the sign_in resource.

This resource sets the authentication cookies required for future requests.

A sign_in may fail if there are still valid authentication cookies.

The cookies can be reset with a request to sign_out.

Content-Type header application/json
URI http[s]://<server>:<port>/authentication/sign_in
Supported HTTP methods POST
Payload for user credentials

Provide a JSON object with the credentials.

Use this type of payload to work with the API as the site admin.

{ 
     "user": "<username>", 
     "password": "<password>" 
}
Payload for API keys
{ 
     "client_id": "<client_id>", 
     "client_secret": "<client_secret>" 
}

Back to top

Basic authentication

Basic authentication can be used for ALM Octane REST API, SDKs, and OData.

You cannot use basic authentication to access the ALM Octane client.

Prerequisites
  • Activate basic authentication.

    Request that the site admin or space admin set the value of the SUPPORTS_BASIC_AUTHENTICATION configuration parameter for each space. For details, see configuration parameter SUPPORTS_BASIC_AUTHENTICATION.

  • Send an HPECLIENTTYPE header with the value ALM_OCTANE_TECH_PREVIEW in your requests to authenticate with basic authentication.

Header

Send the following in the header for each request: 

  • User name and password.

  • According to the Basic Authentication specification, send the Authorization header token with each subsequent request. This means that each request is authenticated.

    The token is based on the encoding of the user name and password, separated by a colon (:), as an octet sequence. This octet sequence is then encoded as Base64.

    Example: Authorization: Basic <token>

    For details on the Basic Authentication specification, see other external resources, such as https://en.wikipedia.org/wiki/Basic_access_authentication.

  • When using basic authentication with ALM Octane, send the LWSSO_COOKIE_KEY cookie to enhance performance. ALM Octane sends the LWSSO_COOKIE_KEY cookie in the response to each successful authentication. For details, see LWSSO_COOKIE_KEY.

Back to top

Status codes

Status Status code Description
Successful authentication 200 (OK) A cookie with the name LWSSO_COOKIE_KEY is set as a response cookie. See Authentication cookies.
Failed authentication 401 (Unauthorized) Not authenticated.

Back to top

Authentication cookies

These cookies are used for authentication: 

LWSSO_COOKIE_KEY

Upon successful authentication, authentication cookie LWSSO_COOKIE_KEY is set in the response.

Send this cookie with each subsequent request.

This timeout of the cookie is 3 hours.

Refreshing the LWSSO_COOKIE_KEY 

After the 3-hour timeout period has passed, you can extend the timeout by calling the cookie.

You can keep extending the timeout for 24 hours after original authentication, if always using the refreshed cookie sent from server.

After 24 hours, the cookie has expired, and 401 errors are issued in response to requests. Re-authenticate to continue.

You can return all cookies sent by the server in the preceding response using the "Set-Cookie" header. For details, see Resend cookies.

HPSSO_COOKIE_CSRF

The HPSSO_COOKIE_CSRF cookie is useful for preventing CSRF attacks.

The cookie can be sent as a response cookie if specified. By default, this cookie is not sent.

If specified, you must send the HPSSO-HEADER-CSRF header with the value of this cookie in subsequent requests.

To return the HPSSO_COOKIE_CSRF cookie, specify the boolean property enable_csrf with the value true in the payload:

{
     "user": "<username>",
     "password": "<password>",
     "enable_csrf": true
}

Back to top

sign_out

The sign_out resource logs the user off the session and cancels (expires) the authentication cookies.

This resource can be used for all authentication methods.

URI

/authentication/sign_out

Supported HTTP methods POST

Example

POST http[s]://<server>:<port>/authentication/sign_out
HTTP/1.1 200 OK

Set-Cookie: LWSSO_COOKIE_KEY="";Version=1;Path=/;Expires=Thu, 01-Jan-1970 00:00:00 GMT;Max-Age=0 Expires: Thu, 01 Jan 1970 00:00:00 GMT

Cache-Control: no-cache, max-age=0 Pragma: no-cache
Content-Length: 0
Server: Jetty(9.1.3.v20140225)

Back to top

See also: