Generate LTPA Token (ltpa-generate)

Use the Generate LTPA Token security policy in IBM® API Connect to generate a Lightweight Third Party Authentication (LTPA) token.

Restriction:

The Generate LTPA Token policy is deprecated and is not supported in API Connect releases later than Version 5.
The Generate LTPA Token policy can be used only with the DataPower® Gateway.

About

Lightweight Third Party Authentication (LTPA) is an IBM protocol that provides a cookie or binary security token based authentication mechanism in WebSphere® Application Server. It supports single sign-on (SSO) technology, and is intended for distributed, multiple application server and machine environments.

Apply the Generate LTPA Token policy to your assembly so that your API can securely authenticate with applications or services that are hosted onWebSphere Application Server. At run time, the LTPA token that is generated by the policy is sent to the WebSphere Application Server back-end services, either in an HTTP cookie header (the default option), or for SOAP and XML payloads the token is wrapped in a WS-Security header inside a SOAP message.

Note: Lotus® Domino® (Domino) token types and keys are not supported in IBM API Connect. However, you can configure Lotus Domino to accept a WebSphere Application Server LTPA token, and then a Generate LTPA Token policy can be used to authenticate with Lotus Domino.

You can attach this policy to the following API flows:

REST
SOAP

Prerequisites

The following prerequisites apply:

Before you can apply a Generate LTPA Token policy to your API definition, an LTPA key must be imported from the LTPA peer (that is, the WebSphere Application Server) into API Manager. For more information, see LTPA keys.
The minimum level of IBM DataPower is Version 7.5.1.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.

Table 1. Generate LTPA Token policy properties
Property label	Property name	Required	Description	Data type
Title	title	Yes	The title of the policy. The default value is `ltpa-generate`.	string
Description	description	No	A description of the policy.	string
LTPA Key	key	Yes	The name of the LTPA key that you want to use to generate the LTPA token. Enter the name of the LTPA key by using one of the following syntax options: `my-ltpa-key` - entering the name with no version number means that at run time the policy selects version 1.0.0 of the LTPA key. `my-ltpa-key:2.0.0` - entering the name with a version number means that at run time that specific version of the key is used. `my-ltpa-key:latest` - entering the name with `latest` means that at run time the policy selects the latest version of the LTPA key to use. Select the LTPA key from the drop-down menu. Each LTPA key has a non-version specific option, for example my-ltpa-key, latest version. Select this option if you want the policy at run time to select the latest version of the LTPA key to use. Otherwise, select a specific version. Note: The automatic version selection feature relies on the LTPA key being configured with a version number that conforms to the version.release.modification version numbering scheme.	LTPAKey
Authenticated User Name	authenticatedUserName	Yes	The runtime variable that contains the authenticated user name. The LTPA token is generated with this property as the user. For example, if the API is configured with a basic authentication security definition, then the authenticated user name can be specified as `$(client.app.id)`. If the API is configured with an OAuth security definition, then the authenticated user name can be specified as `$(oauth.resource-owner)`. Alternatively, before the Generate LTPA Token policy, you can configure a set-variable policy to set a runtime variable with a particular user name, and then specify this runtime variable as the authenticated user name.	string
Token Version	tokenVersion	Yes	The version of the LTPA token. Select from the following values: WebSphereVersion1 WebSphereVersion1-FIPS WebSphereVersion2 WebSphere70Version2 The default value is `WebSphereVersion2`.	string
Token Output	tokenOutput	Yes	Define where in the output source the policy should place the generated LTPA token. Select from the following options: In Cookie Header In WSSec Header¹ The default option is In Cookie Header. Note: In WSSec Header should be selected only if the message has an XML or SOAP media type.	enum
Token Expiry	tokenExpiry	Yes	The length of time (in seconds) that is added to the current date and time, in which the LTPA key is considered valid. The default value is `600`.	integer

Example

- ltpa-generate:
    title: ltpa-generate
    tokenVersion: WebSphereVersion2
    tokenOutput: in-cookie-header
    tokenExpiry: 600
    key: 'my-first-ltpa-key:1.0.0'

Errors

The following error can be thrown while the policy is being executed:

LTPAGenerateError - an error that captures all the errors that occur during the execution of the policy. Upon failure, the detailed error message is assigned to the runtime variable ltpa-generate.error-message, so it can be retrieved via catch.

If a catch is not configured, in the case of a failure the Generate LTPA Token policy returns an HTTP code 500 failure. The detailed error message can be found in the system log.

Tip: If there is an error, make the following checks:

Verify that the IBM DataPower firmware is at Version 7.5.1 or later.
Check that the password that is set in the LTPA key is correct.
If In WSSec Header is selected for the Token Output property, verify that the payload of the message contains an XML or SOAP media type.

¹ If the In WSSec Header option is selected, the following conditions apply:

If the input is XML, the policy creates a SOAP envelope, and places the LTPA token in the SOAP security header, and places the input XML in the SOAP body.
If the input is SOAP, but without a SOAP security header, the policy creates a SOAP security header and places the LTPA token in this header. The rest of the SOAP message is untouched.
If the input is SOAP and there is already a binary security token in the SOAP security header, the policy overwrites the existing token with the newly generated LTPA token. The rest of the SOAP message is untouched.