Forms Authentication Utilities

A helper class called FormsAuthentication provides the static helper methods and properties for managing forms authentication tickets. The following table lists the methods.

Method Description
Authenticate Attempts to validate the credentials from the configured credential store, given the supplied credentials.
Decrypt Returns an instance of the FormsAuthenticationTicket class, given an encrypted authentication ticket obtained from an HTTP cookie.
Encrypt Produces a string containing an encrypted authentication ticket suitable for use in an HTTP cookie, given a FormsAuthenticationTicket.
GetAuthCookie Retrieves the already encrypted authentication cookie as an HttpCookie instance. It does not add it to the Response cookies collection.
GetRedirectUrl Returns the redirect URL for the original request that caused the redirect to the logon page.
HashPasswordForStoringInConfigFile Given a password and a string identifying the hash type, this routine produces a hash password suitable for storing in a configuration file.
Initialize Initializes FormsAuthentication by reading configuration settings and getting the cookie values and encryption values for the current application.
RedirectFromLoginPage Redirects an authenticated user back to the originally requested URL.
RenewTicketIfOld Conditionally updates the sliding expiration on a FormsAuthenticationTicket.
SetAuthCookie Creates an authentication ticket and attaches it to the cookie collection of the outgoing response.
SignOut Removes the authentication ticket by setting the authentication cookie to an empty value. This removes both durable and session cookies.

The following table lists helpful properties for managing forms authentication tickets.

Property Description
FormsCookieName Gets the cookie name for the current application.
FormsCookiePath Gets the cookie path for the current application.
RequireSSL Gets a value indicating whether cookies must be transmitted using SSL (that is, over HTTPS only).
SlidingExpiration Gets a value indicating whether sliding expiration is enabled.

You can use the helper methods to customize the way a module works. You can also use them in the logon page handler to avoid the work of generating the redirection. A logon page using these facilities can be as simple as the following example.

<html>
<head>
<script language="VB" runat=server>
    Sub SubmitBtn_Click(Source As Object, e As EventArgs)
        ' Pull credentials from form fields and try to authenticate.
        If FormsAuthentication.Authenticate _
                (UserName.Value, UserPassword.Value) Then
            Dim ticket As New FormsAuthenticationTicket _
                (UserName.Value, false, 5000)
            FormsAuthentication.RedirectFromLoginPage _
                (UserName.Value, Persist.Checked)
        End If
    End Sub
</script>
</head>

<body>
<form method=post runat=server>
    <table>
        <tr>
            <td>Name:</td>
            <td><input type="text" id="UserName" runat=server/>
        </tr>
        <tr>
            <td>Password:</td>
            <td><input type="password" id="UserPassword" runat=server/>
            </td>
        </tr>
    </table>



    <input type="checkbox" id="Persist" runat=server/>
    <!-- Use persistent cookie -->
    <br>
    <input type="submit" OnServerClick="SubmitBtn_Click" runat=server/>
</form>
</body>
</html>
[C#]<html>
<head>
<script language="C#" runat=server>
    void SubmitBtn_Click(Object Source, EventArgs e)
    {
        // Pull credentials from form fields and try to authenticate.
        if (FormsAuthentication.Authenticate(UserName.Value, 
                UserPassword.Value))
        {
            FormsAuthenticationTicket ticket = new 
                FormsAuthenticationTicket(UserName.Value, false, 5000);
                  
            FormsAuthentication.RedirectFromLoginPage(UserName.Value,
                Persist.Checked);
        }
    }
</script>
</head>

<body>

<form method=post runat=server>
    <table>
        <tr>
            <td>Name:</td>
            <td><input type="text" id="UserName" runat=server/></td>
        </tr>
        <tr>
            <td>Password:</td>
            <td><input type="password" id="UserPassword" runat=server/>
            </td>
        </tr>
    </table>



    <input type="checkbox" id="Persist" runat=server/>
    <!-- Use persistent cookie. -->
    <br>
    <input type="submit" OnServerClick="SubmitBtn_Click" runat=server/>
</form>
</body>
</html>

Applications that need detailed control over the HTTP cookie properties can construct the ticket and perform the redirection but use the encryption helpers to encrypt the authentication ticket.

See Also

ASP.NET Web Application Security | Forms Authentication Provider | FormsAuthentication | FormsAuthenticationTicket | HttpCookie