Common things to check when using Forms Authentication

Michael Kelley — Wed, 09 Dec 2020 21:50:45 GMT

Current Revision posted to User Documentation by Michael Kelley on 12/09/2020 21:50:45

[toc]

When using the Forms Authentication module, there are a couple of areas to check first when troubleshooting any issues you might encounter when setting it up. These include the authentication ticket name, the machine keys, the cookie path, and the cookie domain.

Authentication ticket name

The most common issue when using Forms Authentication is that the name of the cookie used for the authentication ticket is different between the two applications. Forms Authentication works by creating a certain cookie that contains basic information about the user. The name of the cookie is set in the web.config. In ASP.NET, the default name is “.ASPXAUTH”, however Telligent Community Server's out-of-the-box web.config sets it to “.Zimbra.Evolution”. If the two applications do not have the same name set, then the other application will not recognize the authentication ticket from the main application.

To change this, you can either change the main application to match Community Server's setting by changing its <forms> line in the web.config to “.CommunityServer”, or you can change Community Server to use the same setting as your own application, but changing its web.config to use “.ASPXAUTH” or whatever it already has specified. An example is:

<authentication mode="Forms"> <forms name=".Zimbra.Evolution" ... /></authentication>

Machine keys

When using Forms Authentication between two ASP.NET applications, you need to ensure that the machine keys between the two applications match. The machine keys are used to encrypt and decrypt the information within the authentication ticket. If they do not match, one application will not be able to utilize the other application’s authentication ticket.

The machine keys are set within the <system.web> section of the web.config. A sample machine key section looks like this:

<machineKey validationKey="CFBAC2E26EB8...174C6901CE50D" decryptionKey="43AEA5079E…97035372A" validation="SHA1" />

Cookie paths

A frequent issue with the cookie created for the authentication ticket is the path on the cookie. Typically, an application will create the cookie with its path set to its own application path. So if your application is at /app and Community Server is at /tc, when you set the authentication cookie within /app, ASP.NET will automatically set the cookie’s path to /app. Then the browser will only pass the cookie along to page requests under /app, and not to /tc. To get it to carry over, you’ll need to set the cookie’s path to /, so that it will be accessible between the two applications.

The cookie’s path can either be specified in the web.config or through code. To set it in the web.config, use the path attribute on the <forms> line in the parent application's web.config, such as:

<authentication mode="Forms"> <forms name=".Zimbra.Evolution" ... path="/" /></authentication>

Additionally, it can be set in code when you use the GetAuthCookie method of FormsAuthentication instead of just the SetAuthCookie method when creating the cookie in the parent application. For example:

HttpCookie cookie = FormsAuthentication.GetAuthCookie(username, true); cookie.Path = "/"; Response.Cookies.Add(cookie);

Cookie domains

Another common issue with the cookie for the authentication is the domain for the cookie. Similarly to the paths of the cookies, if the cookies are created on two different subdomains, then the cookie will only be accessible on the domain where it was created. For instance your main application may be on www.domain.com, but you have Community Server running on tc.domain.com. If you create the cookie on www.domain.com, the browser will only send it to that domain, and it won’t be passed along when they navigate over to tc.domain.com.

The cookie can be carried over by setting the domain to “.domain.com”. Cookies don’t use the common “*” wild card. Simply use “.domain.com”. With this entry, the browser will not pass the cookie when it goes over to cs.domain.com as well.

Like the path, the domain can be specified in either the web.config or through code. When setting the web.config file, it will only check for the authorization cookie. You must have this set for the site to correctly recognize the new domain level cookie:

<authentication mode="Forms"> <forms name=".Zimbra.Evolution" ... domain=".domain.com" /> </authentication>

The "domain" name is ignored by the FormsAuthentication.SetAuthCookie method, so you must manually set it on your login page when creating the AuthCookie. For example:

HttpCookie cookie = FormsAuthentication.GetAuthCookie(username, true);

cookie.Domain = ".domain.com"; Response.Cookies.Add(cookie);