Custom Forms Authentication Cookie for Single Sign-On in...

Implementing Custom Forms Authentication Cookie for SSO in APG vNext — APG vNext Guide

APG vNext supports Single Sign-On (SSO) via a shared ASP.NET Forms Authentication cookie, allowing your main site and the forum to share the same authenticated session.

Requirements

Both applications must be on the same parent domain (e.g., example.com and forum.example.com)
Both must use the same machineKey in web.config for encryption/decryption
Both must use the same cookie name and domain

Configuration

In both applications' web.config, configure Forms Authentication identically:

Set the same name, domain (e.g., .example.com), path, and protection values.
Add matching <machineKey> entries with the same validationKey and decryptionKey.
Set requireSSL="true" if both sites run on HTTPS.

APG vNext Provider Configuration

In APG vNext's Admin Panel → Settings → Authentication, set the Authentication Mode to External Forms Authentication and configure the login/logout redirect URLs to point to your main site's auth pages.

Custom Forms Authentication Cookie for Single Sign-On in APG vNext

APG vNext integrates with ASP.NET's Forms Authentication system, which means it can participate in a shared single sign-on (SSO) setup with other ASP.NET applications on the same domain. When the cookie name, protection level, and machine key are shared across applications, logging into any one application automatically authenticates the user in APG vNext without a separate login.

Shared Forms Auth Cookie Configuration

<!-- Configure identical settings in ALL participating applications -->
<system.web>
  <authentication mode="Forms">
    <forms name=".SharedAuthCookie"
           domain=".yourdomain.com"
           path="/"
           timeout="60"
           slidingExpiration="true"
           protection="All" />
  </authentication>
</system.web>

<!-- Shared machine key (MUST be identical in all apps): -->
<machineKey
  validationKey="[64-char-hex]"
  decryptionKey="[32-char-hex]"
  validation="HMACSHA256"
  decryption="AES" />

Generating a Secure Machine Key

# PowerShell: generate cryptographically secure machine key
[System.Web.Security.MachineKeySection]::GenerateCompatibilityKey()
# Or use the IIS Manager: Server -> Machine Key -> Generate Keys

APG vNext SSO Configuration

<add key="APG.SSO.Enabled"          value="true" />
<add key="APG.SSO.CookieName"       value=".SharedAuthCookie" />
<add key="APG.SSO.AutoProvision"    value="true" />
<!-- AutoProvision=true creates a forum member on first SSO login -->

Cross-Application Logout

To log out from all SSO-connected applications simultaneously, clear the shared cookie from any app and all others will require re-authentication:

FormsAuthentication.SignOut();
Response.Cookies[".SharedAuthCookie"].Expires = DateTime.MinValue;

Security Hardening for Shared Auth Cookies

When sharing a Forms Authentication cookie across multiple applications, the attack surface for cookie theft expands because the same cookie grants access to all connected applications. Implement these security measures to minimise risk:

Require HTTPS for the Shared Cookie

<forms name=".SharedAuthCookie"
       domain=".yourdomain.com"
       requireSSL="true"
       httpOnlyCookies="true" />
<!-- requireSSL: cookie only sent over HTTPS — protects against network sniffing
     httpOnlyCookies: cookie inaccessible to JavaScript — protects against XSS -->

Cookie Sliding Expiration and Timeout

Balance security with usability when configuring cookie expiration. A very short timeout (15 minutes) is secure but forces frequent re-logins. A longer timeout (60–120 minutes) with sliding expiration (resetting the timer on each request) provides a better user experience while still expiring inactive sessions:

<forms timeout="60"
       slidingExpiration="true" />
<!-- Session expires 60 minutes after last activity, not after login -->

Protecting the Machine Key

The machineKey is the most sensitive configuration value in your SSO setup. If it is compromised, an attacker can forge authentication tickets and log in as any user. Protect it using:

Store encrypted in web.config using aspnet_regiis -pe rather than in plaintext
Rotate the machine key annually and after any suspected security incident
Never commit web.config containing a plaintext machine key to source control
Restrict file system access to web.config — only the IIS app pool identity should be able to read it

Troubleshooting SSO Cookie Issues

The most common SSO failure mode is a mismatch between the machine key values in the two applications. This manifests as users being instantly logged out when navigating from the main site to the forum, or receiving a cryptographic exception. Verify machine key equality by comparing SHA-256 hashes of the validation key values rather than visually comparing 64-character hex strings:

# PowerShell: hash the validation key to compare across servers:
$key = "your-64-char-validation-key-here"
[System.Security.Cryptography.SHA256]::Create().ComputeHash(
    [System.Text.Encoding]::UTF8.GetBytes($key)
) | ForEach-Object { $_.ToString("x2") } | Out-String

SSO Compatibility with Third-Party Auth Providers

If your main site uses OAuth (Google, Microsoft, Facebook) for authentication and you want to extend this to APG vNext via SSO, the shared cookie approach requires that your main site converts the OAuth identity into an ASP.NET Forms Authentication ticket after the OAuth callback. APG vNext then reads this ticket via the shared cookie. This allows a full OAuth → Forms Auth → APG vNext SSO chain without requiring APG vNext to directly integrate with the OAuth providers, simplifying the configuration significantly when multiple OAuth providers are involved.

Testing the SSO Cookie Setup Before Going Live

Before deploying a shared Forms Authentication cookie SSO setup to production, test it thoroughly in a staging environment that mirrors production exactly — same IIS version, same .NET Framework version, same SQL Server version. The most common test failure is the machine key mismatch between applications, which is not always immediately obvious because both applications may appear to work independently but fail when the authentication cookie from one is presented to the other. Use a browser's developer tools Network tab to inspect the Set-Cookie response header from each application and verify that the cookie name and domain match exactly. A difference as small as a missing leading dot in the domain value (example.com vs .example.com) prevents cookie sharing between subdomains.

After confirming cookie sharing works in staging, run a complete user journey test: log in on the main site, navigate to the forum, verify automatic authentication, perform a forum action, then log out from the main site and verify the session is invalidated on the forum. This end-to-end test catches edge cases that unit tests miss, particularly around session invalidation timing and cookie expiry handling across different application pools.

Related Resources

Looking for more help? Browse the support forum or check the Knowledge Base.

Implementing Custom Forms Authentication Cookie for SSO in APG vNext