Configuring the LTPA token

LTPA tokens can be used to avoid needing a user to provide username and password credentials on each request to the mqweb server. You can configure the name of the LTPA token cookie, the expiry interval for LTPA authentication tokens, and configure whether LTPA tokens can be used by HTTP connections, by using the setmqweb command.

Before you begin

To complete this task, you must be a user with certain privileges so that you can use the dspmqweb and setmqweb commands:
  • [z/OS]On z/OS®, you must have authority to run the dspmqweb and setmqweb commands, and write access to the mqwebuser.xml file.
  • [UNIX, Linux, Windows, IBM i]On all other operating systems, you must be a privileged user.
Note: If you are using both the IBM® MQ Console, and token authentication with the REST API, the expiry interval is shared.
[V9.1.0 Jul 2018][z/OS]Attention:

Before issuing either the setmqweb or dspmqweb commands on z/OS, you must set the WLP_USER_DIR environment variable, so that the variable points to your mqweb server configuration.

To do this, issue the following command:
export WLP_USER_DIR=WLP_user_directory
where WLP_user_directory is the name of the directory that is passed to crtmqweb. For example:
export WLP_USER_DIR=/var/mqm/web/installation1

For more information, see Create the mqweb server.

About this task

When users log in to the IBM MQ Console, an LTPA token is generated. If you use token based authentication with the REST API, an LTPA token is generated when the user logs in using the /login REST API resource with the HTTP POST method. This token is returned in a cookie. The token is used to authenticate the user without the user being required to log in again with their user ID and password, until the token expires. The default expiry interval is 120 minutes.
The name of the cookie that includes the LTPA token varies by platform:
  • [MQ Appliance]On the IBM MQ Appliance, the LTPA token is LtpaToken2. This value cannot be changed.
  • [UNIX, Linux, Windows][z/OS]By default, on all other platforms, the name of the cookie that includes the LTPA token starts with LtpaToken2, and includes a suffix that can change when the mqweb server is restarted. This randomized cookie name allows more than one mqweb server to run on the same system. However, if you want the cookie name to remain a consistent value, you can specify the name that the cookie has by using the setmqweb command.

[UNIX, Linux, Windows][z/OS][IBM i]If you enable both the HTTP and HTTPS ports, an LTPA token that is issued for an HTTPS request can be reused for an HTTP request. This behavior is disabled by default, but you can enable this behavior by using the setmqweb command.

Procedure

  • View the current expiry of the LTPA token, the name of the LTPA token cookie, and whether the LTPA token can be used for HTTP requests by using the following command:

    dspmqweb properties -a

    • The ltpaCookieName field shows the name of the LTPA token cookie. If you have not set a cookie name, the value of this property is LtpaToken2_${env.MQWEB_LTPA_SUFFIX} on UNIX, Linux®, and Windows , or LtpaToken2_${httpsPort} on z/OS, . The variable after the LtpaToken2_ prefix is used by the mqweb server to generate a unique name for the cookie. You cannot set this variable, but you can change the ltpaCookieName to a value of your choosing.
    • The ltpaExpiration field shows the LTPA token expiry time.
    • The secureLtpa field is set to false if LTPA tokens can be used by HTTP requests.

    For more information, see dspmqweb.

  • Configure the LTPA token expiry:
    • Set the LTPA token expiry by entering the following command:

      setmqweb properties -k ltpaExpiration -v time

      where time specifies the time, in minutes, before the LTPA token expires and the user is logged out.

    • Reset the LTPA token expiry to the default value of 120 minutes by entering the following command:

      setmqweb properties -k ltpaExpiration -d

  • [UNIX, Linux, Windows][z/OS] Configure the LTPA token cookie name:
    • Set the LTPA token cookie name by entering the following command:

      setmqweb properties -k ltpaCookieName -v name

      where name specifies a unique name for the LTPA token cookie.

    • Reset the LTPA token cookie name to the default, where a prefix of LtpaToken2_ is followed by random characters, by entering the following command:

      setmqweb properties -k ltpaCookieName -d

  • [UNIX, Linux, Windows][z/OS] Configure whether the LTPA token can be used by HTTP connections by entering the following command:

    setmqweb properties -k secureLtpa -v secure

    where secure specifies whether the LTPA token can be used by both insecure HTTP connections and secure HTTPS connections. A value of false allows both HTTP and HTTPS connections to use the same LTPA token.