Retrieve SAML Browser Artifact Assertion

The Retrieve SAML Browser Artifact assertion uses the credentials in a request message to obtain a SAML Browser Artifact from a SAML Single Sign-On (SSO) endpoint. The SSO endpoint authenticates a requestor using either Basic Authentication or HTML Form POST Authentication. If authentication succeeds, the Gateway parses the redirect header and saves the "SAMLart" parameter in memory for future assertions in the same policy to use.
gateway90
The
Retrieve SAML Browser Artifact
assertion uses the credentials in a request message to obtain a SAML Browser Artifact from a SAML Single Sign-On (SSO) endpoint. The SSO endpoint authenticates a requestor using either Basic Authentication or HTML Form POST Authentication. If authentication succeeds, the Gateway parses the redirect header and saves the "SAMLart" parameter in memory for future assertions in the same policy to use.
The Retrieve SAML Browser Artifact assertion is useful for "mixed-mode" SAML interactions in which an initial request containing a user's credentials establishes a SSO session that can be used in subsequent browser-based requests from the same user. Multiple instances of this assertion can be used in a policy if required.
The saved SAML artifact value can be used in the Evaluate Regular Expression assertion by entering the variable "${samlBrowserArtifact.artifact}" in the Replacement field in the Evaluate Regular Expression Properties. This is useful when resources require different SAMLart parameters.
The Retrieve SAML Browser Artifact assertion should be placed after the credential source assertion (such as the Require HTTP Basic Credentials assertion) and before the assertion that uses the obtained context parameters (such as the Evaluate Regular Expression assertion).
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. When adding the assertion, the
    SAML Browser Artifact Properties
    automatically appear; when modifying the assertion, right-click
    Retrieve SAML Browser Artifact
    in the policy window and select
    SAML Browser Artifact Properties
    or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:
    Setting
    Description
    SAML Single Sign-On Endpoint URL
    Enter the URL of the SAML identity provider endpoint. This URL must include both the Single Sign-On (SSO) endpoint and the corresponding service endpoint.
    If the SSO system returns a '302' status code after processing, then the assertion succeeds and will proceed to process the service endpoint URL. If the SSO system returns a non-302 status code, the assertion will fail, possibly resulting in a failure of the policy if:
    • the target redirect URL cannot be parsed, or if
    • the result does not match the SAML Artifact Query Parameter specified below,
    The URL specified here is only for authentication, not message routing. Even if the URL is the same as the endpoint of the service, the Route via HTTP(S) assertion is still required to route service messages.
    SAML Artifact Query Parameter
    This field is populated with the default value "SAMLart". SAMLart is the type of cookie returned from the SSO system, which is then sent on to the target URL. If the return cookie is not the same type as the value in the SAML Artifact Query Parameter, then the assertion will fail.
    The SAMLart setting should suffice for most usage scenarios of the Retrieve SAML Browser Artifact assertion. You should change the default value only if the administrator of the Single Sign-On system has chosen a different parameter name. The value in the SAML Artifact Query Parameter field is case sensitive.
  4. Examine the information in the 
    Authentication Summary
     box. There are two types of authentication methods:Authentication methods:
    Method
    Description
    Basic Authentication
    The Basic Authentication method uses a Require HTTP Basic Credentials, Require WS-Security UsernameToken Profile Credentials, or Retrieve XPath Credentials assertion to extract credentials from an incoming request message. Credentials are passed to the Single Sign-On (SSO) endpoint in an HTTP message header.
    This is the default authentication method.
    Form Authentication
    Like Basic Authentication, Form Authentication uses a credential source assertion to extract credentials from an incoming request message, but uses an HTML form to pass the credentials to the SSO endpoint. Form parameters can be auto-detected or manually configured.
  5. Do one of the following:
    • To use the default Basic Authentication, click [
      OK
      ]. The assertion is added to the policy development window.
    • To change to Form Authentication, click [
      Edit
      ]. The Configure Authentication dialog appears.