Establish a Front-End Authentication Scheme

Policy Server Guides › Policy Server Configuration Guide › Strong Authentication › Establish a Front-End Authentication Scheme

Establish a Front-End Authentication Scheme

The front-end authentication scheme uses the Forms Credential Collector (FCC), selectlogin.fcc, to generate the login selection screen that is used to request access to the protected resource. The FCC dynamically constructs the FCC directives for the agent so the agent can redirect the user as appropriate for any of the authentication scheme choices.

Note: The selectlogin.fcc is a sample for use by the Credentials Selector. The set of authentication choices and HTML formatting depends upon your particular situation.

Use a Forms Credential Collector (FCC)

The FCC format is a proprietary format that Web Agent use to collect credentials and pass them to the Policy Server. An FCC consists of a header and a body.

FCC Header Description

An FCC header is a list of FCC directives, one per line. The FCC directives have the following syntax:

@<directive>[=<value>]

The values can contain % substitutions, formatted as %parameter%. The parameters are passed with the FCC file on a POST action when the credentials are submitted.

The set of FCC directives is limited. For the purposes of this example, the most important directives are:

@target: Resource URL that the Web Agent must pass to the Policy Server.
@username: Username that the Web Agent must pass to the Policy Server.
@password: Password that the Web Agent must pass to the Policy Server.
@smagentname: Agent name that the Web Agent must pass to the Policy Server. If the EncryptAgentName parameter in the agent configuration is set to yes, the name is encrypted.

Not all FCC directives must be listed in the header; many have implicit defaults, such as:

@target=%target%
@username=%username%
@password=%password%
@smagentname=%smagentname%

FCC Body Description

The FCC body contains HTML or other web-browser readable format. The FCC body is rendered in the web browser when the user is challenged.

The body can contain substitutions, formatted as $$parameter$$. The parameter name must belong to a certain set of known parameters that are passed with the FCC file on a GET action.

For the purposes of this example, the important directives are:

$$target$$: Resource URL that the user has requested.
$$smagentname$$: The agent name. If the EncryptAgentName parameter in the agent configuration is set to yes, the name is encrypted.

Configure the selectlogin.fcc File for Front-End Authentication

The selectlogin.fcc file is included with the Web Agent installation as a sample FCC. The front-end authentication scheme uses the selectlogin.fcc file to render the login dialog that is presented to the user when they request the protected resource.

When a user requests a resource, the Web Agent passes the requested URL to the Policy Server. In most cases, the resource URL that the Web Agent passes is the same one that the user requests. The FCC files that are defined for the authentication schemes ensure that the requested URL is sent by passing $$target$$ (the GET parameter) as %target% (the POST parameter), and using the @target=%target% directive. For example:

<!-- some HTML code -->
<form name="Login" method="POST">
<!-- some HTML code -->
<input type="hidden" name="target" value=”$$target$$”>
<!-- more HTML code -->
</form>
<!-- more HTML code -->

Note: The @target=%target% directive is used by default.

In this case, the selectlogin.fcc file works by replacing the value of the %target% parameter with the following value:

/path/redirect.ext?authtype=type&target=$$target$$

redirect.ext

A simple script that redirects to the URL provided in the target parameter. Example values are redirect.asp or redirect.jsp. Alternatively, you can use different redirect script files or different virtual directories that expose the same physical file as long as the URLs in the redirect script depend on the credentials provided.

type

A string that is determined by the credentials that the user chooses.

If different authentication schemes protect different redirect URLs, the chosen authentication scheme processes the credentials that the FCC collects. The chosen authentication scheme establishes the user session, including the user authentication level. After the user is authenticated and authorized for the redirect script resource, the user is redirected to the originally requested resource.

Note: If single sign-on is in effect and the user protection level is equal or higher than the protection level of the front-end authentication scheme, then the user session is validated against the original resource. Whether the user is authorized depends on the policy configuration, which can check for the user authentication context. For example, a minimal protection level or certain conditions can be required to access particular resource.

More Information:

Selectlogin.fcc Configuration Details

You can configure various authentication schemes in the selectlogin.fcc file. The following list shows configuration details for some schemes:

The cert-and-form scheme requires posting over an SSL connection. If the front-end authentication scheme does not use an SSL connection, the agent cannot POST to the same selectlogin.fcc URL that the GET request obtains.
The following JavaScript code can be used to convert the URL to an SSL URL:
```
arr = document.URL.split("://");
document.Login.action = "https://" + arr[1];
```
To support SafeWord two-step authentication, the client side must remember the username that is collected from the first challenge form in time for the second challenge. The safeword.fcc file, also included in the agent installation, uses the @smtransient FCC directive to keep the username in a transient cookie. The same directive can be used in the selectlogin.fcc file too, but then the cookie is going to be created even if the user makes a different choice of credentials. A better alternative is to modify the action argument to POST to the safeword.fcc file, as follows:
```
document.Login.action = "safeword.fcc";
```
The Windows authentication scheme does not use an FCC file. It uses a specific pseudo-resource URL, which does not exist on the web server but which the agent recognizes. To make Windows authentication work, set the action argument to this same pseudo-resource URL, as follows:
```
document.Login.action = "/siteminderagent/ntlm/creds.ntc";
```
The SecurID authentication scheme does not use an FCC; however, the Agent can POST the SecurID credentials directly to the selectlogin.fcc file. No modification of the action argument is required.
The action URL can be hosted by a different web server. However, the other web server must also be protected by an agent so that the CA SiteMinder®-specific resource URLs (FCC, SCC, and NTC) are recognized and properly processed.
Note: SCC pseudo-resource URLs are used for certificate-only authentication.

Sample selectlogin.fcc File

A simplified version of the selectlogin.fcc file (without the HTML formatting) follows. Hidden input fields for smquerydata and postpreservationdata are necessary for passing the GET and POST parameters, respectively.

The smauthreason parameter holds the reason code that the Policy Server provides together with the authentication challenge.

A sample selectlogin.fcc file follows:

@username=%USER%
@smretries=0

<html>
<head>
  <script language="JavaScript">
    function submitForm(form)
    {
      authtype = "none";

      if (form == 1)
      {
        document.Login.USER.value     = document.Login.USER1.value;
        document.Login.PASSWORD.value = document.Login.PASSWORD1.value;

        if (!document.Login.UseCert.checked)
        {
          // username/password only
          authtype = "form";
        }
        else if (document.Login.USER.value == "" &&
                 document.Login.PASSWORD.value == "")
        {
          // certificate only
          authtype = "cert";
        }
        else
        {
          // username/password and certificate
          authtype = "certform";

          // This option requires posting over SSL.
          arr = document.URL.split("://");
          document.Login.action = "https://" + arr[1];
        }
      }
      else if (form == 2)
      {
        // SecurID authentication
        authtype = "securid";
        document.Login.USER.value     = document.Login.USER2.value;
        document.Login.PASSWORD.value = document.Login.PASSWORD2.value;
      }
      else if (form == 3)
      {
        // SafeWord authentication
        authtype = "safeword";
        document.Login.USER.value     = document.Login.USER3.value;
        document.Login.PASSWORD.value = "";

        // POST to safeword.fcc, for additional processing.
        // NOTE: This forces the web agent to POST to safeword.fcc
        // even if the authentication scheme's URL parameter
        // is set to selectlogin.fcc for redirection purposes.
        document.Login.action = "safeword.fcc";
      }
      else if (form == 4)
      {
        // Authenticate with the current Windows login credentials
        authtype = "windows";
        document.Login.USER.value     = "";
        document.Login.PASSWORD.value = "";

        // POST to creds.ntc (required by the Windows authentication scheme).
        document.Login.action = "/siteminderagent/ntlm/creds.ntc";
      }
      // Generate the target, depending on the user's choice of credentials.
      // This sample uses redirect.asp, but it could also be redirect.jsp, redirect.pl, etc.
      // This sample uses the following format: /auth/redirect.asp?authtype=<choice>&target=<original target>
      // Other formats are also possible, e.g.: /auth-<choice>/redirect.asp?target=<original    
         target>
      // The helper realms' resource filters must be defined accordingly (see the tech note).
      // Check if the target is not already in the same format. The user may
      // have been redirected back to selectlogin.fcc upon authentication failure,
      // if the authentication scheme's URL parameter is set to selectlogin.fcc.
      if ("$$target$$".indexOf("/auth/redirect.asp?authtype=") == 0 &&
          "$$target$$".indexOf("&target=") > 0)
      {
        // This must be a redirect. Extract the original target, but not
        // the authtype parameter, because the user may have made a different
        // choice of credentials this time.
        trgarr = "$$target$$".split("&target=");
        document.Login.target.value = "/auth/redirect.asp?authtype=" + authtype + "&target=" + trgarr[1];
      }
      else
      {
        // This is not a redirect. Pass $$target$$ as a URL query parameter.
        document.Login.target.value = "/auth/redirect.asp?authtype=" + authtype + "&target=$$target$$";
      }

      document.Login.submit();
    }
    function resetCredFields()
    {
      document.Login.PASSWORD.value  = "";
      document.Login.PASSWORD1.value = "";
      document.Login.PASSWORD2.value = "";
    }
  </script>
</head>

<body onLoad="resetCredFields();">
  <center>
    <form name="Login" method="POST">
      <input type="hidden" name="USER">
      <input type="hidden" name="PASSWORD">
      <input type="hidden" name="smagentname"  value="$$smagentname$$">
      <input type="hidden" name="smauthreason" value="$$smauthreason$$">
      <input type="hidden" name="smquerydata"  value="$$smquerydata$$">
      <input type="hidden" name="postpreservationdata" value="$$postpreservationdata$$">
      <input type="hidden" name="target">
      <!-- Some table formatting throughout -->
        <!-- Authentication Choice: Password And/Or Certificate -->
          <input type="text"     name="USER1">
          <input type="password" name="PASSWORD1">
          <input type="button"   value="Login" onClick="submitForm(1);">

        <!-- Authentication Choice: Windows Authentication -->
          <input type="button"   value="Login" onClick="submitForm(4);">

        <!-- Authentication Choice: SecurID Authentication -->
          <input type="text"     name="USER2">
          <input type="password" name="PASSWORD2">
          <input type="button"   value="Login" onClick="submitForm(2);">

        <!-- Authentication Choice: SafeWord Authentication -->
          <input type="text"     name="USER3">
          <input type="button"   value="Login" onClick="submitForm(3);">
      <!-- More table formatting -->
    </form>
  </center>
</body>
</html>

Configure the Front-end Authentication Scheme

Configure a front-end authentication scheme that protects the sample application which generates the greeting. For this solution, you can configure the AuthChannel authentication scheme.

See the following illustration for an example of an AuthChannel authentication scheme.

Graphic showing the General and Scheme Setup sections of the AuthChannel Authentication Scheme page in view mode

The AuthChannel authentication scheme is set as follows:

Authentication Type Style

HTML Form Template

Protection Level

The Protection Level for the AuthChannel scheme is set to 1 because the front-end authentication scheme must have a lower protection level than any other scheme in the configuration. The authentication scheme the user chooses when logging in to access the protected resource determines the actual protection level for that user. When the user is redirected back to the originally requested resource, the low protection level of the front-end scheme ensures that the user is not rechallenged.

Web Server Name

auth.sample.com

Specifies the web server where the sample application resides.

Target

/siteminderagent/forms/selectlogin.fcc

This target points to the selectlogin.fcc file. The selectlogin.fcc file is a sample file that is included with the Web Agent installation.