Authenticating

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

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

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

For details on granting API access, see Set up API access.

Note: SSO and SaaS federation authentications are only supported with API keys. For details, see Set up SSO authentication (on-premises).

Basic authentication
  • REST API

  • 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: SSO and SaaS federation authentications are only supported with API keys. For details, see Set up SSO authentication (on-premises).

Back to top

JSON authentication

JSON authentication uses the sign_in resource.

This resource sets the authentication cookies required for future requests.

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>" 
}
Cookie

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

Status code

  • 200 - Successful authentication
  • 401 (Unauthorized) - Failed authentication

Back to top

Basic authentication

Basic authentication can be used for the ALM Octane REST API 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
  • According to the Basic Authentication specification, send the Authorization header with each request, to ensure that each request is authenticated.

    The Authorization header contains a token, 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 cookie.

Cookie

Upon successful authentication, the LWSSO_COOKIE_KEY cookie is set in the response. Although the cookie is returned, you are not required to use it.

Status code

  • 200 - Successful authentication
  • 401 (Unauthorized) - Failed authentication

Back to top

Content-Type header application/json
Request URI http[s]://<server>:<port>/authentication/tokens
HTTP method POST
Response Body
Status code 200 for successfully creating the identifier.
URL http[s]://<server>:<port>/authentication/store_tool_ token?TENANTID=1&id=<id>
Content-Type header application/json
Request URI http[s]://<server>:<port>/authentication/tokens/<id>?userName=<user name>
HTTP method GET
Response body
Status code

Authentication cookies

Authentication cookies are used for storing the authentication tokens. 

LWSSO_COOKIE_KEY cookie

Upon successful authentication, the LWSSO_COOKIE_KEY cookie 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 cookie

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: