Invoking message flow security using a security enabled input node

You can invoke the message flow security manager by configuring a security enabled input node.

The following diagram shows an example message flow and gives an overview of the sequence of events that occur when an input message is received by a security enabled input node in the message flow:

Diagram showing the sequence of events that occur when a message arrives at a security enabled input node in a message flow.

For information about the security-enabled message flow nodes, see Message flow security overview.

The following steps explain the sequence of events that occur when a message arrives at a security enabled input node in the message flow. The numbers correspond to those in the preceding diagram:
  1. When a message arrives at a security enabled input node (MQ, HTTP, or SOAP), the presence of a security profile associated with the node indicates whether message flow security is configured. SOAP nodes can implement some WS-Security capabilities without using the integration node's security manager; for more information, see Implementing WS-Security. The integration server's security manager is called to read the profile, which specifies the combination of propagation, authentication, authorization, and mapping to be performed with the identity of the message. If an external security provider (Policy Decision Point or PDP) is to be used for one or more of these functions, the security profile specifies details of the provider to be used. If locally-stored credentials are to be used for authentication, the profile sets Local authentication and specifies the local credentials alias for the credentials in the independent integration server's vault. For more information, see Authenticating incoming requests by using credentials stored in the vault.

    You can create security profiles by using the Policy editor, as described in Creating policies with the IBM App Connect Enterprise Toolkit. You then deploy the policy to the integration server where your associated message flows are deployed.

  2. If a security profile is associated with the node or message flow, the security enabled input node extracts the identity information from the input message (based on the configuration on the node's Security properties page) and sets the Source Identity elements in the Properties folder. If the security tokens cannot be successfully extracted, a security exception is raised.

    If you require a SOAPInput node to use the identity in the WS-Security header (rather than an underlying transport identity), you must also define and specify an appropriate policy set and bindings for the relevant token profile. For more information, see Policy sets.

    For HTTP and MQ input nodes, the Security properties page is used to configure the extraction of the identity. This defaults to Transport Default. For example, an HTTPInput node extracts a username and password from the HTTP BasicAuth header. The Security properties page allows the Identity token type and its location to be explicitly configured to control the extraction. This source identity information can be in a message header, the message body, or both.

    For information about the tokens that are supported by each node, see Identity.

  3. If authentication is specified in the security profile, the security manager either calls the configured security provider to authenticate the identity, or, if Local authentication has been configured, it authenticates the identity against the credentials that are held in the integration server's vault. A failure results in a security exception being returned to the node. The security providers that are supported by IBM Integration for authentication are LDAP, a WS-Trust v1.3 compliant Security Token Service (such as TFIM V6.2) and TFIM V6.1.

    A security cache is provided for the authentication result, which enables subsequent messages (with the same credentials) arriving at the message flow to be completed with the cached result, provided that it has not expired.

    For information about configuring an independent integration server to enforce authentication on all HTTP and SOAP input nodes, see Configuring authentication for all HTTP and SOAP input nodes on an integration server.

  4. If identity mapping is specified in the security profile, the security manager calls the configured security provider to map the identity to an alternative identity. A failure results in a security exception being returned to the node. Otherwise, the mapped identity information is set in the Mapped Identity elements in the Properties folder.

    The security providers that are supported by IBM Integration for identity mapping are a WS-Trust V1.3 compliant Security Token Service (such as TFIM V6.2) and TFIM V6.1.

    A security cache is provided for the result of the identity mapping.

    Alternatively, you can use a SecurityPEP node at any point in the message flow to map the identity that was authenticated at the security enabled input node. For more information, see Invoking message flow security using a SecurityPEP node.

  5. If authorization is specified in the security profile, the security manager calls the configured security provider to authorize that the identity (either mapped or source) has access to this message flow. A failure results in a security exception being returned to the node.

    The security providers that are supported by IBM Integration for authorization are LDAP, a WS-Trust V1.3 compliant Security Token Service (such as TFIM V6.2) and TFIM V6.1.

    A security cache is provided for the authorization result.

    Alternatively, you can use a SecurityPEP node at any point in the message flow to authorize the identity that was authenticated at the security enabled input node. For more information, see Invoking message flow security using a SecurityPEP node.

  6. When all security processing is complete, or when a security exception is raised by the message flow security manager, control returns to the input node.

    When a security exception is returned to the security enabled input node, it performs the appropriate transport handling and ends the message flow transaction. For example, an HTTPInput node returns an HTTP header with a 401 HTTP response code, without propagating to an output terminal. A SOAPInput node returns a SOAP Fault, reporting the security exception. Alternatively, if the Treat security exceptions as normal property is set on the security enabled input node, a security exception is propagated to the node's Failure terminal. The security enabled input node propagates to its Out terminal only if all the configured operations in the associated security profile complete successfully.

  7. The message, including the Properties folder and its source and mapped identity information, is propagated down the message flow.
  8. At subsequent nodes in the message flow an identity might be required to access a resource such as a database. The identity used to access such a resource is a proxy identity, an identity configured for the specific resource by using the mqsisetdbparms command.
  9. When you are developing a message flow you can use the identity fields in the Properties folder for application processing (for example, identity-based routing or content building based on identity). Also, as an alternative to invoking mapping through a WS-Trust V1.3 enabled STS (such as TFIM V6.2) or TFIM V6.1, you can set the mapped identity fields in a compute node, such as a Compute, JavaCompute, or Mapping node.
  10. When the message reaches a security enabled output or request node (MQOutput, HTTPRequest, SOAPRequest, or SOAPAsyncRequest), a security profile (with propagation enabled) associated with the node indicates that the current identity token is to be propagated when the message is sent.

    If the security profile indicates that propagation is required, the mapped identity is used. If the mapped identity is not set, or if it has a token type that is not supported by the node, the source identity is used. If no identity is set, or if neither the mapped nor source identity has a token type that is supported by the node, a security exception is returned to the node.

    SOAP nodes also require the appropriate policy set and bindings for the token profile to be associated with the node.

    If you want to include a security token in the message that is issued at an output node, and if the output node is not able to propagate that type of token, you can use a compute node (before the output node) to put the token from the properties tree into the relevant message location.

    For information about the tokens that are supported by each node, see Identity and security token propagation.

  11. The propagated identity is included in the appropriate message header when it is sent.