Authenticate using LWSSO

Available in versions: ALM 12.5x and ALM 12.6x and later

To receive services from the ALM Platform, the application must provide an authentication token as a cookie in the request header.

One way to receive services from the ALM Platform is for the application to pass an LWSSO (Light Weight Single Sign On) cookie in the request header.

This cookie is returned from the server after the user is authenticated. This LWSSO token is self-contained. By default, the token times out after one hour of inactivity. The token cannot be reused in a new session after the session in which the token is created is closed. See General Notes and Limitations: Resend Cookies.

After authentication, open ALM Platform sessions by a POST on the site-session resource.

The authentication procedure is slightly different for different types of application. Follow the appropriate procedure for your application: Non-Web Application Authentication, Non-Web Application with Basic Authorization Header, or Browser-Based Application authentication procedure.

For details on other authentication options, see Authenticate using API keys and Authenticate using IdP.

See also the General Notes and Limitations.

Non-Web Application Authentication

Steps:

Client queries the is-authenticated resource and sends no authentication headers. This step is optional.

GET /qcbin/rest/is-authenticated

Server refuses request and returns reference to authentication point.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: LWSSO realm=http://[server]:[port]/qcbin/authentication-point

Post an authorization request with alm-authenticate.

POST /qcbin/authentication-point/alm-authenticate 

Server creates a new LWSSOtoken and returns it as LWSSO_COOKIE_KEY.

HTTP/1.1 200 OK
Set-Cookie: LWSSO_COOKIE_KEY={cookie}

The application can now access data and services using the token. At the end of the session, log off to Discard the token.

 

Non-Web Application Authentication with Basic Authorization Header

Steps:

Client queries the is-authenticated resource and sends no authentication headers. This step is optional.

GET /qcbin/rest/is-authenticated

Server refuses request and returns reference to authentication point.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: LWSSO realm=http://[server]:[port]/qcbin/authentication-point

Client sends a valid Basic Authorization header to the authentication point.

GET /qcbin/authentication-point/authenticate
Authorization: Basic ABCDE123

Server validates the Basic Authorization headers, creates a new LWSSOtoken and returns it as LWSSO_COOKIE_KEY.

HTTP/1.1 200 OK
Set-Cookie: LWSSO_COOKIE_KEY={cookie}

The application can now access data and services using the token. At the end of the session, log off to Discard the token.

Browser-Based Application Authentication

Browsers can log in using a log-in form accessed by passing the URL parameter "form-login-required" when requesting a resource.

Client requests the login page.

GET /{any resource}?login-form-required=y

For example: http://{server}:{port}/qcbin/rest/domains/{domain}/projects/{project}/defects?login-form-required=y

HTTP/1.1 401 Unauthorized
WWW-Authenticate: LWSSO realm=http://[server]:[port]/qcbin/authentication-point

The server returns the login page.

HTTP/1.1 200 OK

At the end of the login process the server redirects to the requested resource with a valid LWSSO token. The application can now access data and services using the token. At the end of the session, log off to Discard the token.

Discard the token

When work is completed, discard the token.

GET /qcbin/authentication-point/logout
Cookie: LWSSO_COOKIE_KEY={cookie}

The server removes the LWSSOtoken from the client's active cookies.

Returns HTTP/1.1 200 OK
Set-Cookie: LWSSO_COOKIE_KEY=""; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/