Establish Outbound Secure Conversation Assertion

 
gateway90
 
The 
Establish Outbound Secure Conversation 
assertion creates a new secure outbound conversation session using the security context identifier extracted from a Security Context Token. This outbound session includes a shared secret to be used for message decoration in future message exchanges.
To learn about selecting the target message for this assertion, see Select a Target Message.
(1) Outbound secure conversation sessions are stored for each distinct authenticated-user and service URL. (2) An existing outbound session will be overwritten if a new session is created for the same authenticated-user and service URL.
Context Variables Created by This Assertion
The Establish Outbound Secure Conversation assertion sets the following context variable for the session:
outboundSC.session
Attributes of the secure conversation session can be retrieved by using the following syntax:
outboundSC.session.
<attribute>
For example, to access the session identifier, use 
${
outboundSC.session.id}
.
The attributes are described in the following table
Attribute
Description
id
The session identifier
user
The authenticated user
To access specific attributes about the user, use the syntax:
outboundSC.session.user.
<user_attribute>
providerId
The user's Identity Provider ID
id
The user's identifier
login
The user's login ID
firstName
The user's first name
lastName
The user's last name
email
The user's email address
department
The user's department
subjectDn
The user's X.509 subject DN
creation
The session creation time
expiration
The session's expiration time
scNamespace
The namespace of WS-Secure Conversation
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click 
    <target>:
     Establish Outbound Secure Conversation to 
    <service URL>
     in the policy window and select 
    Outbound Secure Conversation Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows.
    You may use context variables in every field except for "Maximum Expiry Period" and "Security Context Token". 
    Setting
    Description
    Service URL
    Enter the URL of the service that issued the Security Context Token.
    The service URL will be used with the authenticated user information to create a mapping key to map the outbound secure conversation session that has been established.
    This field is disabled when the
    This session is for use with incoming request messages
    check box is selected (the service URL is not required in this scenario).
    If the authenticated user information is unavailable, the service URL should be specified by a unique string in order to create a unique session mapping key. (This string does not need to be a real URL, but it must be unique per secure conversation session.) The following is a sample string that creates a unique service URL:
    <service_url>?sessionId=<session_identifier>
    where
    <session_identifier>
    is the identifier of the outbound secure conversation session that has been established.
    Security Context Token
    Specify the name of the context variable from which to extract the session identifier. Enter this without the "${ }" wrapper.
    The default is
    rstrResponseProcess.token
    , which is defined in the Process RSTR Response Assertion.
    This field requires that you specify the
    actual name
    of the context variable (i.e.,the name without the "${ }" wrapper), not a name that is
    resolved
    from another variable. For example, "${mySecurityToken}" is not permitted even if it contains the value "rstrResponseProcess.token".
    Client Entropy
    Specify the context variable containing the client entropy for creating a shared secret.
    The default is
    ${requestBuilder.clientEntropy}
    , which is defined in the Build RST SOAP Request Assertion.
    Server Entropy
    Specify the context variable containing the server entropy, if the RSTR response includes a server entropy.
    The default is
    ${rstrResponseProcessor.serverEntropy}
    , which is defined in the Process RSTR Response Assertion.
    Key Size
    Specify the context variable containing the key size, in bits, from the RSTR response. Enter "
    0
    " (zero) to use the default key size.
    The default value for this field is
    ${rstrResponseProcessor.keySize}
    , which is defined in the Process RSTR Response Assertion.
    Shared Secret
    Specify the context variable containing the shared secret, if the RSTR response includes a shared secret.
    The default is
    ${rstrResponseProcessor.fullKey}
    , which is defined in the Process RSTR Response Assertion.
    Session Lifetime
    Optionally set the lifetime of the secure conversation session.
    • Create Time:
      Specify the context variable containing the creation time of the session in the server.
    The default is
    ${rstrResponseProcessor.createTime}
    , which is defined in the Process RSTR Response Assertion. If left blank, the current
    Layer7 API Gateway
    time is used.
    • Expiry Time:
       Specify the context variable containing the expiry time of the session.
    The default is
    ${rstrResponseProcessor.expiryTime}
    , which is defined in the Process RSTR Response Assertion.
    If the expiry time is left blank, the
    Layer7 API Gateway
    will use the following:
    Current time + Maximum Expiry Period
    The cluster property
    outbound.secureConversation.sessionPreExpiryAge
    can be used to expire the assertion prior to the supplied expiry time; this offset can be adjusted to help prevent use of an expired session. For example, if the maximum expiry period is 20 minutes and the value of the cluster property is 5 minutes, the
    Layer7 API Gateway
    will use 15 minutes (20-5) as the final expiry period.
    Maximum Expiry Period
    Enter the maximum length of time for the session lifetime. A value of "0" (zero) means the original session expiry time is not limited.
    The original session expiry time is defined as:
    Expiry Time - Create Time
    Use System Default
    When specifying a token lifetime, select this check box to use the system default, as defined by the
    outbound.secureConversation.defaultSessionDuration
    cluster property. The default value for this property is
    2
    hours.
    [
    This session is for use with incoming request messages
    ]
     
     
    Select this check box if this secure conversation session will be used with inbound request messages. This will allow the Security Token Service (STS) to "impersonate" that session user. Select this check box only if it is necessary to do so and only if the target STS is trusted.
    Sharing a secure conversation session for inbound and outbound traffic is not secure and is not recommended. This setting is recommended only for advanced users.
    Clear this check box to not permit this session to be used with inbound secure conversation request messages. This setting is the default and the recommended setting.
    When this option is enabled, you will not be able to access the session using the Look Up Outbound Secure Conversation Session Assertion. To use this session with outbound messages, use the Require WS-Secure Conversation Assertion to validate the inbound session, then use the token from the
    inboundSC.session
    context variable with the Add Security Token Assertion for outbound decoration.
  4. Click [
    OK
    ].