-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Welcome to the Jacaranda2FA wiki!
This guide explains how to install and configure Jacaranda2FA 1.00.00 on DNN Platform.
Jacaranda2FA is a two-factor authentication provider for DNN that adds authenticator-app verification, email verification codes, recovery codes, trusted browsers, and configurable 2FA enforcement while leaving DNN responsible for normal username/password validation.
Jacaranda2FA 1.00.00 has been tested with:
- DNN Platform 10.3.2
- DNN Platform 10.3.3
- Microsoft Authenticator
- Google Authenticator
- the default DNN skin
- custom Bootstrap 5 skins
- Registered Users
- Administrators and SuperUsers
Important: Version 1.00.00 is the first public test release. It is strongly recommended that you install and test Jacaranda2FA on a development or staging site before using it on a production website.
Before installing Jacaranda2FA, make sure your DNN website is functioning normally.
You should also confirm that DNN can successfully send email if you intend to use email verification codes.
Before changing any authentication settings:
- Back up your DNN website and database.
- Confirm that you can log in as a DNN SuperUser.
- Confirm that the site's SMTP/email configuration is working.
- Keep one existing SuperUser browser session logged in while configuring Jacaranda2FA.
- Have a second browser, private/incognito window, or another device available for testing login.
Keeping an existing SuperUser session open is particularly important when you begin changing authentication providers.
If a configuration problem prevents Jacaranda2FA login, the existing session can be used to restore the previous authentication settings.
Download:
Jacaranda2FA_01.00.00_Install.zip
Log in to DNN as a Host/SuperUser.
Open:
Settings → Extensions
Choose the option to install an extension and upload:
Jacaranda2FA_01.00.00_Install.zip
Follow the normal DNN extension installation process.
The installer adds:
- the Jacaranda2FA authentication provider
- the Jacaranda2FA Account Security module
- the required database objects
- authentication controls
- settings controls
- supporting CSS and JavaScript
After installation, confirm that DNN reports that the extension installed successfully.
It is also a good idea to check:
Settings → Event Viewer
and make sure there are no installation or SQL errors.
After installation, open the DNN authentication-provider settings.
Locate:
Jacaranda2FA
and enable it for the portal.
For the initial test, leave the standard DNN Normal Login authentication provider enabled.
At this stage you should have both:
- DNN Normal Login
- Jacaranda2FA
available.
This gives you a safe fallback while configuring and testing Jacaranda2FA.
Open the Jacaranda2FA authentication-provider settings.
The available settings include options for areas such as:
- who must use 2FA
- email verification-code lifetime
- failed verification attempts
- resend limits
- resend delay
- trusted-browser lifetime
- maximum trusted browsers
- recovery-code quantity
- audit and diagnostic settings
Jacaranda2FA can be configured to apply two-factor authentication to:
All users authenticating through Jacaranda2FA must complete the configured second-factor process.
2FA is required for privileged accounts.
2FA can be applied only to members of selected DNN roles.
Users who are not covered by the configured policy can continue through the normal DNN authentication process after their password has been validated.
Before disabling any other authentication provider, test Jacaranda2FA.
Open a different browser or a private/incognito window.
Go to the normal DNN login page.
Select:
Jacaranda2FA
Enter a valid DNN username and password.
DNN validates the username and password first.
If the account is covered by the Jacaranda2FA policy, the user will then be asked to complete a second-factor check.
Depending on the account configuration, this may be:
- an authenticator-app code
- an email verification code
- a recovery code
Only after the second factor succeeds does Jacaranda2FA return successful authentication to DNN and allow DNN to complete the login.
Jacaranda2FA includes a user-facing module called:
Jacaranda2FA Account Security
This module allows users to manage their own 2FA settings.
Create a suitable page in DNN, for example:
Account Security
Add the:
Jacaranda2FA Account Security
module to that page.
The page should normally be available only to authenticated users.
Use normal DNN page and module permissions to control access.
The Account Security module allows a user to:
- enrol an authenticator app
- replace an existing authenticator
- remove an authenticator when another usable factor remains
- generate recovery codes
- replace recovery codes
- view trusted-browser information
- revoke trusted browsers
- view their current 2FA status
Sensitive security changes require recent password confirmation.
Open the Account Security page while logged in.
Choose the option to configure an authenticator app.
Jacaranda2FA displays:
- a QR code
- a manual setup key
The QR code is generated locally by Jacaranda2FA. The authenticator secret is not sent to an external QR-code service.
Open an authenticator application such as:
- Microsoft Authenticator
- Google Authenticator
Choose the option to add a new account and scan the QR code.
If scanning is not possible, enter the displayed setup key manually.
The authenticator app should begin generating a six-digit code.
Enter the current six-digit code into Jacaranda2FA to confirm enrolment.
The authenticator is not activated until a valid code has been successfully verified.
After configuring 2FA, generate a set of recovery codes from the Account Security page.
Recovery codes are designed for situations where the normal authenticator is unavailable.
For example:
- the phone has been lost
- the phone has been replaced
- the authenticator application has been removed
- the user cannot currently access email
Each recovery code can be used only once.
Store recovery codes somewhere secure and separate from the device containing the authenticator application.
Do not store recovery codes in a publicly accessible location.
Generating a replacement set invalidates the previous recovery-code set.
Jacaranda2FA can send a one-time verification code to the email address associated with the DNN account.
The email verification code:
- is six digits
- expires after the configured period
- has a limited number of verification attempts
- has resend controls
- cannot be reused after successful authentication
DNN's configured mail system is used for delivery.
Therefore, DNN SMTP/email configuration must already be working.
If an authenticator is configured, Jacaranda2FA can provide an option to use an email verification code instead.
Email verification is useful as a practical fallback, although an authenticator app with securely stored recovery codes provides stronger protection for privileged accounts.
After successful second-factor verification, a user may select:
Remember this browser for 2FA
When enabled, Jacaranda2FA stores a secure trusted-browser token.
On a future login from the same browser:
- DNN still validates the username and password.
- Jacaranda2FA validates the trusted-browser token.
- If the token is valid, the additional 2FA challenge can be skipped.
Trusted-browser tokens:
- are issued only over HTTPS
- use Secure and HttpOnly cookies
- are stored on the server only as hashes
- have configurable expiry
- can be revoked from the Account Security module
A trusted browser never bypasses the user's normal DNN password.
The option:
Keep me signed in
is separate from:
Remember this browser for 2FA
These perform different functions.
Controls DNN's normal persistent login behaviour.
Controls whether Jacaranda2FA remembers that this browser has previously completed the second factor.
A user may therefore choose either, both, or neither depending on the site's policy and their security requirements.
Before making Jacaranda2FA the only login route, test recovery carefully.
At minimum, test:
- normal authenticator login
- email fallback
- recovery-code login
- an incorrect authenticator code followed by a correct code
- an incorrect email code followed by a correct code
- trusted-browser creation
- trusted-browser revocation
For a SuperUser account, make sure that you have at least one reliable recovery method available.
This is an important part of the installation process.
Jacaranda2FA can enforce two-factor authentication only when authentication passes through the Jacaranda2FA authentication provider.
If another independent authentication provider remains enabled, that provider may provide a login route that does not use Jacaranda2FA.
This includes the standard:
DNN Normal Login
provider.
Before disabling DNN Normal Login:
- Keep an existing SuperUser session logged in.
- Open another browser or private/incognito session.
- Log in successfully as a normal registered user through Jacaranda2FA.
- Log out.
- Log in successfully as a SuperUser through Jacaranda2FA.
-
Confirm that the SuperUser has:
- a working authenticator, or
- working email fallback, or
- unused recovery codes.
- Only after these tests succeed should you consider disabling DNN Normal Login.
After disabling Normal Login, repeat both the registered-user and SuperUser login tests.
Jacaranda2FA has been tested successfully operating as the sole enabled login provider on DNN 10.3.2 and 10.3.3.
The same rule applies to authentication providers other than DNN Normal Login.
For example, if a website has another authentication provider that independently completes DNN authentication, that provider may not pass through Jacaranda2FA.
Administrators who require mandatory 2FA should therefore review all enabled authentication providers, not only DNN Normal Login.
Before relying on Jacaranda2FA on a production website, test:
- Registered User login
- Administrator login
- SuperUser login
- Microsoft Authenticator
- Google Authenticator
- email verification
- email resend
- recovery code
- reused recovery code rejection
- trusted browser
- trusted-browser revocation
- incorrect authenticator code
- incorrect email code
- expired verification challenge
- password confirmation before security changes
- role-based enforcement
- mobile/narrow-screen login
- desktop login
- the site's normal production skin
- the DNN Event Viewer
If mandatory 2FA is required, also test with DNN Normal Login disabled.
Jacaranda2FA 1.00.00 can be installed as an upgrade over an existing development version such as 00.00.31.
Do not uninstall the existing working extension first.
Install the newer package through:
Settings → Extensions
using the normal DNN extension-upgrade process.
After upgrading:
- clear browser cache if necessary
- confirm the extension version
- test a normal login
- test 2FA
- test the Account Security module
- review DNN Event Viewer
Version 1.00.00 introduces no new database migration beyond those already present in the confirmed-working 00.00.31 baseline.
Check that the authentication provider is enabled for the portal.
Also check:
Settings → Event Viewer
for control-compilation or extension errors.
Confirm that DNN itself can send email successfully.
Check:
- SMTP configuration
- sender address
- spam/junk folders
- mail-server logs
- DNN Event Viewer
Jacaranda2FA uses DNN's configured mail infrastructure.
Check that the server and mobile device clocks are correct.
TOTP authentication depends on accurate time.
Jacaranda2FA uses 30-second TOTP intervals with a small clock-tolerance window.
Use:
- email fallback, if available, or
- an unused recovery code.
After logging in, open Account Security and enrol the replacement authenticator.
Do not disable alternative authentication providers until Jacaranda2FA SuperUser login has been tested successfully in another browser.
Keep an existing logged-in SuperUser session available during initial configuration.
Also securely retain recovery codes.
Jacaranda2FA 1.00.00 is a public test release.
Normal bugs, compatibility problems, and usability feedback can be reported through the project.
If you discover something that may represent an exploitable security vulnerability, please report it privately rather than publishing full exploit details.
Security reports can be sent to:
webmaster@forrestitservices.org
Please include:
- Jacaranda2FA version
- DNN Platform version
- reproduction steps
- expected behaviour
- actual behaviour
- sanitised Event Viewer information where relevant
Please do not send:
- passwords
- authenticator secrets
- recovery codes
- trusted-browser tokens
- machine keys
- database connection strings
- SMTP credentials
Jacaranda2FA 1.00.00 has currently been tested successfully with:
Component | Tested -- | -- DNN Platform 10.3.2 | Yes DNN Platform 10.3.3 | Yes Default DNN skin | Yes Bootstrap 5 custom skin | Yes Microsoft Authenticator | Yes Google Authenticator | Yes Email OTP | Yes Recovery codes | Yes Trusted browsers | Yes Registered Users | Yes SuperUsers | Yes Jacaranda2FA as sole login provider | YesAdditional testing and feedback from the DNN community is welcome.
Jacaranda2FA is released under the MIT Licence.
Copyright © 2026 Forrest IT Services.
This guide explains how to install and configure Jacaranda2FA 1.00.00 on DNN Platform.