Authenticate
To receive services from the ALM Platform, the application must 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 LWSSOtoken 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 the note on 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, Complex Web Application (such as an Ajax application), or Browser-Based Application authentication procedure.
See 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.
Complex Web Application Authentication
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 requests the login page.
GET /qcbin/authentication-point/login.jsp?redirect-url=http://[ui_server]:[port]/myUiResource.jsp Server returns the page.
HTTP/1.1 200 OK
At the end of the login process the server redirects to the specified redirect-url 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.
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.
Discarding 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=/