Process SAML Authentication Request Assertion

The Process SAML Authentication Request assertion helps to simplify policies that are used to create a single sign-on service. This assertion can perform the following:
gateway92
The
Process SAML Authentication Request
assertion helps to simplify policies that are 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 validates the following items and fails 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  Select a Target Message.
Context Variables Created by This Assertion
The Process Authentication Request assertion sets the following context variables. The default
<prefix>
is "
authnRequest
" and can be changed in the assertion properties.
Context variable
Description
<prefix>
.
acsUrl
Returns the URL of the Assertion Consumer Service.
<prefix>
.
consent
Returns the consent of the AuthnRequest. If one is not available, the following value is used:
urn:oasis:names:tc:SAML:2.0:consent:unspecified
<prefix>
.
destination
Returns the destination to which this AuthnRequest was sent.
<prefix>
.
Id
Returns the ID of the AuthnRequest.
<prefix>
.
issueInstant
Returns the time that the request was issued.
<prefix>
.
issuer
Returns the entity which issued the AuthnRequest.
<prefix>
.
issuer.format
Returns the URI of the Issuer format.
<prefix>
.
issuer.nameQualifier
Returns the domain that is used to qualify the Issuer name.
<prefix>
.
issuer.spNameQualifier
Returns the name of an IssuerSP, which is used to qualify a name.
<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 Context Variables .
<prefix>
.
subject
Returns the Subject of the AuthnRequest.
<prefix>
.
subject.format
Returns the URI of the Subject format.
<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.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 can be converted into an X.509 Certificate.
This variable can be input into the  Retrieve Credentials from Context Variable Assertion.
<prefix>
.
version
Returns the version of the request.
The following context variables are available in version 9.2 CR5 or later:
<prefix>
.
acsIndex
Returns the value of the attribute
AssertionConsumerServiceIndex
of the
AuthnRequest
element, if present.
<prefix>
.
attrcsIndex
Returns the value of the attribute 
AttributeConsumingServiceIndex
of the 
AuthnRequest
element, if present.
<prefix>
.
forceAuthn
Returns the value of the attribute
ForceAuthn
of the
AuthnRequest
element. If not provided, the default ("false") is returned as specified in the SAML core 2.0 spec.
<prefix>
.
isPassive
Returns the value of the attribute
IsPassive
of the
AuthnRequest
element. If not provided, the default ("false") is returned as specified in the SAML core 2.0 spec.
<prefix>
.
protocolBinding
Returns the value of the attribute 
ProtocolBinding
of the 
AuthnRequest
element, if present.
<prefix>
.
providerName
Returns the value of the attribute
ProviderName
of the
AuthnRequest
element, if present.
The variables 
<prefix>.x509CertBase64
 and 
<prefix>.x509Cert
 may contain values if the <AuthnRequest> is signed. If so then:
  • <prefix>.x509CertBase64
     contains the Base64 encoded certificate from the request (if any)
  • <prefix>.x509Cert
     contains 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 that is selected for this assertion. For more information, see  Select 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
    .
    Additional Attributes Required
    (available in version 9.2 CR5 and later)
    Select which of these attributes must be present in the SAML authentication request:
    AssertionConsumerServiceIndex
    AssertionConsumerServiceURL
    AttributeConsumingServiceIndex
    ProviderName
    ProtocolBinding
    Note:
    In version 9.2,
    AssertionConsumerServiceURL
    is a required attribute.
    Variable Prefix
    Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents 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 that are displayed, see "Context Variable Validation" in Context Variables.
  4. Click [
    OK
    ]
    when done.