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).

Interactive tools authentication

Interactive integrations and flows

Through an API call, interactive tools receive a unique ID from ALM Octane. The tool's end users are prompted to perform a manual authentication to ALM Octane using a browser. The interactive tool polls ALM Octane with the unique ID and the end user's username, in order to acquire the access token. For details, see Interactive integration for ALM Octane authentication.

For non-interactive tools, use JSON authentication with API keys.

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 parameters.

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

Interactive integration for ALM Octane authentication

Use the tokens API for interactive token sharing authentication. This is especially useful for accessing ALM Octane with an on-premises SSO login or SaaS federation from interactive tools such as Intelij.

Token sharing authentication uses two REST calls and a user-interactive authentication.

  • Step 1. The integrated tool submits a REST call to generate an identifier and authentication URL.
  • Step 2. The end user enters the authentication URL in a browser and performs a regular authentication, after which the browser can be closed.
  • Step 3. The integrated tool polls Octane using a second REST call to extract the token received in the authentication process (step 2). The integrated tool uses the token to access Octane.

Step 1 - Generate an identifier

The integrated tool sends a request with the following content:

Content-Type header application/json
Request URI http[s]://<server>:<port>/authentication/tokens
HTTP method POST
Response Body

Receive a unique identifier and URL for a browser login.

{ 
     "id": "<identifier>", 
     "authentication_url": "<url>" 
}
For example
{ 
     "id": "98f5d0cf-7289-4ec2-…", 
     "authentication_url": "http://acme.net:8080/authentication/store_tool_token?id=98f…" 
}
Status code 200 for successfully creating the identifier.

Step 2 - Perform a browser authentication

This end user uses the URL obtained above to log in via a browser.

URL http[s]://<server>:<port>/authentication/store_tool_ token?TENANTID=1&id=<id>

 

Open a browser, using the above URL that you received as a response in Step 1. The browser prompts you to enter your credentials. After authentication, the browser will issue a message indicating that you may close the browser.

Step 3 - Extract the token

The integrated tool polls Octane with a second REST request. This request extracts the token received in the browser authentication, using the following content:

For id use the identifier value received as a response in Step 1.

For user name, provide the same user name that you used while authenticating in the browser in Step 2. The use of the same user name is essential for maintaining a secure environment.

Content-Type header application/json
Request URI http[s]://<server>:<port>/authentication/tokens/<id>?userName=<user name>

 

HTTP method GET
Response body

A successful response returns 200 and the following body. This is the same id value received as a response in Step 1. You use this accesss_token to access Octane.

{ 
  "access_token": "<access token>", 
  "id": "<id>", 
  "cookie_name": "<cookie name>" 
} 
  • access_token – The token required for authentication. Place the <access token> value in the cookie named <cookie name> and add it to all future requests.
  • id- The interactive tool identifier.
  • cookie_name - The name of the cookie storing the token value for requests to Octane.
For example:
{ 
  "access_token": "THIgSzVsGHJ9p3YeG33...Le8U0VeF3T6DxPbv-9DAzU_RjPg..", 
  "id": "123456", 
  "cookie_name": "LWSSO_COOKIE_KEY" 
} 
Status code

200 for successfully creating the access token.

404 for a failure in creating the token for one of the following reasons:

  • The user interactive authentication from Step 2 has not completed yet.
  • The id submitted is wrong or no longer valid (see comment below table).
  • The user name submitted did not match the one used by the user in Step 2.

Note: The access token is stored in Octane until it retrieved by a tool. If it is not retrieved within 3 minutes (180 seconds), the ID will timeout and be deleted together with the associated token. To change the timeout, modify the value of the site parameter, TOOLS_ ACCESS_TOKEN_STORAGE_TTL_SECONDS, and perform a restart.

Back to top

Authentication cookies

Authentication cookies are used for storing the authentication tokens. 

The access_token cookie is used for SSO authentication, while LWSSO_COOKIE_KEY is used for all other authentication types.

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.

access_token cookie

Upon successful SSO authentication, the access_token authentication cookie is set in the response.

Refreshing the access_token cookie

The access_token cookie cannot be refreshed. The default timeout is 3 hours. After this period, a new authentication is required. The timeout may be changed by modifying the sso.oauth.authentication.timeout.seconds parameter as described in Modify site settings.

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: