Authentication

This section provides information about authentication, signing in, and signing out when using the 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.

Note: SSO and SaaS federation authentications are only supported with API keys. For details, see Set up SSO authentication.

Oauth 2.0 authentication with API access keys

REST API

To use Oauth 2.0 authentication, enable federated client authentication and send an externally authenticated API key by which the integration accessing OpenText Software Delivery Management identifies itself. For details, see OAuth 2.0 authentication for API keys.

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.

Interactive tools authentication

Interactive integrations and flows

Through an API call, interactive tools receive a unique ID from OpenText Software Delivery Management. The tool's end users are prompted to perform a manual authentication to OpenText Software Delivery Management using a browser. The interactive tool polls OpenText Software Delivery Management with the unique ID and the end user's username to acquire the access token. For details, see Interactive token sharing authentication.

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

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 Software Delivery Management 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.

Area Description
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 REST API and OData.

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

Area Description
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.

Caution: Basic authentication is not secure. Turning this parameter on reduces the security level of your data.

Note: Admins can set the parameter using a REST API request. For details, see Activate basic authentication through API.

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>

  • To enhance performance when using basic authentication, send the LWSSO_COOKIE_KEY cookie.The LWSSO_COOKIE_KEY cookie is sent 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

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 access 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 Software Delivery Management 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 Software Delivery Management.

Step 1 - Generate an identifier

The integrated tool sends a request with the following content:

Area API details
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>" 
}
Status code 200 for successfully creating the identifier.

Note: If the authentication_url in the response points to the incorrect host, validate the SERVER_BASE_URL site parameter.

Step 2 - Perform a browser authentication

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

Area API details
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 OpenText Software Delivery Management 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.

Note: By default the user name is case sensitive. To change to insensitive, set the site parameter CASE_INSENSITIVE_USER_NAME_IN_INTERACTIVE_AUTHENTICATION to true.

Area API details
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 access_token to access OpenText Software Delivery Management.

{ 
  "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 OpenText Software Delivery Management.
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 OpenText Software Delivery Management until it is 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

OAuth 2.0 authentication for API keys

The OAuth 2.0 protocol is supported for creating access tokens and validating them. OAuth 2.0 provides more robust security and greater flexibility than static API tokens.

Configure OpenText Software Delivery Management 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 access tokens received from your organization's OAuth 2.0 authorization server can be validated using any one of the following request options.

Request option Description

JWT

If the subject_token format is JWT (JSON Web Token), the signature of the JWT is verified using the JWKS from the OAuth authorization server.

For details, see 3e i in the Authentication table.

OpenID Connect UserInfo


If the subject_token format is opaque, a UserInfo request is made to the OAuth 2.0 authorization server using the UserInfo endpoint value from the server’s metadata.

For details, see 3e ii in the Authentication table.

Token introspection

If introspection is configured and enabled in the sso.conf file, an introspection request is made to the OAuth 2.0 authorization server using the token introspection protocol RFC 7662.

For details, see 3e iv in the Authentication table.

OAuth 2.0 Token Exchange mechanism

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

  1. Prerequisites - Authorization

    The following authorization prerequisites apply, depending on the validation method selected.

    • Because authorization is performed internally in OpenText Software Delivery Management, the externally authenticated API key must have a role inside OpenText Software Delivery Management: it must be connected to either a user or an API key in OpenText Software Delivery Management.

    • 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 OpenText Software Delivery Management, or that the data returned by the authorization server must specify the same name.

    • If the API key (API access) approach is used, define the API key in Settings > Spaces > API Access. For details, see Create an API access key.

      For each externally authenticated API key, create an appropriate API access entity at the space level, and set a federated client ID. The same client ID can be stored in API access entities in several spaces.

      When configuring the Set a federated client ID option:

      • The name can be different from the client ID.

      • Roles must be granted.

      • There might be a difference between the client ID used for the authentication and the client ID sent by the authorization server. Therefore, it is important to correctly configure the mapping between the OpenText Software Delivery Management fields and the authorization server response in the sso.conf file. For details, see SSO authentication settings (optional).

        Copy code
        Example: Mapping section in sso.conf file
        mapping{
           user-name = "sub"
           session-identifier = "jti"
        }
    • For token introspection validation only: The OAuth 2.0 authorization server provides a single client ID and client secret to OpenText Software Delivery Management, which are used when calling the Introspection. The client ID and secret must be stored in the sso.conf file.

      In the introspect section, enable token introspection, and add the client ID and client secret. For details, see SSO authentication settings (optional).

      Copy code
      Example: Introspect section in sso.conf file
      introspect{
         enabled = true
         auth-server-client-id = "oauth2-test"
         auth-server-client-secret = "QCC:yToAiHsUPSe3rzDzJi7qzdfrtHyD39koi94srOkL7dDePzEoSg0Qa9V4dsrWd8OuY0dcR0l3QuA=="
      }
  2. Authentication

    OpenText Software Delivery Management uses the OAuth 2.0 Token Exchange mechanism defined by RFC 8693 and 7662.

    The OAuth 2.0 Token Exchange mechanism used to authenticate.

    The 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 OpenText Software Delivery Management 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 either the UserInfo or Token Introspection endpoint.

    3

    A token exchange request (RFC 8693, Request) is issued to the OpenText Software Delivery Management 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”.

      The request must contain the Authorization header with the “Basic” scheme. The credentials are defined in the sso.conf file in the oidc section.

    Token exchange request process:

    1. OpenText Software Delivery Management issues an HTTP GET request to the OAuth 2.0 authorization server’s .well-known/openid-configuration endpoint.

    2. The OAuth 2.0 authorization server replies with JSON containing the OAuth2/OpenID metadata. OpenText Software Delivery Management caches this metadata for future use.

    3. OpenText Software Delivery Management examines the metadata and obtains the jwks_uri value. It then makes an HTTP GET request to the OAuth 2.0 authorization server’s JWKS URI endpoint.

    4. The OAuth 2.0 authorization server replies with JSON containing the JW KeySet (JWKS). OpenText Software Delivery Management caches the key set for future use.

    5. OpenText Software Delivery Management examines the received subject_token.

      1. If the subject_token format is JWT, the JWT signature is verified using the JWKS from the OAuth authorization server. Provided that the signature is valid, OpenText Software Delivery Management obtains a claim value from the JWT for use as the user name value. Proceed to step 3f.

      2. If the subject_token format is opaque, OpenText Software Delivery Management makes a UserInfo request to the OAuth 2.0 authorization server using the UserInfo endpoint value from the server’s metadata.

      3. The OAuth 2.0 authorization server replies with JSON containing the UserInfo result. OpenText Software Delivery Management obtains a claim value from the UserInfo result to use as the user name value. Proceed to step 3f.

      4. If Token Introspection validation is configured and enabled, OpenText Software Delivery Management examines the metadata and obtains the token_introspection_endpoint value. OpenText Software Delivery Management makes an HTTP POST request to the OAuth 2.0 authorization server’s Token Introspection endpoint according to RFC 7662.

      5. The OAuth 2.0 authorization server replies with JSON containing the Token Introspection result. OpenText Software Delivery Management obtains claim values from the Token Introspection result to use as the username and session identifier value. The mapping is configured in sso.conf. Proceed to step 3f.

    6. OpenText Software Delivery Management issues a new access token containing the user name obtained in step 3e i (for JWT), 3e iii (for OpenID Connect UserInfo), or 3e v (for token introspection).

    Note: Steps 3a-3d are only performed the first time a token-exchange request is made. The received data is cached and used for subsequent token exchange requests. If the data has already been obtained from the OAuth 2.0 authorization server, proceed to step 3e.

    4

    OpenText Software Delivery Management returns the newly-issued access token created in step 3f.

    5

    The requesting client uses the OpenText Software Delivery Management-issued access token to make one or more API calls.

To configure OAuth 2.0 access keys:

  1. Activate and configure federated identity authentication.

    1. Prerequisites.

      When upgrading from OpenText Software Delivery Management 24.1 or earlier, perform the following.

      Item Details
      osp-config folder

      Replace the ../repo/conf/osp-config/ folder with the ../repo/conf/osp-config.new/ folder. Do the following:

      1. Make a back up of the existing ../repo/conf/osp-config folder.

      2. 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 OpenText Software Delivery Management.

  2. Register an API key in OpenText Software Delivery Management 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.

Area API details
URI

/authentication/sign_out

Supported HTTP methods POST
Copy code
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: