SecurityPEP node

The SecurityPEP node enables you to invoke the message flow security manager at any point in the message flow between an input node and an output (or request) node.

Message flow security enables the broker to perform end-to-end processing of an identity or security token carried in a message through a message flow. This capability enables you to configure security for a message flow, allowing you to control access based on the identity or security token associated with the message and providing a security mechanism that is independent of both transport type and message format.

The SecurityPEP node enables you to invoke the security manager even if your message flow input nodes do not support message flow security (for example, TCPIPClientInput or SAPInput nodes). If you use input nodes that do not support message flow security, or you require some processing or routing of the message before the required security operation can be identified, you can use the SecurityPEP node to invoke the message flow security.

The SecurityPEP node also enables you to invoke different aspects of security at different points in the message flow. For example, you might require authentication to occur at a security enabled input node, whereas token mapping and authorization might be required after some logic in the message flow has determined the necessary business operation. Alternatively, you might have a message flow with multiple request nodes that require SecurityPEP nodes to enable one type of security token to be mapped to another type for propagation by the request nodes.

You can use the node properties to specify the location of the security tokens in the message tree. These properties contain an XPath expression or ESQL path that defines the location of the security tokens in the message tree. The message flow security manager extracts this information from the message and sends it to the external Policy Decision Point (PDP), which uses the information for authentication, authorization, or mapping. The PDP to be used is configured by the associated security profile.

Alternatively, you can configure the SecurityPEP node to use the current tokens, which have already been extracted by an upstream input node or SecurityPEP node, and stored in the Properties folder. When the node is configured with the token type as Current token, if a mapped token exists, the mapped token is used; otherwise, the source token is used.

The SecurityPEP node must be associated with a security profile, which specifies the security operations to be enforced by the node, including authentication, authorization, and mapping. If no security profile is associated with the node, the node propagates the message to the Output terminal without enforcing any security. Security profiles are configured by the broker administrator before deploying a message flow, and are accessed by the security manager at run time. If a security profile is specified on either a message flow or a node, the profile must be available when the message flow is deployed; otherwise, a deployment error occurs.

The associated security profile also allows you to specify the external security provider to be used (LDAP, WS-Trust V1.3 STS, or TFIM V6.1), and to configure the way in which they are used. The security profile is associated with the SecurityPEP node (or its owning message flow) during deployment, by editing the Security Profile property with the Broker Archive editor.

For information about the types of security token that are supported by the SecurityPEP node, see Identity.

The SecurityPEP node propagates messages to the Out terminal only if all the configured security operations complete successfully. The input messages are propagated unmodified, apart from the population of the source identity and mapped identity (if one exists).

If any of the configured security operations are unsuccessful, the SecurityPEP node throws a security exception wrapped in a recoverable exception (unlike the security enabled input nodes), which invokes the error handling that is provided by the message flow. This enables the exception to be caught and processed. Alternatively, you can handle SecurityPEP node exceptions by wiring the node's failure terminal into specific security failure processing logic. When a security operation fails, the input messages are unmodified apart from the population of the exception list.

The SecurityPEP node is contained in the Security drawer of the palette, and is represented in the IBM Integration Toolkit by the following icon:

Message structure

You can view information about samples only when you use the product documentation that is integrated with the IBM Integration Toolkit or the online product documentation. You can run samples only when you use the product documentation that is integrated with the IBM Integration Toolkit.

When you have put an instance of the SecurityPEP node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.

All mandatory properties that do not have a default value defined are marked with an asterisk.

Configure the SecurityPEP node:

1. Optional: On the Description tab, enter a Short description, a Long description, or both. You can also rename the node on this tab.
2. On the Basic tab, set values for the properties that control the extraction of an identity or security token from a message (when a security profile is associated with the node).
   • Select an option from the Identity token type list to specify the type of identity in the incoming message tree. If you leave this option to the default (Current token), the token type that exists in the identity mapped or source field in the Properties folder is used.

     If Current token is selected, the Identity token location and Identity password location fields are disabled.

   • In Identity token location, enter the XPath expression, ESQL field reference, or string literal that specifies where, in the message, the identity or token is located. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.),

     This property is disabled if the Identity token type property is set to Current token.

   • In Identity password location, enter the XPath expression, ESQL field reference, or string literal that specifies where, in the message, the password can be found. 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 + Password.

     This property is disabled if the Identity token type property is set to Current token.

   • In Identity issuedBy location, specify an XPath expression, an ESQL field reference, or a string literal that specifies the location in the message of the issuer value. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.),

     If the associated security profile specifies a WS-Trust v1.3 STS provider (for example, TFIM V6.2) and this field is left blank, no WS-Trust Issuer.Address element is included in the WS-Trust request.

3. On the Advanced tab, set the properties to override the default settings for a WS-Trust v1.3 STS. These properties can be set only if the security profile associated with the SecurityPEP node specifies a WS-Trust v1.3 STS.
   • Use the WS-Trust Applies-To Address property to specify the Address for the /wst:RequestSecurityToken/wsp:AppliesTo element of the WS-Trust message. You can use this property to provide the URI of the service for which the security token is to be validated or issued.

     You can specify this value as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.),

     By default, this value is a URI for the fully qualified name of the message flow, in the form uri:Brokername.Integration Server Name.Message Flow Name

   • Use the WS-Trust Applies-To Service property to specify the Service Name for the /wst:RequestSecurityToken/wsp:AppliesTo element of the WS-Trust message. You can use this property to provide the Service Name of the service for which the security token is to be validated or issued.

     You can specify this value as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.),

     By default, this value is left blank, which means that the WS-Trust request will not include this element.

   • Use the WS-Trust Applies-To PortType property to specify the Port Type for the /wst:RequestSecurityToken/wsp:AppliesTo element of the WS-Trust message. You can use this property to provide the Port Type of the service for which the security token is to be validated or issued.

     You can specify this value as an ESQL field reference, an XPath expression, or a string literal. If you use a string literal, it must be enclosed in single quotes and must not contain a period (.),

For more information, see Message flow security overview and Setting up message flow security.

The terminals of the SecurityPEP node are described in the following table.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).

The Description properties of the SecurityPEP node are described in the following table.

The Basic properties of the SecurityPEP node are described in the following table. Set values for these properties to control the extraction of an identity from a message (when a security profile is associated with the node). For more information about these properties, see Identity, Configuring the extraction of an identity or security token, Message flow security overview, and Setting up message flow security.

The Advanced properties of the SecurityPEP node are described in the following table. These properties are used only if the security profile specifies a WS-Trust V1.3 STS (for example, TFIM V6.2).