Support Thread

APG vNext 4.3 Upgrade Guide and Providers Documentation

APG vNext 4.3 Upgrade Guide and Providers Documentation — APG vNext Guide

This document covers the full upgrade process to APG vNext 4.3 and explains the provider architecture introduced in this version.

What Changed in 4.3

  • Provider model: APG vNext 4.3 introduced a flexible provider architecture allowing you to plug in custom membership, roles, and profile providers.
  • ASP.NET Membership integration: You can now use your existing ASP.NET Membership database with APG vNext instead of the built-in member store.
  • Custom authentication: Support for Forms Authentication with external identity providers was significantly improved.

Upgrading from 4.2 to 4.3

  • Back up your database and application files.
  • Run the Upgrade_4.2_to_4.3.sql script against your forum database.
  • Replace all application files with the new 4.3 build, preserving your web.config.
  • If using custom providers, update the provider configuration in web.config as documented below.

Configuring Custom Providers

To use an external ASP.NET Membership provider, add the following to web.config:

  • Set APG_MemberProvider to AspNetMembershipProvider in the APG configuration section.
  • Configure the standard <membership> section in web.config to point to your existing membership database.
  • Ensure the membership database schema is compatible with the ASP.NET Membership provider schema.

See the Support Forum for provider-specific questions. For the full 4.4 release, see APG vNext 4.4 release notes.

Understanding the Provider Architecture in APG vNext 4.3

APG vNext 4.3 formalised the provider architecture that had been incrementally introduced since version 3.x. The provider pattern in ASP.NET allows the core application to define an interface (the provider contract) and then swap in different implementations without changing application code. In APG vNext, this is used for membership, roles, profiles, and session state — making it possible to integrate the forum with an existing corporate user directory or custom authentication system without forking the codebase.

The Four Core Providers

  • MembershipProvider: handles user authentication, password hashing, account lockout, and password reset
  • RoleProvider: manages group membership and permission assignment
  • ProfileProvider: stores per-user profile data (avatar, signature, notification preferences)
  • SessionStateProvider: manages user session — can be switched to SQL Server or Redis for web farm deployments

Full Upgrade Process to APG vNext 4.3 with Provider Migration

If you are running a custom provider implementation from a pre-4.3 version, the upgrade requires additional steps beyond the standard file replacement and SQL script run.

Step 1 — Inventory Your Custom Providers

Check your current web.config for any custom provider registrations:

<membership defaultProvider="APGMembershipProvider">
  <providers>
    <clear />
    <add name="APGMembershipProvider"
         type="APGPlayground.Providers.MembershipProvider, APGPlayground"
         connectionStringName="APGConnection"
         requiresUniqueEmail="true"
         minRequiredPasswordLength="6" />
  </providers>
</membership>

Note the type attribute. If it references a custom assembly (not the default APG vNext provider), you will need to recompile against the 4.3 provider interfaces.

Step 2 — Run the SQL Upgrade Script

APG vNext 4.3 added two stored procedures and one table to support the new provider features. Run upgrade_4.2_to_4.3.sql in SSMS. The script is wrapped in a transaction — if it fails partway through, it will roll back completely, leaving your database in the pre-upgrade state.

Step 3 — Update Provider Configuration

The 4.3 release renamed several provider configuration keys. Update your web.config accordingly:

<!-- Old (4.2) -->
<add key="APG.MembershipProvider.HashAlgorithm" value="SHA1" />

<!-- New (4.3) — SHA1 deprecated; use SHA256 -->
<add key="APG.Security.PasswordHashAlgorithm"  value="SHA256" />
<add key="APG.Security.SaltLength"             value="32" />

If you leave the old SHA1 key, existing passwords continue to work (APG vNext auto-upgrades hashes on next login). New registrations will use SHA256 immediately.

Step 4 — Verify Provider Registration

After deploying the updated application files and restarting IIS, verify provider registration in Admin Panel → About → Server Info. The providers section should list all four providers with their current implementation class names. Any provider showing "Default" is using the built-in APG implementation.

Using the Active Directory Membership Provider in APG vNext 4.3

One of the most common use cases for the new provider architecture in 4.3 is integrating APG vNext with an existing Windows Active Directory domain. Instead of managing a separate forum user database, AD integration means your corporate users log into the forum with their Windows credentials — no separate registration required.

<!-- web.config: Active Directory membership provider -->
<membership defaultProvider="ADMembershipProvider">
  <providers>
    <clear />
    <add name="ADMembershipProvider"
         type="System.Web.Security.ActiveDirectoryMembershipProvider"
         connectionStringName="ADConnectionString"
         attributeMapUsername="sAMAccountName"
         attributeMapEmail="mail"
         connectionUsername="DOMAIN\forumservice"
         connectionPassword="encrypted-value" />
  </providers>
</membership>

<connectionStrings>
  <add name="ADConnectionString"
       connectionString="LDAP://dc=yourdomain,dc=com/DC=yourdomain,DC=com" />
</connectionStrings>

Mapping AD Groups to APG vNext Roles

When using AD integration, map Active Directory security groups to APG vNext user groups to control permissions without manual group assignment. In APG Admin Panel → User Groups → AD Group Mapping, enter the distinguished name of each AD group and select the corresponding APG user group:

<!-- Example: Map AD group to APG Administrators group -->
<add key="APG.AD.GroupMap.Administrators"
     value="CN=Forum Admins,OU=Groups,DC=yourdomain,DC=com" />
<add key="APG.AD.GroupMap.Moderators"
     value="CN=Forum Mods,OU=Groups,DC=yourdomain,DC=com" />

Troubleshooting AD Authentication Failures

  • "LDAP bind failed" error: The service account credentials are wrong, or the account is locked. Verify with Test-ADAuthentication -Username forumservice in PowerShell
  • Users can log in but see no forum content: Their AD account is not mapped to any APG user group — check the group mapping configuration
  • Intermittent failures: The LDAP connection is being dropped by a firewall after idle timeout — add a keepalive connection to the AD connection string

Related Resources

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