CA API Gateway 9.1

9.4 9.1

Build SAML Protocol Response Assertion

gateway90
The Build SAML Protocol Response assertion places a SAML token into a SAML Protocol <Response> message and allows various attributes/elements of <Response> to be specified.
To learn about selecting the target message for this assertion, see Select a Target Message.
If you select a context variable for the target message, that variable does not need to exist already. The variable will be overwritten if it exists.
To learn more about selecting a private key for this assertion, see Select a Custom Private Key.
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
    Build SAML Protocol Response
     in the policy window and select
    SAML Protocol Response Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure each tab as necessary. Note the fields differ depending on whether SAML 2.0 or SAML 1.1 is selected. Refer to the appropriate section below for a description of each tab.
  4. Click [
    OK
    ] when done.
Configuring the [General] Tab
Configure this tab as follows:
Setting
Description
SAML Version
Select the SAML version from the drop-down list: 2.0 or 1.1.
Default: 2.0.
Sign Response
Select this check box if the response should be digitally signed.
For more information about selecting a private key for the signature, see Select a Custom Private Key.
Validate Web SSO Rules
Select this check box if you want the assertion to validate Web SSO profile rules. If any rule is broken, the assertion fails and a warning is logged. For a description of the rules validated, see Validate Web SSO Profile Rules below.
Clear this check box if the assertion will be used in situations outside of Web SSO and such validation is not desired (for example, SAML Protocol Attribute Query Responses—see Step 4 in the Evaluate SAML Protocol Response assertion).
Response Status
Status Code
Specify a response status using either of the following methods:  
  • Choose the response status from the drop-down list. By default, these responses are used:
    • SAML 1.1: Success
    • SAML 2.0: urn:oasis:names:tc:SAML:2.0:status:Success
  • Specify a context variable that will resolve to a valid status code for the SAML version at run time. You will typically use the context variable set by the Set SAML Response Status Code Assertion.
Status Message
Enter a status message to be returned in the response. This message may reference String context variables.
Status Detail
Optionally specify the status detail to be returned in the response. You must use context variables; text entry is not permitted. The variables may be concatenated or separated with a space.   
The variables may be of type Element, Message (text/xml), or String and may be multivalued.
Response Attributes
ResponseId
(SAML 1.1 only)
Enter the ID for the SAML response. May reference String context variables.
Default: <auto>. This indicates that the system will automatically fill the field if no ReponseID is entered.
ID
(SAML 2.0 only)
Enter the ID for the SAML response. May reference String context variables.
Default: <auto>. This indicates that the system will automatically fill the field if no ID is entered.
Issue Instant
Specify the IssueInstant property to be used in the response. This property contains the date and time when the response was issued. May reference String context variables.
Default: <auto>. This indicates that the system will automatically fill the field if no IssueInstant is entered.
InResponseTo
Optionally specify the InResponseTo value to be used in the response. This is an identifier to the request to which this response may correspond. May reference String context variables.
Recipient
(SAML 1.1 only)
Specify the intended recipient for this response. May be a String context variable.
Destination
(SAML 2.0 only)
Specify the URI to which the response will be sent.
Consent
(SAML 2.0 only)
Specify the Consent property. This indicates whether consent was obtained from a principal in sending the response. May reference String context variables.
Response Elements
Assertion(s)
Enter one or more context variables containing the SAML tokens to be returned in the response, in the format: ${variableName}. The variables may be concatenated or separated with a space. 
These variables may be of type Element, Message (text/xml), or String. Variables may be multivalued.
Variables of type Element are created by the Evaluate Request XPath and Evaluate Response XPath assertions in the ".elements" context variable.
EncryptedAssertion(s)
(SAML 2.0 only)
Enter one or more context variables containing the encrypted SAML tokens to be returned in the response, in the format: ${variableName}. The variables may be concatenated or separated with a space. 
These variables may be of type Element, Message (text/xml), or String. Variables may be multivalued.
Extensions
(SAML 2.0 only)
Optionally enter one or more context variables, separating them with a space.
These variables may be of type Element, Message (text/xml), or String. Variables may be multivalued.
Validate Web SSO Profile Rules
This assertion validates the following profiles rules when the Validate Web SSO Rules check box in the [
General
] tab is selected.
For SAML 2.0:
If an encrypted token is present in the
samlp:response
, then no rules relating to the enclosed
saml:assertion
 (SAML tokens) can be validated, as the
API Gateway
 cannot examine the contents of encrypted SAML tokens.
The following Web SSO profile rules are validated:
  • If the Idp (SAML Web Browser SSO Profile Identity Provider) wants to return an error, then the <
    Response
    > must not contain any assertions.
  • If the <
    Response
    > message is signed or if an enclosed assertion is encrypted, then the <
    Issuer
    > element must be present.
  • Response must contain at least one <
    Assertion
    >, the same rule above for <
    Issuer
    > applies for each assertion.
  • All assertions in the response must be from the same Identity Provider (for example, the same
    API Gateway
    ).
  • If multiple assertions are included, then each <
    Subject
    > element must refer to the same principal.
  • Any assertion issued must contain a <
    Subject
    > element with at least one <
    SubjectConfirmation
    > element containing a Method of
    urn:oasis:names:tc:SAML:2.0:cm:bearer
    .
  • The bearer <
    SubjectConfirmation
    > element must contain a <
    SubjectConfirmationData
    > element that itself must contain a Recipient attribute containing the service provider's assertion consumer service URL and a
    NotOnOrAfter
     attribute that limits the assertion.
  • It must not contain a
    NotBefore
     attribute.
  • The set of bearer assertions must contain at least one <
    AuthnStatement
    > that reflects who the principal was authenticated.
  • Each bearer assertion must contain an <
    AudienceRestriction
    > including the SP's unique identifier as the <
    Audience
    > (for example, the web site's URL)
  • If no SAML tokens are specified for the response, then the Status Code cannot be "Success", as the response that is generated must be an error.
For SAML 1.1
:
The following Web SSO rules are validated:
  • At least one SSO assertion must be included. An SSO assertion is a SAML token that has a <
    saml:Conditions
    > element with
    NotBefore
     and
    NotOnOrAfter
     attributes present, and also contains at least one or more authentication statements about the subject.
  • SAML Response must include the Recipient attribute - xsd:anyURI
  • Every subject-based statement in the assertion(s) returned to the destination site must contain a <
    saml:SubjectConfirmation
    > element. The <
    ConfirmationMethod
    > element in the <
    SubjectConfirmation
    > must be set to
    urn:oasis:names:tc:SAML:1.0:cm:bearer
    .
  • If no SAML tokens are specified for the response, then the Status Code cannot be "Success", as the response that is generated must be an error.
Configuring the [Issuer] Tab (SAML 2.0 only)
Configure this tab as follows.
Setting
Description
Add Issuer
Select this check box to add the Issuer element in the SAML Protocol response. This enables the other settings in the tab.
Include Format Attributes
Select this check box to include the Format attribute in the SAML token and then select format of the Issuer attribute:
Entity Identifier
X.509 Subject Name
Unspecified
Windows Domain Qualified Name
Email Address
Kerberos Principal Name
Name Qualifier
Enter the value for the optional NameQualifier attribute. You may reference context variables.
Issuer Value
Specify how to obtain the value of the Issuer:
  • Default
    : Select this to use the subject DN from public key that corresponds to the configured private key.
  • From Template
    : Select this to override the default by entering a custom value. You may reference context variables.
Configuring the [Advanced] tab
Select this check box to include the entire certificate chain from the signing private key when signing the response. This includes the root certificate as well as any intermediate certificates.
The chain that is included will include the full path to the CA certificate only if the corresponding private key certificate chain is complete. If it is a partial chain or if only the subject certificate is available, then selecting the check box will have no effect.
Clear this check box to use only the X.509 certificate data from the signing certificate. The rest of the certificate chain is ignored. This is the default. 

Content feedback and comments