CA API Gateway 9.1

9.4 9.1

Create SAML Token Assertion

The Create SAML Token Assertion can create and optionally sign a SAML token. Examples of when this might be useful include:
gateway90
The Create SAML Token Assertion can create and optionally sign a SAML token. Examples of when this might be useful include:
  • You need to create ad-hoc token services (i.e., receive a WS-Trust request, validate it, authenticate and authorize, and then issue a SAML token for the response)
  • You are currently using the "Attach SAML Sender-Vouches" option in the Route via HTTP(S) assertion ([Security] tab), but you need a more configurable option.
  • You are using a transport like FTP that does not presently include an option to add a SAML sender-vouches token.
The SAML token that is created is stored in the
${issuedSamlAssertion}
 context variable. This variable is made available to the Build RSTR SOAP Response Assertion to create an RSTR response message. For more information, see Working with the Security Token Service.
2
The following is an example of a SAML token in the
${issuedSamlAssertion}
 variable:
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
MinorVersion="1" MajorVersion="1"
AssertionID="SamlAssertion-87a72d52cf2716824ccb036c03f17fca"
              Issuer="gateway.acmecorp.com"
IssueInstant="2010-08-17T23:01:10.215Z"><saml:Conditions
NotBefore="2010-08-17T22:56:10.000Z"
NotOnOrAfter="2010-08-17T23:06:10.216Z"><saml:AudienceRestrictionCondition> <saml:Audience>https://saml.salesforce.com</saml:Audience> </saml:AudienceRestrictionCondition></saml:Conditions><saml:AuthenticationStatement
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"
AuthenticationInstant="2010-08-17T23:01:10.215Z"><saml:Subject><saml:NameIdentifier
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
NameQualifier="">jsmith@acmecorp.com.sso</saml:NameIdentifier> 

<saml:SubjectConfirmation><saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer 

</saml:ConfirmationMethod></saml:SubjectConfirmation></saml:Subject><saml:SubjectLocality IPAddress="10.0.12.345"/></saml:AuthenticationStatement></saml:Assertion>
To learn more about selecting a private key for this assertion, see Select a Custom Private Key.
To learn more about changing the WSS Recipient for this assertion, see Change the WSS Assertion Recipient.
Context Variables Created by This Assertion
The Create SAML Token assertion sets the following context variables.
The default <prefix> is "attrStatement" and can be changed in Step 6 of the SAML Token Creation Wizard.
Context variable
Type
Notes
<prefix>.
missingAttrNames
String
Stores a list of the missing attributes (comma separated). This variable is empty when no attributes are missing.
<prefix>.
unknownAttrNames
String
Stores a list of the unknown filter attributes (comma separated). This variable is empty when no attributes are unknown
<prefix>.
noAttributes
Boolean
Returns "true" when all configured attributes were filtered, otherwise returns "false".
<prefix>
filteredAttributes
String
Stores a list of the filtered attributes (comma separated). This variable is empty when no attributes were filtered.
<prefix>.
excludedAttributes
String
Stores a list of the excluded attributes (comma separated). This variable is empty when no attributes were excluded.
This variable applies to SAML 2.0 only.
Adding and Configuring 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 Create <
    token type
    >
    SAML Token
     in the policy window and select
    SAML Token Creation Wizard
     or double-click the assertion in the policy window.
  3. Follow the wizard to complete the assertion. For details, see SAML Token Creation Wizard.
SAML Token Creation Wizard
The SAML Token Creation Wizard automatically starts when you add or modify the Create SAML Token assertion in a policy.
Wizard Step
Description
Step 1: Introduction
Introduces the wizard.
Step 2: SAML Version
Specify the version of the SAML token to be issued: 1.1 or 2.0.
Step 3: Issuer
Configure the Issuer attribute value. The settings differ depending on the SAML version.
SAML 1.1
  • Default
    : Select this to use the subject DN from public key that corresponds to the configured private key.
  • From Template
    : Select this to customize the Issuer attribute. You may reference context variables.
SAML 2.0
For a description of these settings, see
Configure the [Issuer] Tab
 in Build SAML Protocol Response Assertion.
Step 4: SAML Statement Type
Select at least one SAML statement to issue:
  • Authentication Statement
    : This statement asserts that the subject authenticated with the identity provider at a particular time, using a particular method of authentication.
  • Authorization Decision Statement
    : This statement asserts that a subject is permitted to perform a specified action on a specified resource.
  • Attribute Statement
    : This statement is used to populate the SAML statement with specified attributes pertaining to the subject.
  • Include Authentication Context Declaration (SAML 2.0 only)
    : This statement will include an Authentication Context Declaration, if possible. Specifically, this means the generated AuthnStatement or AuthnContext will contain an AuthnContextDecl child. If this check box is not selected, then only a AuthnContextClassRef child is present.
The AuthnContextDecl element may not be present for all credential types, even if this option is enabled. This element should be present for password or X.509 credentials.
The wizard will lead you through the appropriate steps based on the statements selected.
Step 5: Authorization Statement
Specify the details for the Authorization Statement:
  • Resource
    : Enter a value for the resource that the SAML statement must describe (for example, "http://acme.org").
  • Action
    : Enter an action value for the resource (for example, "GET").
  • Action Namespace
    : Optionally enter a corresponding action namespace value (for example, "http://acme.org/ns/services").
Step 6: Attribute Statement
Define one or more SAML attributes that will be included in the SAML statement.
See
Configure the Attribute Statement
below for details.
Step 7: Name Identifier
Enter the details for the SAML Authentication Statement:
  • Name Identifier
    : Select the check box to include the Name Identifier in the SAML token.
If you choose to not include the Name Identifier, clear the check box and then click [
Next
] to proceed to the next step.
  • Format
    : Specify the format of the Name Identifier:
    • Automatic
      : The Name Identifier Format URI will be selected based on the type of credentials used to authenticate the user.
    • Unspecified
      : Indicates that the issuer of the assertion is not warranting that the Name Identifier value meets any particular format expectations.  
    • Any other
      : The Name Identifier Format URI is selected based on the option chosen.
  • Name Qualifier
    : Optionally enter a Name Qualifier template. This value determines the security or administrative domain of the subject. An example of a Name Qualifier might be the
    API Gateway
     hostname (e.g., gatewayhost.acmecorp.com). It is not necessary to enter a fully-qualified hostname.
  • Name Identifier Value
    : Specify where the value of the Name Identifier is to be retrieved:
  • From Credentials
    : The value is the user name from the credentials used to authenticate the user.
  • From Authenticated User
    : The value is the most appropriate attribute (matching the selected Format) available from the user who was authenticated.
  • From Template
    : The value is the result of evaluating the specified template. This will typically be a context variable, perhaps one resulting from an XPath (Evaluate Request XPath or Evaluate Response XPath) or from the Extract Attributes for Authenticated User assertion.
Step 8: Subject Confirmation
Configure the subject confirmation method in this step.
See Configure the Subject Confirmation  below for details.
Step 9: Conditions
Select one of the following options to restrict the validity period of the issued token to a limited time:
  • Use Default Validity Period Condition
    : Select this option to use the validity period conditions defined in the following cluster properties. This setting is the default:
samlAssertion.NotBeforeOffsetMinutes
samlAssertion.NotAfterOffsetMinutes
  • Customize Validity Period Condition
    : Select this option to set a custom validity period for this assertion only:
  • Not Before seconds in past
    : The recipient should reject the token if its current local time is earlier than the token's
    NotBefore
     time. This value sets the
    NotBefore
     time to the current time on the
    API Gateway
     minus this number of seconds.
    This is useful for deployments with known time synchronization issues (for example, two machines that need to communicate with SAML have different system clocks).
  • Not On Or After seconds in future
    : The recipient should reject the token if its current local time is later than the token's NotAfter time. This value sets the NotAfter time to the current time on the
    API Gateway
     plus this number of seconds.
  • Audience Restriction
    : Optionally specify any restrictions on the audience for the SAML token. You may specify one or more constraints, separated by a space. The constraints may be static strings or context variables (either single- or multi-valued). The variable values may themselves contain a space-separated list of strings.  
    All strings that resolve to a valid URI will be added as separate saml:Audience elements in the SAML token.
Step 10: Digital Signatures
In this step, you specify the digital signatures that the
API Gateway
 should create (if any) after the SAML token is issued.
  • Sign Assertion with an Enveloped Signature
    : If selected, the
    API Gateway
     will include an XML Digital Signature within the issued SAML token, allowing it to be used outside the context of the current request or response. This option is mainly useful in situations where the SAML token itself is the focus of the interaction (for example, in token service policies).
  • Insert Assertion into Security header in request/response
    : This option is mainly useful for Sender Vouches. If selected, the issued SAML token will be added to the SOAP Security Header in either the Request or Response. In addition to the SAML token, selecting either of the following options will cause a message-level Signature to be created and added to the Security header as well:
    • If Include Assertion in Message-level Signature is selected, the issued SAML token will be included in the Signature.
    • If Include SOAP Body in Message-level Signature is selected, the SOAP Body element will be included in the Signature.
Configure the Attribute Statement
This wizard step defines one or more SAML attributes that will be included in the SAML statement.
  1. Configure the attributes for the Attribute Statement:
    • To add an attribute, click [
      Add
      ] and then complete the dialog.
    • To modify an attribute, select it from the list, click [
      Edit
      ] and then complete the dialog.
    • To remove an attribute, select it from the list, and then click [
      Remove
      ].
  2. Complete the settings as follows:
    Setting
    Description
    Attribute Name
    Enter the name of the attribute.
    Attribute Namespace
    (SAML 1.x only)
    Optionally enter a namespace for the attribute.
    Attribute Name Format
    (SAML 2.x only)
    Optionally specify a URI reference that describes the format of the attribute name. Only attributes that declare this format will be accepted.
    • Unspecified
      : If no name format is provided, the default value of
      urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
       is used.
    • URI Reference
      : This option uses the URI
      urn:oasis:names:tc:SAML:2.0:attrname-format:uri
      .
    • Basic
      : This option uses the URI:
      urn:oasis:names:tc:SAML:2.0:attrname-format:basic
      .
    • Other
      : Select this option to define your own attribute name format in the box below.
    Attribute Value
    Optionally enter a value for the attribute.
    If Message or Element variable referenced
    Configure how to add the contents of the context variable to the Attribute element:
    • Convert to string
      : The contents will be converted to a string. This setting is the default.
    • Add as XML fragment
      : This adds the XML contents of the variable to the
      saml:AttributeValue
      .
    If variable not found
    Configure the behavior when a context variable is not found:
    • Replace variable with empty string
      : This uses an empty string in place of the variable. This setting is the default.
    • Replace expression with empty string
      : This replaces the entire expression with an empty string.
    If value resolves to empty string
    Configure empty attribute value behaviour:
    • Add empty AttributeValue
      : This adds an empty <
      saml:AttributeValue /
      >. This setting is the default.
    • Do not add AttributeValue
      : This adds the Attribute without any <
      AttributeValue
      > element.
    • Add null value AttributeValue
      : This adds a null <
      saml:AttributeValue xsi:nil="true" /
      >.
    Attribute Value Comparison
    (SAML 2.x only)
    The requestor of a SAML Protocol Attribute Query service may supply values for a requested Attribute, in this case if the attribute is returned in the response it must not contain any values not equal to the values specified in the query. Configure how incoming AttributeValue elements should be compared for an Attribute:
    • String comparison
      : The values are compared as strings; no processing is done to the values before comparison.
    • Canonicalize
      : The values are canonicalized first. This option should be selected if the values contain XML.
    When the runtime value for an attribute is multivalued, then only values matching an incoming attribute value will be added.
    Missing when empty string
    • Select this check box to treat a resolved empty string as “missing”. This allows the Attribute Statement configuration to fail the assertion if an attribute’s value cannot be resolved successfully.
    • Clear this check box to never interpret a resolved empty string as missing.
    If you need to ensure that a referenced variable is successfully resolved at runtime, set “If variable not found” to
    Replace expression with empty string
    , then select the
    Missing when empty string
     check box is selected. This can be used to fail the assertion. For example, you use LDAP to resolve context variables. However, a variable was not set because either the LDAP attribute does not exist or does not have a value. Using the settings outlined above, the AttributeValue can be declared as “missing” and the Attribute Statement configuration may choose to fail the assertion.
    Repeat if Multivalued
    Select this check box to expand multivalued context variables into multiple <saml:Attribute> values.
    Example:
    When [
    Repeat if Multivalued
    ] is selected, a context variable containing the values ["first", "second"] will result in the following attributes:
     <saml:Attribute AttributeName="myVar"   AttributeNamespace="urn:example.com:attributes">
 <saml:AttributeValue>first</saml:AttributeValue>
 </saml:Attribute>
 <saml:Attribute AttributeName="myVar" AttributeNamespace="urn:example.com:attributes">
 <saml:AttributeValue>second</saml:AttributeValue>
 </saml:Attribute>
    Conversely, if the Repeat if Multivalued check box is not selected, the values from the above context variable will be concatenated:
     <saml:Attribute AttributeName="myVar"   AttributeNamespace="urn:example.com:attributes">
 <saml:AttributeValue>first, second</saml:AttributeValue>
 </saml:Attribute>
    The
    Repeat if Multivalued
     check box is unavailable if more than one variable reference is entered into the Attribute Value field or if only a single element is referenced within a multivalued variable. The following are some examples:
    • If a single context variable is entered, the check box can be selected since the variable may be multivalued.
    • If there is any mixture of variable references and text or other variables, the check box cannot be selected.
  3. Configure the
    Fail if any Attribute is missing
     check box as required:
    • Select this check box to fail the assertion if the value of an Attribute is missing. If the assertion fails, this populates the context variable <prefix>.missingAttrNames with a list (comma separated) of attribute names.
      Exception
      : When attribute filtering is enabled, this option only fails the assertion when the attribute requested has a missing value.
    • Clear this check box to allow missing Attributes without failing the assertion.
  4. Configure the 
    Filter
     panel in the Attribute Statement as follows:
    Setting
    Description
    Filter Attribute Variables
     
    Enter a context variable (single or multivalued) of type Element or Message that will contain saml:Attribute value(s). Any other values cause a warning audit but will not fail the assertion. If supplied then only Attributes included in this variable from the list of configured Attributes will be added to the Attribute Statement.
    For SAML 2.0, the variables must be of type
    saml:Attribute
    . For SAML 1.1 they must be of type
    AttributeDesignator
    .
    Fail if unknown Attribute in filter
    Select this check box to fail the assertion if the request contains an unsupported attribute. If the assertion fails, this populates the context variable
    <prefix>.unknownAttrNames
     with a list (comma separated) of the unknown attribute names.
    Clear this check box to allow a SAML Token to be issued when there is an unknown attribute requested.
    Fail if no Attributes are added
    Select this check box to fail the assertion if either the assertion is not configured with any Attributes contained in the Filter Attribute Variables or if the values of the incoming Attributes caused configured Attributes to be filtered. This will populate the context variable
    <prefix>.noAttributes
     with true. By default, this check box is selected to comply with SAML core.
    Clear this check box to allow an empty AttributeStatement to be created.
    Fail if AttributeValue excludes Attribute
    (SAML 2.0 only)
    Select this check box to fail the assertion if:
    • Attribute in the context variable contains one or more AttributeValue elements
    AND
    • the resolved value(s) of the Attribute in this dialog at runtime does not contain any of the incoming value(s)
    This populates the context variable
    <prefix>.excludedAttributes
     with a list (comma separated) of the excluded attributes.
    Clear this check box to not fail the assertion under the above conditions.
    This setting does not apply to SAML v1.1, as an AttributeQuery in v1.1 may not include AttributeValue elements.
  5. Enter a prefix that will be added to the 
    <prefix>.missingAttrNames
     variable and to the variables references. This prefix will ensure uniqueness and will prevent the variables from overwriting each other when multiple instances of this assertion appear in a policy. The default prefix is 
    attrStatement
    .
    For an explanation of the validation messages displayed, see Context Variable Validation.
Configuring the Subject Confirmation
This wizard step configures the subject confirmation method to be used in the issued SAML token.
  1. Choose the
    Subject Confirmation Method
     to be used for the issued SAML token:
    Holder-of-Key
    The SAML token will use the Holder-of-Key subject confirmation method (with the standard URI
    urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
     or
    urn:oasis:names:tc:SAML:2.0:cm:holder-of-key
    , depending on the selected SAML version in Step 2 of the wizard). For such assertions, the
    API Gateway
     will require that the subject demonstrate possession of the private key corresponding to the public key in the Subject certificate.
    The request Subject may use one of two methods to prove that they hold this key:
    • The request includes at least one element covered by a valid WSS message signature. The signing certificate will be used as the Subject certificate. Or,
    • The request arrived over SSL/TLS with client certificate. The client certificate will be used as the Subject certificate.
    Sender Vouches
    The SAML token will use the Sender Vouches subject confirmation method (with the standard URI urn:oasis:names:tc:SAML:1.0:cm:sender-vouches or urn:oasis:names:tc:SAML:2.0:cm:sender-vouches, depending on the selected SAML version in Step 2 of the wizard). For such assertions, the
    API Gateway
     vouches for the verification of the subject.
    Bearer
    The SAML token will use the Bearer Token subject confirmation method (with the standard URI
    urn:oasis:names:tc:SAML:1.0:cm:bearer
     or
    urn:oasis:names:tc:SAML:2.0:cm:bearer
    , depending on the selected SAML version in Step 2 of the wizard). Like HTTP cookies, such assertions will always be assumed to belong to whatever message contains them, and the subject will be assumed to be the sender of the message.
    None
    The SAML token does not have a subject confirmation method.
  2. Configure the
    [Include Subject Certificate as
    ] check box as required. This is available on when the Subject Confirmation Method is "Holder-of-Key".
    Select this check box to specify that the subject's certificate (or a reference to it) will be included in the SAML token. Choose the method by which it should be included or referenced from the drop-down list:
    • Literal Certificate (X509Data)
      : The entire subject certificate is inserted into the SAML token. This increases the size of the assertion significantly, but will mean that the recipient does not have to locate the subject certificates.  
    • SecurityTokenReference using SKI
      : A Subject Key Identifier (SKI) from the certificate is included in the SAML token. This may result in a smaller token, but it requires that the recipient look up the subject certificate.
    • SecurityTokenReference using SHA1 Thumbprint
      : A SHA1 thumbprint from the certificate is included in the SAML token. Like the SK1 option above, this may result in a smaller token, but it requires that the recipient look up the subject certificate.
    Clear this check box to not include the subject's certificate (or reference to it) in the SAML token.
  3. If SAML 2.0 is used and the
    Subject Confirmation Method
     is not set to "None", optionally complete the Subject Confirmation Data section. These fields provide additional information to be used by a specific confirmation method. You may reference context variables in any of these fields.
    • Recipient
      : Enter a URI that specifies the entity or location to which an attesting entity can present the token. For example, this attribute might indicate that the token must be delivered to a particular network endpoint in order to prevent an intermediary from redirecting it someplace else. You may reference context variables.
      This must be set if configuring a SAML Web SSO profile.
    • Address
      : Enter the network address or location from which an attesting entity can present the token. For example, this attribute might be used to bind the token to particular client addresses to prevent an attacker from stealing and presenting the token from another location. You may reference context variables.
    • In Response To
      : Enter the ID of a SAML protocol message in response to which an attesting entity can present the token. For example, this attribute might be used to correlate the token to a SAML request that resulted in its presentation. You may reference context variables.
      This must be set if configuring a SAML Web SSO profile that was started with an
      AuthnRequest
      .
  4. In the
    Validity Period
     section, you can optionally define a validity period for the SAML token:
    • Not Before seconds in past
      : Select this check box and then enter the number of seconds in the past before which the subject cannot be confirmed. The default is
      120
       seconds.
    • Not On or After seconds in future
      : Select this check box and then enter the number of seconds into the future after which the subject can no longer be confirmed. The default is
      300
       seconds.
      This must be set if configuring a SAML Web SSO profile.

Content feedback and comments