CA API Gateway 9.1

9.4 9.1

Process SAML Authentication Request Assertion

The Process SAML Authentication Request assertion helps to simplify policies used to create a single sign-on service. This assertion can perform the following:
gateway90
The
Process SAML Authentication Request
assertion helps to simplify policies used to create a single sign-on service. This assertion can perform the following:
  • (Optional) Extract the SAML Request from a form or URL parameter and then decode it.
  • Validate that the incoming Authentication Request is valid, according to the SAML profile specifications.
    Validation Details
    The assertion will validate the following and will fail if these rules are not met:
    • <Issuer>
       is present; if 
      <Format>
       is supplied, it must be 
      urn:oasis:names:tc:SAML:2.0:nameid-format:entity
    • No SubjectConfirmation elements should be present
  • Extract key information from the Authentication Request and place them into context variables.
This assertion only supports SAML 2.0.
To learn about selecting the target message for this assertion, see Selecting a Target Message.
Context Variables Created by This Assertion
The Process Authentication Request assertion sets the following context variables. Note: The default
<prefix>
 is "authnRequest" and can be changed in the assertion properties.
Context variables created by Process Authentication Request assertion
Context variable
Description
<prefix>
.
subject
Returns the Subject of the AuthnRequest.
<prefix>
.
subject.nameQualifier
Returns the domain to qualify the Subject name.
<prefix>
.
subject.spNameQualifier
Returns the name of a Subject SP, which is used to qualify a name.
<prefix>
.
subject.format
Returns the URI of the Subject format.
<prefix>
.
subject.spProvidedId
Returns the identifier of the Subject SP.
<prefix>
.
x509CertBase64
Returns the Base64-encoded X.509 Certificate, if present in the AuthnRequest.
<prefix>
.
x509Cert
Returns the X.509 Certificate, if present in the AuthnRequest, and if it is convertable into an X.509 Certificate.
This variable can be input into the Retrieve Credentials from Context Variable assertion.
<prefix>
.
acsUrl
Returns the URL of the Assertion Consumer Service.
<prefix>
.
Id
Returns the ID of the AuthnRequest.
<prefix>
.
version
Returns the version of the request.
<prefix>
.
issueInstant
Returns the time the request was issued.
<prefix>
.
destination
Returns the destination to which this AuthnRequest was sent .
<prefix>
.
consent
Returns the consent of the AuthnRequest. If one is not available, the following value will be used:
urn:oasis:names:tc:SAML:2.0:consent:unspecified
<prefix>
.
issuer
Returns the entity which issued the AuthnRequest.
<prefix>
.
issuer.nameQualifier
Returns the domain used to qualify the Issuer name.
<prefix>
.
issuer.spNameQualifier
Returns the name of an IssuerSP, which is used to qualify a name.
<prefix>
.
issuer.format
Returns the URI of the Issuer format.
<prefix>
.
issuer.spProvidedId
Returns the identifier of the Issuer SP.
<prefix>
.
request
Returns the contents of the AuthnRequest. This is only set for HTTP bindings to allow XPath of extensions or other values.
To access the main part of this context variable as text, you must append the ".mainpart" suffix; for example:
${authnRequest.request.mainpart}
. For more information about the ".mainpart" suffix, see Transport Layer Variables.
The variables 
<prefix>.x509CertBase64
 and 
<prefix>.x509Cert
 may contain values if the <AuthnRequest> is signed. If this is the case then:
  • <prefix>.x509CertBase64
     will contain the Base64 encoded certificate from the request (if any)
  • <prefix>.x509Cert
     will contain the X.509 Certificate used to validate the request signature
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Adding an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click
    Process SAML Authentication Request
    in the policy window and select
    SAML Authentication Request Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure the dialog as follows:
    Setting
    Description
    Extract SAML Request from binding
    Select this check box to have the assertion extract the SAML Request from the incoming HTTP URL or Form parameters, based on the chosen binding (
    HTTP Post
     or
    HTTP Redirect
    ).
    Clear this check box to use the SAML Request from the body of the target message selected for this assertion. For more information, see Selecting a Target Message.
    Verify Signature
    Select this check box to have the assertion validate any signature that is present. Signature validation may use an enclosed X.509 Certificate and may attempt to look up the certificate in the Gateway's trust store.
    This check box is unavailable if
    HTTP Redirect
     is selected for
    Extract SAML Request from binding
    .
    Variable Prefix
    Enter a prefix that will be added to the context variables created by this assertion. 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 variable prefix is
    authnRequest
    .
    For an explanation of the validation messages displayed, see Context Variable Validation.
  4. Click [
    OK
    ]
    when done.

Content feedback and comments