CA API Gateway 9.1

9.4 9.1

Build SAML Protocol Request Assertion

The Build SAML Protocol Request assertion is used to create a SAMLP request from either a request message, response message, or a Message variable. If the request can be successfully fulfilled, a SAMLP request is returned containing one or more SAML tokens. The Evaluate SAML Protocol Response assertion is then used to evaluate the request, response, or Message variable.
gateway83
The
Build SAML Protocol Request
 assertion is used to create a SAMLP request from either a request message, response message, or a Message variable. If the request can be successfully fulfilled, a SAMLP request is returned containing one or more SAML tokens. The Evaluate SAML Protocol Response assertion is then used to evaluate the request, response, or Message variable.
2
The target message for this assertion is set within the wizard, but it may also be changed in the policy window, without using the wizard. For more information, see Select a Target Message.
To learn more about selecting a private key for this assertion, see Select a Custom Private Key.
The Build SAML Protocol Request assertion is typically used as follows in a policy:
Build SAML Protocol Request
Route via HTTP(S)
Evaluate SAML Protocol Response
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
    >:
    Build SAML Protocol Request...
     in the policy window and select
    SAML Protocol Request Wizard
     or double-click the assertion in the policy window. 
  3. Follow the wizard to complete the assertion. For details, see SAML Protocol Request Wizard below.
SAML Protocol Request Wizard
The SAML Protocol Request Wizard automatically starts when you add or edit a Build SAML Protocol Request  assertion in a policy. 
You can use context variables in many of the text fields in the wizard. These variables are evaluated at runtime as the SAML Protocol request is being constructed.
Wizard Step
Descriptions
Step 1: Introduction
Introduces the wizard.
Step 2: Target Message and SOAP Version
  • Target Message
    : Choose the target location to set the SAMLP query: Request, Response, or some Other Message Variable, with the default being samlpRequest.message. For more information on Message variables, see Context Variables. To learn how to change the message target, see Select a Target Message.
  • SOAP Version
    : Specify the SOAP version to use: 1.1, 1.2, or use version from request.
Step 3: SAML Version
  • Create a SAMLP query...:
     Choose the version of the SAML query request that will be created.
  • Request Identifier
    : Choose to have the wizard generate a request identifier or reference a context variable that contains the identifier.
  • Optional Request Attributes
    : Optionally specify a Destination URI or Consent URI.
Step 4: Issuer
(SAML 2.0 only)
Configure the Issuer attribute value. For a description of these settings, see Configure the [
Issuer
] Tab in Build SAML Protocol Response Assertion.
Step 5: SAMLP Request Type
Specify the SAMLP query request to be configured:
  • Authentication Request
    : Select this option to request assertions containing authentication statements to establish a security context at one or more replying parties. Proceed to Step 8 to configure this request type. Note: The Authentication Request option is available only when SAML 2.0 was selected in Step 3.
  • Authorization Decision Request
    : Select this option to request whether an assertion subject has permission to access the specified resources. Proceed to Step 6 to configure this request type.
  • Attribute Query Request
    : Select this option to make a query that requests the assertion subject associated with the supplied attributes. Proceed to Step 7 to configure this request type.
Step 6: Authorization Query
This step is used if you chose "Authorization Decision Request" in Step 5.
  • Resource
    : Specify the URI for the resource for which authorization is requested.
  • Action
    : Specify one or more actions for which authorization is requested.
  • Action Namespace
    : Optionally specify a URI reference representing the namespace in which the specified action should be interpreted.
  • Evidence
    : Indicate whether the wizard should generate the appropriate evidence block or whether it should obtain the evidence block from a context variable.
Step 7: Attribute Statement
This step is used if you chose Attribute Query Request.
Define the attributes that the SAML statement will include.
  1. Click [
    Add
    ] and then complete the Edit SAML Attribute Properties dialog:
    • Attribute Name
      : Enter the name of the attribute.
    • Attribute Namespace
      : Optionally enter a namespace for the attribute. This applies only to SAML 1.x.
    • 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.x.
    • 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.
    • Friendly Name
      : Optionally enter a friendly name for the attribute to be used for display purposes. This applies only to SAML 2.x.
    • Attribute Value
      : If defining your own attribute name format, enter it here. This applies only to SAML 2.x.
     
  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
].
Step 8: Name Identifier
Enter the details for the Name Identifier.
See
Configure the Name Identifier
 below for details.
Step 9: Subject Confirmation
Configure the subject confirmation method in this step.
See
Configure the Subject Confirmation
 below for details.
Step 10: Digital Signature
Select the Sign Request check box to include a digital signature in the request. Clear the check box to not include a digital signature.
A digital signature is not always required in SAML. The following are some examples where the signature may not be required:
  • When a signature is "inherited"—an unsigned assertion gains protection from a signature in the containing protocol response message.
  • The SAML requestor has obtained an assertion from the SAML authority directly, through a secure channel. In this case, the SAML authority has been verified using means other than a digital signature.
Configuring the Name Identifier
This wizard step configures the details for the Name Identifier in the SAML Protocol Request.
  1. Select the
    Include Name Identifier
     check box to include the Name Identifier in the SAML token.
    Clear the check box to not include the Name Identifier. This disables all the remaining settings in the wizard step; click [
    Next
    ] to proceed to the next step in the wizard.
  2. Select the
    Encrypt Name Identifier
     check box to encrypt the Name Identifier. This causes a <
    saml:EncryptedID
    > to be placed in the <
    saml:Subject
    > element.
    Clear the check box to not encrypt the Name Identifier. This will place a <
    saml:NameID
    > in the <
    saml:Subject
    > element.
  3. If encrypting the Name Identifier, click [
    Configure
    ] and complete the EncryptedID Encryption Properties. For more information, see Configure Encryption Settings.
    If not encrypting the Name Identifier, skip to step 4.
  4. Choose 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.
    • X.509 Subject Name
      : The Name Identifier Format URI is the X.509 Subject Name.
    • Email Address
      : The Name Identifier Format URI is the email address.
    • Windows Domain Qualified Name
      : The Name Identifier Format URI is the Windows Domain Qualified  Name.
    • Unspecified
      : Indicates that the issuer of the SAML token is not warranting that the Name Identifier value meets any particular format expectations.  
    • Custom
      : Enter a custom Name Identifier Format URI. You may specify a context variable. Ensure that the URI is valid to prevent the assertion from failing.
  5. 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 (for example, gatewayhost.acmecorp.com). It is not necessary to enter a fully-qualified hostname.
  6. For
    Name Identifier Value
    , indicate 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.
Configuring the Subject Confirmation
This wizard step configures the subject confirmation method to be used in the SAML Protocol Request.
  1. Choose the
    Subject Confirmation Method
     to be used in the issued SAML token. This allows the SAML-relying party to confirm that the message came from a system entity that corresponds to the subject in the statement or query.
    Values
    Description
    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 3 of the wizard). For such assertions, the 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
     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 one of the following options.
    • 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 results in a smaller assertion, but it requires that the recipient look up the subject certificate.
    • SecurityTokenReference using SHA1 Thumbprint
      : An SHA1 thumbprint from the certificate is included in the SAML token. Like the SK1 option above, this produces a smaller assertion, 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.
    • Recipient
      : Enter a URI that specifies the required entity or location. For example, this attribute might indicate that a resulting SAML 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.
    • Address
      : Enter the required network address or location. For example, this attribute might be used to bind a resulting SAML 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 required message ID. For example, this attribute might be used to correlate the resulting SAML token to the related SAML request. You may reference context variables.
  4. If SAML 2.0 is used and the Subject Confirmation Method is not set to "None", optionally complete 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. 

Content feedback and comments