CA API Gateway 9.1

9.4 9.1

(Non-SOAP) Validate SAML Token Assertion

The (Non-SOAP) Validate SAML Token assertion is used to validate a SAML token that was not delivered using WS-Security. This assertion will validate the Subject, Statements, Conditions, and Signatures in a SAML token that is not contained in a SOAP header.
gateway90
The (Non-SOAP) Validate SAML Token assertion is used to validate a SAML token that was not delivered using WS-Security. This assertion will validate the Subject, Statements, Conditions, and Signatures in a SAML token that is not contained in a SOAP header.
To learn about selecting the target message for this assertion, see Select a Target Message.
Add and Configure the Assertion
  1. Add the Require SAML Token Profile assertion to the policy development window as described in Add an Assertion. The SAML Token Properties appears.
  2. Complete the properties as shown below.
Edit the Assertion
  1. In the policy development window, right-click on the assertion and then select (Non-SOAP) Validate Assertion Properties. The assertion properties are displayed.
  2. Modify the tabs as necessary. Refer to the corresponding step below for information about each tab.
  3. Click [
    OK
    ] when done.
Step 1: Introduction
This step introduces the Non-SOAP Validate SAML Token properties.
Step 2: SAML Version
Specify which SAML versions will be accepted by the
API Gateway
 version 1.1, version 2.0, or any supported version.
Step 3: SAML Statement Type
Select the type of SAML statement to configure:
  • Authentication Statement: Proceed to Step 4.
  • Authorization Decision Statement: Proceed to Step 5.
  • Attribute Statement: Proceed to Step 6.
Step 4: Authentication Methods
Select the authentication methods that will be enforced by the assertion. You must choose at least one method.
Hints
:
  • Hold down the [
    Ctrl
    ] or [
    Shift
    ] keys to select multiple items at once.
  • Click [
    All
    ] to choose every available authentication method.
  • Click [
    None
    ] to quickly clear the Selected list and start again.
  • Select the Unspecified method to allow authentication by an unspecified method.
  • The Available list only displays the methods that are applicable to the SAML version chosen in Step 2 of the wizard.
In the Custom field, optionally enter any URI custom authentication methods, separated by spaces. You may reference context variables (either single- or multi-valued variables with space-separated URI values).  
The SSL/TLS Certificate Based Client Authentication method is not related to the Require SSL or TLS Transport assertion. This method refers to the original authentication, not to the current request which may or may not have used SSL. The SAML-supported authentication methods are outlined in the SAML 1.1 and 2.0 specification documents provided at http://www.oasis-open.org/
Proceed to Step 7: Subject Confirmation.
Step 5: Authorization Statement
Specify the resource that the SAML statement must describe, the resource action, and the action namespace.
  • 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, "acmeNamespace").
Proceed to Step 7: Subject Confirmation.
Step 6: Attribute Statement
Define one or more SAML attributes that must be described by the SAML statement.
  1. Click [
    Add
    ] and then complete the Edit SAML Attribute Constraints dialog:
    • Attribute Name
      : Enter the name of the attribute.
    • Attribute Namespace
      : Optionally enter a namespace for the attribute. This applies only to SAML 1.1.
    • Attribute Name Format
      : Optionally specify a URI reference that describes the format of the attribute name. Only attributes that declare this format will be accepted. This applies only to SAML 2.0.
      • 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
      : To require an exact variable match, select
      Specific Value
       and then enter a set value. To require that a particular attribute be present, but allow it to have any non-empty value rather than requiring a specific match, select the
      Allow any non-empty
       value option.When a non-empty attribute value is required, you can separately validate the attribute contents using XPath expressions, transient variables, and the Compare Expression assertion.To modify an attribute statement, select it and click [
      Edit
      ]. 
    • To delete an attribute statement, select it and click [
      Delete
      ].
  2. Click [
    OK
    ] to enter the attribute into the table. Repeat to configure additional attributes.
To modify an existing Attribute Statement, select it from the list and then click [
Edit
].
To remove an Attribute Statement, select it from the list and then click [
Remove
].
The attribute values validated by the Attribute Statement are available in context variables. For more information, see Context Variables Created by This Assertion in Require SAML Token Profile Assertion.
Step 7: Subject Confirmation
Select one or more subject confirmation methods that should be accepted by the
API Gateway
 and indicate whether the message signature is required as the proof material:
Holder-of-Key
This allows SAML tokens that 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 Holder-of-Key subject confirmation method currently requires that the request ticket's "SubjectConfirmation" element contain a "KeyInfo" element that contains a complete copy of the Subject's X.509 certificate. Any other form of Holder-of-Key ticket will be rejected by the
API Gateway
.
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, and the signing certificate is the Subject certificate. Or,
  • The request arrived over SSL/TLS with client certificate authentication, and the client certificate exactly matches the Subject certificate.
Sender Vouches
This allows SAML tokens that 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
 will require that the sender, presumably different from the subject, vouches for the verification of the subject.
The Sender Vouches subject confirmation method is typically used only in a SAML identity bridging policy.
Three conditions must be met in order to use the Sender Vouches confirmation method:
  • An existing trust relationship with the sender ( "Attesting Entity") must be configured in the 
    API Gateway
    . To do this, import the sender's certificate, configured as a "SAML Attesting Entity" certificate, into the Trust Store. For more information, see Manage Certificates.
  • The SAML ticket used by the SAML token must be bound to the request message by one of the following methods:
    • Send the request over SSL using the sender certificate as the SSL client certificate, OR
    • If SSL is not used, then the SAML ticket needs to be bound to the message with a WSS signature. One complication here is that the SAML ticket does not necessarily contain or refer to the sender certificate; it usually contains or refers to the subject certificate and, assuming that the ticket is signed, contains or refers to the certificate of the ticket issuer. In this method, therefore, the WSS signature must cover both the SAML token and the relevant portions of the rest of the message that use the sender certificate as the signing certificate.  
  • The format of the request message must conform to the OASIS Web Services Security standards: SAML Token Profile 1.0 (for SAML 1.1) or SAML Token Profile 1.1 (for SAML 2.0). The
    API Gateway
     does not support references to SAML tokens that are not included with the request message.
    See the OASIS Web Services Security: SAML Token Profile 1.0 standards document.
Bearer
This allows SAML tokens that 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.
The Bearer Token subject confirmation method does not protect against an attacker modifying the message or stealing a copy of the assertion and attaching it to an unauthorized message. To protect the secrecy of the SAML token when using the Bearer subject confirmation method, be sure to select the SSL-TLS Certificate Based Client Authentication check box in Step 4 of the SAML Token Profile Wizard.
None
This allows SAML tokens that do not contain a subject confirmation method.
Not having a subject confirmation method exposes the system to various threats. To protect the secrecy of the SAML token when a confirmation method is not used, be sure to select the "SSL-TLS Certificate Based Client Authentication" option in Step 3 of the SAML Token Profile Wizard.
If SAML version 2.0 is permitted, complete the Subject Confirmation Data fields:
  • Recipient
    : This property allows the expected recipient to be configured. You may enter the name directly or enter a String context variables. Leave this field blank to allow any recipient.
  • Check Address
    : Select this check box to validate the "Address" attribute. Currently, the
    API Gateway
     only supports IPv4 addresses.
  • Check Validity Period
    : Select this check box to check the time period validity period in the request. The permissible clock skew for validation is defined by the cluster properties samlAssertion.validate.notBeforeOffsetMin and samlAssertion.validate.notOnOrAfterOffsetMin.
    If there are no validity period constraints in the request message, then there is nothing to check and validation (of the time period constraints) will always succeed.
Note that if any of the Subject Confirmation Data fields fail validation, the assertion will not fail.
Step 8: Name Identifier
Specify the name formats that are acceptable to the
API Gateway
; optionally enter a subject name qualifier:
  • Name Qualifier
    : Optionally enter a subject name identifier (for example, "www.example.com"). You may reference context variables.
  • Format
    : Select one or more subject name formats that should be accepted by the
    API Gateway
    . Select the
    Unspecified
     check box if the subject name format is not known. This will cause the
    API Gateway
     to attempt to match the subject name identifier specified in the Name Qualifier field against the user login property. If the Name Qualifier field is blank, then the
    API Gateway
     will not verify the Name Qualifier attribute value.
You can only select name formats applicable to the SAML version chosen in Step 2 of the wizard.
Step 9: Conditions
In this step, you can specify any conditions to be observed.
  • Check Assertion Validity Period
    : Select this check box to verify that the SAML token is still within its validity period, using the current
    API Gateway
     time. Clear this check box to not check the validity period within the token.
  • Maximum Expiry Time
    : Specify the maximum allowable expiry time period for the SAML token. The  will use the earlier of the expiry date or the specified period. This allows you to restrict the token's expiry date with an earlier date. (If the specified date is later than the token's expiry date, then the token's date takes priority.) Tokens that exceed the expiry time will cause policy consumption to fail and audit message code 6108 will be logged.
    The default is 0 (zero), which indicates that token expiration is not checked. The maximum allowable expiry time is 100 years.
  • Audience Restriction
    : Enter an audience restriction constraint into the field. You may reference context variables.
Step 10: Embedded Signature
Select the
Require Embedded Signature
 check box to require an embedded signature in the SAML token. An invalid signature will cause the assertion to fail.
Clear the check box if an embedded signature is not required.

Content feedback and comments