Configuring the extraction of an identity or security token

You can configure the SecurityPEP node or security enabled input nodes to extract the identity or security token from a message and store it in the properties tree identity fields, enabling it to be processed throughout the message flow and propagated at output or request nodes.

Before you begin

Check that an appropriate security profile exists or create a new security profile. See Creating a security profile.

About this task

If an input node or SecurityPEP node is associated with a profile that specifies a security operation (authentication, mapping, or authorization), or specifies propagation as enabled, the node can retrieve an identity or security token from the message bit stream.
  • An MQInput node, with the Identity token type security property set to Transport default, retrieves the UserIdentifier element from the message descriptor (MQMD) and puts it into the Identity Source Token element of the Properties folder. At the same time, it sets the Identity Source Type element to username and the Identity Source Issued By element to MQMD.PutApplName (the put application name).
  • An HTTPInput node, with the Identity token type security property set to Transport default, retrieves the BasicAuth header from the HTTP request, decodes it, and puts it into the Identity Source Token and Password elements in the Properties folder. At the same time, it sets the Identity Source Type element to username + Password and the Identity Source Issued By element to the HTTP header UserAgent property.
  • A SOAPInput node retrieves the appropriate tokens as defined by the configured WS-Security policy sets and bindings, or (if they are not set), the transport binding determines the token type; for example, HTTP transport is BasicAuth. The SOAPInput node then populates the identity source fields in the Properties folder with the retrieved tokens. With a Kerberos policy set and bindings, the token type is a Username containing the Service Principal Name (SPN) from the Kerberos ticket.
  • A SecurityPEP node, with the Identity token type property set to Current token, can use the token that has been extracted by an upstream input or SecurityPEP node and stored in the Properties folder.

In some cases, the information extracted from the transport headers is not set or is insufficient to perform authentication or authorization. For example, for authentication to occur, a Username + Password type token is required; however, with WebSphere® MQ, only a username is available, which means that the incoming identity has to be trusted. However, you can increase security by applying transport-level security using WebSphere MQ Extended Security Edition.

If the transport header cannot provide the required identity credentials, the information must be provided as part of the body of the incoming message. To enable the identity information to be taken from the body of the message, you must specify the location of the information by using either the Security tab on the HTTP, MQ, and SCA input nodes or the Basic tab on the SecurityPEP node, or by configuring the required policy set and bindings WS-Security profile on the SOAP node. A SOAP node with a Kerberos policy set and bindings extracts a Username token containing the Service Principal Name (SPN) of the Kerberos ticket.

Procedure

  1. In Identity Token Type, specify the type of identity token that is in the message.
    The type can have one of the following values:
    • Transport Default (on the security enabled input nodes)
    • Current token (on the SecurityPEP node)
    • Username
    • Username and password
    • X.509 Certificate
    • SAML assertion
    • Kerberos GSS v5 AP_REQ (on the SecurityPEP node)
    • LTPA v2 token (on the SecurityPEP node)
    • Universal WSSE token (on the SecurityPEP node)
    On the security enabled input nodes, the default value is Transport Default. On the SecurityPEP node, the default value is Current token, which means that the token type that exists in the identity mapped or source field in the Properties folder is used.
  2. In Identity Token Location, specify the location in the message where the identity is specified.
    This string is in the form of an ESQL field reference, XPath expression, or string literal, and must resolve to a token with the type Username, Username and password, SAML assertion, Kerberos GSS v5 AP_REQ, LTPA v2 token, or X.509 Certificate. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.).
  3. In Identity Password Location, enter the location in the message where the password is specified.
    This string is in the form of an ESQL field reference, XPath expression, or string literal, and must resolve to a string containing a password. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.). This option can be set only if the Identity Token Type is set to Username and password.
  4. In Identity IssuedBy Location, specify a string or path expression to show where (in the message) information about the issuer of the identity is held.
    This string is in the form of an ESQL field reference, XPath expression, or string literal, defining where the identity was defined. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.).

    If you leave this property blank on the security enabled input nodes, the transport header value is used (if there is one). For example, for MQ the MQMD.PutApplName value is used. If you leave this property blank on the SecurityPEP node, the WS-Trust request is sent to the STS without the optional Issuer element in the WS-Trust message.

  5. (Optional) Ensure that all input nodes share the same information by promoting the properties to the message flow.

What to do next

To enable the extraction of an identity in a security enabled input node or SecurityPEP node, select a security profile that has at least one security operation configured (authentication, mapping, or authorization) or propagation enabled:
  1. In the IBM Integration Toolkit, right-click the BAR file, then click Open with > BAR Editor.
  2. Click the Manage and Configure tab.
  3. Click the flow or node on which you want to set the security profile. The properties that you can configure for the message flow or for the node are displayed in the Properties view.
  4. In the Security Profile Name field, select a security profile.
  5. Save the BAR file.
Alternatively, you can set a security profile on the flow or the input node by using the mqsiapplybaroverride command. For example:
mqsiapplybaroverride -b barFileName -k applicationName -m 
flowName#nodeName.securityProfileName=securityProfileName
For more information, see mqsiapplybaroverride command.