SecurityPEP node
Use the SecurityPEP node in a message flow to invoke the message flow security manager at any point in the message flow.
- Developer
- Application Integration Suite
- Standard
- Advanced
- Adapter
This topic contains the following sections:
Purpose
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 integration node 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 integration 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 BAR 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
- XMLNSC
- SOAP
- DataObject
- XMLNS
- JMSMap
- JMSStream
- MIME
- BLOB
- XML (this domain is deprecated; use XMLNSC)
- IDOC (this domain is deprecated; use MRM)
- MRM
Using the SecurityPEP node in a message flow
For more information about how to configure this node, see Configuring the SecurityPEP node.
Terminals and properties
The terminals of the SecurityPEP node are described in the following table.
Terminal | Description |
---|---|
In | The input terminal that accepts a message for processing. |
Out | The output terminal to which the message is routed if the SecurityPEP node is associated with a security profile and if all the configured security operations complete successfully. The propagated properties folder identity elements are updated by the configured security operations. |
Failure | The output terminal to which the message is routed if there is a failure in the node; for example, if the configured security operations return an exception. |
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.
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | The node type, SecurityPEP | The name of the node. |
Short description | No | No | A brief description of the node. | |
Long description | No | No | Text that describes the purpose of the node in the message flow. |
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.
Property | M | C | Default | Description |
---|---|---|---|---|
Identity token type | No | No | None | This property specifies the type of identity
token present in the incoming message. Valid values are:
You can also specify the Username and password value to validate a RACF® PassTicket using a WS-Trust V1.3 STS such as TFIM V6.2. |
Identity token location | No | No | None | This property specifies where, in the message, the identity or security token can be found. The location is specified 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 (.), |
Identity password location | No | No | None | This property specifies where, in the message,
the password can be found. The location is specified 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 (.), This property can be set only if Identity token type is set to Username and password. |
Identity IssuedBy location | No | No | None | This property specifies an XPath expression
or ESQL path that describes the issuer of the identity or security
token. The location is specified 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 (.), This option is used when the associated security profile specifies a WS-Trust V1.3 STS provider (for example, TFIM V6.2) for authentication, mapping or authorization. In this case, when this field is left blank, no WS-Trust Issuer.Address element is sent. |
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).
Property | M | C | Default | Description |
---|---|---|---|---|
WS-Trust Applies-To Address | No | Yes | Not set | This property sets the Address for the /wst:RequestSecurityToken/wsp:AppliesTo element
of the WS-Trust message. Use this property to provide the URI of the
service for which the security token is to be validated or issued. This value can be specified 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. |
WS-Trust Applies-To Service | No | Yes | Not set | This property sets the Service Name for the /wst:RequestSecurityToken/wsp:AppliesTo element
of the WS-Trust message. Use this property to provide the Service
Name of the service for which the security token is to be validated
or issued. This value can be specified 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 does not include this element. |
WS-Trust Applies-To Port Type | No | Yes | Not set | This property sets the Port Type for the /wst:RequestSecurityToken/wsp:AppliesTo element
of the WS-Trust message. Use this property to provide the Port Type
of the service for which the security token is to be validated or
issued. This value can be specified 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 does not include this element. |
Property | M | C | Default | Description |
---|---|---|---|---|
Events | No | No | None | Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |