Authentication

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

In this topic:

Overview

You can sign in using the following methods:

Back to top

Restricted REST API access

You can configure your site and spaces to require API key authorization for direct REST API access.

If you are authenticated as a regular user, as opposed to an API key, REST API requests will be rejected.

To set up restricted REST API access:

1. Set the following parameter at the space or site level: RESTRICT_REST_API_TO_API_KEYS_ONLY.

2. The ALM Octane interface and other standard UI clients, such as QoT, are excluded from the restricted access and will continue allowing user authentication access even if the above parameter is activated. To change how the other UI clients can be accessed, configure the following site/space parameter: CLIENT_TYPES_ALLOWED_TO_ACCESS_REST_API.

For details on working with parameters, see Configuration parameters.

Back to top

JSON authentication

JSON authentication uses the sign_in resource.

This resource sets the authentication cookies required for future requests.

{ 

     "user": "<username>", 

     "password": "<password>" 

}

{ 

     "client_id": "<client_id>", 

     "client_secret": "<client_secret>" 

}

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.

The basic authentication result is cached for 2 minutes. Subsequent requests are then validated against the cache. The cache period is configurable by the BASIC_AUTHENTICATION_CACHE_TTL_SECONDS site parameter.

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 ALM 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 ALM Octane.

Step 1 - Generate an identifier

The integrated tool sends a request with the following content:

{ 

     "id": "<identifier>", 

     "authentication_url": "<url>" 

}

{ 

     "id": "98f5d0cf-7289-4ec2-…", 

     "authentication_url": "http://acme.net:8080/authentication/store_tool_token?id=98f…" 

}

Step 2 - Perform a browser authentication

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

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 ALM 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. In case of SSO authentication, provide the the same user name that was sent in the SAML assertion from the IDP. The use of the same user name is essential for maintaining a secure environment.

{ 
  "access_token": "<access token>", 
  "id": "<id>", 
  "cookie_name": "<cookie name>" 
} 

For example:

{ 
  "access_token": "THIgSzVsGHJ9p3YeG33...Le8U0VeF3T6DxPbv-9DAzU_RjPg..", 
  "id": "123456", 
  "cookie_name": "LWSSO_COOKIE_KEY" 
} 

Back to top

OAuth 2.0 authentication for API keys

Available in versions: 24.3 and later

ALM Octane supports the OAuth 2.0 protocol for creating access tokens and validating them. OAuth 2.0 provides more robust security and greater flexibility than static API tokens.

Configure ALM Octane for OAuth 2.0 federated identity authentication when your organization requires its tools to work with API keys that are authenticated in your organization's SSO system.

OAuth 2.0 Token Exchange mechanism

The externally authenticated API key flow is a two-step process.

1. Prerequisite - Authorization

   Because authorization is performed internally in ALM Octane, the externally authenticated API key must have a role inside ALM Octane; it must be connected to either a user or an API key in ALM Octane.

   The connection is performed by name. This means that the API key in the OAuth authorization server must have the same name as a user or an API key in ALM Octane, or that the data returned by the authorization server must specify the same name.

2. Authentication

   ALM Octane uses the OAuth 2.0 Token Exchange mechanism defined by RFC 8693.

   

   The OAuth 2.0 Token Exchange mechanism works as follows:

   Step	Description
   1	An authorization request is issued to the OAuth 2.0 authorization server using whichever OAuth grant type is appropriate.
   2	An access token is received from the OAuth 2.0 authorization server that contains a claim which identifies the ALM Octane user or API key by name. The claim can be included in the access token if the access token is a JWT. Otherwise, the claim must be obtainable using the OAuth 2.0 authorization server’s UserInfo endpoint.
   3	A token exchange request (RFC 8693, Request) is issued to the ALM Octane token endpoint using: grant_type - “urn:ietf:params:oauth:grant-type:token-exchange” subject_token - The obtained access token. subject_token_type - “urn:ietf:params:oauth:token-type:access_token”
   3a	ALM Octane issues an HTTP GET request to the OAuth 2.0 authorization server’s .well-known/openid-configuration endpoint.
   3b	The OAuth 2.0 authorization server replies with JSON containing the OAuth2/OpenID metadata. ALM Octane caches this metadata for future use.
   3c	ALM Octane examines the metadata and obtains the jwks_uri value. ALM Octane makes an HTTP GET request to the OAuth 2.0 authorization server’s JWKS URI endpoint.
   3d	The OAuth 2.0 authorization server replies with JSON containing the JW KeySet (JWKS). ALM Octane caches the key set for future use.
   3e	ALM Octane examines the received subject_token.
   3e i	If the subject_token format is JWT, ALM Octane verifies the signature of the JWT using the JWKS from the OAuth authorization server. Provided that the signature is valid, ALM Octane obtains a claim value from the JWT for use as the ALM Octane user name value. Proceed to step 3f.
   3e ii	If the subject_token format is opaque, ALM Octane makes a UserInfo request to the OAuth 2.0 authorization server using the userinfo_endpoint value from the server’s metadata.
   3e iii	The OAuth 2.0 authorization server replies with JSON containing the UserInfo result. ALM Octane obtains a claim value from the UserInfo result to use as the ALM Octane user name value. Proceed to step 3f.
   3f	ALM Octane issues a new access token containing the ALM Octane user name obtained in step 3e.i or 3e.iii.
   4	ALM Octane returns the newly-issued access token (created in step 3f) to the requesting client.
   5	The requesting client uses the ALM Octane-issued access token to make one or more ALM Octane API calls.

To configure OAuth 2.0 access keys:

1. Activate and configure federated identity authentication.

   1. Prerequisites.

      When upgrading from ALM Octane 24.1 or earlier, you must perform the following:

      Item	Details
      osp-config folder	Replace the ../repo/conf/osp-config/ folder with the ../repo/conf/osp-config.new/ folder. To do this: Make a back up of the existing ../repo/conf/osp-config folder. Rename the ../repo/conf/osp-config.new folder to ../repo/conf/osp-config.
      sso.conf file	Merge the existing sso.conf file with the sso.conf.new file.

   2. In the sso.conf file, go to the token-exchange section, set token-exchange-enabled = true, and configure the token exchange settings. For details, see Modify site settings.

   3. Restart ALM Octane.

2. Register an API key in ALM Octane and assign it a role.

   Create an API key to authenticate using a federated client ID. You must register this API key separately in each shared space that you want to access.

   The same API key can be registered in several shared spaces.

   For details on setting up API access, see API access.

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.

Example

POST http[s]://<server>:<port>/authentication/sign_out

HTTP/1.1 200 OK

Cache-Control: no-cache, max-age=0 Pragma: no-cache

Content-Length: 0

Server: Jetty(9.1.3.v20140225)

Back to top

See also:

• REST API basics
• How to work with the REST API
• Common flows and ER diagrams