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.
- 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.
- REST
- SOAP
Prerequisites
- 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.
Property label | Property name | Required | Description | Data type |
---|---|---|---|---|
Title | title | Yes | The title of the policy. The default value is |
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:
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
|
string |
Token Version | tokenVersion | Yes | The version of the LTPA token. Select from the following values:
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:
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 |
integer |
Example
- ltpa-generate:
title: ltpa-generate
tokenVersion: WebSphereVersion2
tokenOutput: in-cookie-header
tokenExpiry: 600
key: 'my-first-ltpa-key:1.0.0'
Errors
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.
- 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 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.