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.
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:
-
Set the following parameter at the space or site level: RESTRICT_REST_API_TO_API_KEYS_ONLY.
-
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.
JSON authentication
JSON authentication uses the sign_in resource.
This resource sets the authentication cookies required for future requests.
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.
Activate basic authentication through API
Admins can activate basic authentication by setting a parameter through a REST API request.
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" } ] }
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" }
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:
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.
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.
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.
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.
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.
-
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 codeExample: Mapping section in sso.conf filemapping{
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 codeExample: Introspect section in sso.conf fileintrospect{
enabled = true
auth-server-client-id = "oauth2-test"
auth-server-client-secret = "QCC:yToAiHsUPSe3rzDzJi7qzdfrtHyD39koi94srOkL7dDePzEoSg0Qa9V4dsrWd8OuY0dcR0l3QuA=="
}
-
-
OpenText Software Delivery Management uses the OAuth 2.0 Token Exchange mechanism defined by RFC 8693 and 7662.
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:
-
OpenText Software Delivery Management issues an HTTP GET request to the OAuth 2.0 authorization server’s .well-known/openid-configuration endpoint.
-
The OAuth 2.0 authorization server replies with JSON containing the OAuth2/OpenID metadata. OpenText Software Delivery Management caches this metadata for future use.
-
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.
-
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.
-
OpenText Software Delivery Management examines the received subject_token.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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:
-
Activate and configure federated identity authentication.
-
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:
-
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. -
-
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.
-
Restart OpenText Software Delivery Management.
-
-
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.
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.
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.
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.
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 |
|
Supported HTTP methods | POST |
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)
See also: