Authenticating

This section provides information about authentication, signing in, and signing out when using the ALM Octane SDKs, REST API, and OData. Non-authenticated access is also described.

Overview

You can sign in using the following methods:

Sign-in 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 Set up API access.

Note: When ALM Octane is configured with SSO authentication, APIs should be invoked using API keys authentication only. For details on SSO authentication, see Set up SSO authentication (on-premises)

Basic authentication
  • REST API

  • SDKs

  • OData

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

For details, see Basic authentication.

Note: When ALM Octane is configured with SSO authentication, APIs should be invoked using API keys authentication only. For details on SSO authentication, see Set up SSO authentication (on-premises)

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 ALM_OCTANE_TECH_PREVIEW header with the value true 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.

The 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 resending the cookie. To resend a cookie, you send back all cookies you received from the server in the preceding response using the "Set-Cookie" header. For details, see Resend cookies.

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

After 24 hours, the cookie expires, and 401 errors are issued in response to requests. In this case, re-authenticate to continue.

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: