Authentication

This section provides information about authentication, signing in, and signing out when using the OpenText Core Software Delivery Platform 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 OpenText Core Software Delivery Platform 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 REST API and OData.

You cannot use basic authentication to access the OpenText Core Software Delivery Platform 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

Activate basic authentication through API

Admins can activate basic authentication by setting a parameter through a REST API request.

For a site admin:

The site admin can activate basic authentication for a specific space using the SUPPORTS_BASIC_AUTHENTICATION parameter.

The ID for the space for which you are enabling basic authentication is specified using sharedspace_id.

POST .../admin/context_parameters/

{
  "data": [
    {
      "name": "SUPPORTS_BASIC_AUTHENTICATION",
      "sharedspace_id": 2001,
      "value": "true"
    }
  ]
}

For a space admin:

The space admin can also activate basic authentication for a specific space using the parameter Authentication, with the following syntax:

PUT  .../api/shared_spaces/<space_id>/params/SUPPORTS_BASIC_AUTHENTICATION

{
    "value":"true"
}

Back to top

Interactive token sharing authentication

Use the tokens API for interactive token sharing authentication. This is especially useful for accessing OpenText Core Software Delivery Platform 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 - Generate an identifier. The integrated tool submits a REST call to generate an identifier and authentication URL.

• Step 2 - Perform a browser authentication. The end user enters the authentication URL in a browser and performs a regular authentication, after which the browser can be closed.

• Step 3 - Extract the token. The integrated tool polls OpenText Core Software Delivery Platform using a second REST call to extract the token received in the authentication process (step 2). The integrated tool uses the token to access OpenText Core Software Delivery Platform.

Step 1 - Generate an identifier

The integrated tool sends a request with the following content:

{ 

     "id": "<identifier>", 

     "authentication_url": "<url>" 

}

Step 2 - Perform a browser authentication

This end user uses the URL obtained above to log in through 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 OpenText Core Software Delivery Platform 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

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.

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:

• REST API basics
• REST API calls
• Common flows and ER diagrams