Single Sign On For TNG Plugin
OVERVIEW
This plugin improves the user experience when a site using WordPress is related to a site developed using the TNG Genealogy Software. With V2 of the plugin the WordPress website and the TNG website do not need to be on the same server.
User accounts for both systems are managed through the WordPress user management system. This includes account creation, deletion, certain account information, and password change.
Logging in and out of the users WordPress account automatically logs in and out of their account in TNG. When the user changes his/her password, name or email address in their WordPress account the equivalent information in the TNG account is changed automatically.
This plugin makes no attempt to visually incorporate TNG into the WordPress theme. But TNG’s template feature allows the developer to design a visual for TNG which is consistent with that on the WordPress Site.
Table of Contents
- Installation
- Settings
- Important Short Codes
- How the Plugin Works
- Forminator Forms
- Setting Screen Shots
- Assistance
SETTINGS
To set up the plugin go to Single Sign On for TNG in the settings section.
TNG Link Method
Two methods are provided.
Database Access
When this method is selected the plugin accesses the TNG database directly. For this to work the WordPress and TNG installations must be on the same server, and the hosting service must not prevent the WordPress installation from accessing (for both read and write) a “foreign” database on the same server. This method will provide the best performance when the preceding conditions are met.
Web Access
This method uses HTTP/HTTPS communications to “talk” between the WordPress and TNG sites. As a result there is no requirement that two sites be on the same server, or the same continent for that matter. Nor will it be affected by any restriction the sites’ hosts might put on accessing “foreign” databases!
Communications over the Internet are protected by keys, and passwords are encrypted. To make this method functional it is required that a small file called sso_interface.php be placed in the base folder of the TNG installation, and the Password Encryption Key from this plug-in’s settings page be placed in the TNG customconfig.php file. You will either need SSH or FTP access to your TNG installation.
sso_interface.php
You can download this file by clicking here. Place the file in the base folder of your TNG site installation. You can identify this folder because it will have the file customconfig.php in it, which you will need to edit in the next step. DO NOT change this file’s name or make an edits to the file. It will stop the interface from working!
customconfig.php
This file can be found in the base folder of your TNG installation. You will need to edit it using FTP or SSH. Place the following line in the file:
$sso_key=’<Your Password Encryption key>‘;
where <Your Password Encryption key> is the key you can obtain from the plugin’s settings page. It is normally hidden by asterisks, but there is a button there to make it visible, and another to copy it to the clipboard, to allow you to copy and paste it to this file.
IMPORTANT
Make sure you use SINGLE QUOTES around the key, as shown, and not double ones.
TNG Installation Location
Enter either an absolute or relative path to the folder location where TNG installed. An absolute path will start with a / and look something like this: /www/familytree. A relative path will start with .. and look something like this: ../../familytree. It will be relative to the WordPress wp-admin folder. When you save your settings changes the folder will be checked to make sure an installation of TNG is at the given location.
Important Note: this setting will not show if you have selected Web Access as your TNG Link method, as it is not relevant in that situation.
TNG Installation URL
Enter the web address of your TNG installation. It will start with either https:// or http:// and might look something like this: https://www.mysite.com/familytree.
Password Encryption Key
The first time you run the settings page a secret key will be generated. This is used to encrypt your password for passing to TNG and once generated cannot be changed.
Add Existing Users
When this setting is checked, when a user logs in to your website and has one of the roles selected in the next setting, and does not have a matching TNG account, one will be created there automatically, using their WordPress account credentials.
Select Matching Roles
Select one or more roles that a user of your site must have to cause a matching TNG account created for them when they first log in. This setting is only relevant if the Add Existing Users setting is checked.
Forminator Integration
This section is entirely optional. We have found that Forminator Forms provides the best level of simplicity and capability when generations forms for logging in, registering users, password management and providing profile editing. The use of Forminator Forms is entirely option and any well-written plugin to provide these functions should work with this plugin, as long as they follow standard WordPress methods. For more information on Forminator Integration click here. For details on the WordPress hooks that the plugin uses see the How it Works section, Whichever plugin or custom coding you use to implement login, registration, password management and profile management, it must use WordPress calls to trigger the TNG integration.
Before completing this section go to the form download section and get the forms you want. Install them per the instructions in that section. Then create the pages containing the form shortcode that you want to be functional. If you decide to use the password reset form, then also create a page, suitably names, with the short [sso_for_tng_new_password] installed.
Name the page something related to its functionality for easy identification in the settings. You do not have to implement all forms, but best results will be had if you do.
To activate the integration check the Activate the Forminator Forms Integration checkbox. Additional configuration fields will display, as described below.
Forminator Pages
For each of the Forminator Forms you intend to use, you will need to put the associated shortcodes on specific pages. In the following selection you will choose which form to use for a particular function, and the page where the related shortcode is installed.
Login Page
Select the Forminator form to use for log-in, and page where you installed the log-in form shortcode. Each dropdown will also show the related ID for easier identification.
Registration Page
Select the Forminator form to use for registration, and the page where you installed the registration form shortcode. Each dropdown will also show the related ID for easier identification.
Profile Page
Select the Forminator form to use for user profile management, and the page where you installed the profile form shortcode. Each dropdown will also show the related ID for easier identification.
Password Reset Page
Select the Forminator form to use for Password Reset and the page where you installed the password reset form shortcode. Each dropdown will also show the related ID for easier identification. Also select the New Password Entry Page where you installed to [sso_for_tng_new_password] shortcode.
Software Disclaimer
You must check this box to complete the settings and allow them to be saved.
While the author (Author) of this plugin make every effort to deliver high quality software, Author does not guarantee that its software is free from defects. The software is provided ‘as is’, and you use the software at your own risk.
This plugin may make changes to your installation of The Next Generation (TNG) application. Author excepts no responsibility, either expressed or implied, for any undesirable changes it may make to the TNG software.
Author makes no warranties as to performance, merchantability, fitness for a particular purpose, or any other warranties whether expressed or implied.
No oral or written communication from or information provided by Author shall create a warranty. Under no circumstances shall Author be liable for direct, indirect, special, incidental, or consequential damages resulting from the use, misuse, or inability to use this software, even if Author has been advised of the possibility of such damages.
Save Changes
When you are satisfied with your entries click this button. Success, or any problems with your entries, will display at the top of the page.
IMPORTANT SHORT CODES
In order for the plugin to work corrected the following two short-codes must be installed on pages in your site.
Login Short-code
Create a new blank WordPress page called TNG Login with a slug of tng-login. The end result should be that it is publicly accessible at https://<your domain>/tng-login. If your theme has a template for a blank page then use that, but if not you can just put some words on it indicated that the user is being redirected. Then anywhere on the page put the short-code [sso_for_tng] (including the square brackets).
Logout Short-code
When a user logs out of WordPress the site usually returns to the Home page. Whichever page yours returns to put the short-code [sso_for_tng_logout] (including the square brackets) anywhere convenient on the page. It logs the user out of TNG in the background, and does does not emit any text to your page.
HOW THE PLUGIN WORKS
The plugin uses a number of standard hooks to implement successful operation. Any login, registration or profile plugin or code must use these standard hooks to result in successful single sign-on to TNG.
These actions are used by the plugin. Click the action name to see the relevant WordPress documentation in a new browser tab:
| Hook | WordPress Action | Used by plugin to |
| wp_authenticate | Fires before the user is authenticated | save the password for TNG login later |
| wp_login | Fires after the user has successfully logged in | intercept login to log in to TNG, or optionally add a new TNG user |
| clear_auth_cookie | Fires just before the authentication cookies are cleared | intercept logout to clear cookies created by the plugin |
| user_register | Fires immediately after a new user is registered | intercept a registration and add user to TNG f not already registered there |
| delete_user | Fires immediately before a user is deleted from the site | intercept WordPress account deletion and also deletes TNG account if it exists |
| profile_update | Fires immediately after an existing user is updated | intercept WordPress user’s profile change to update name and email in a related TNG |
| password_reset | Fires before the user’s password is reset. Triggered by WordPress function reset_password | intercept password change and update related password in related TNG account* |
| after_password_reset | Fires after the user’s password is reset Triggered by WordPress function reset_password | intercept password change and update related password in related TNG account* |
*For the password reset actions at least one of them must fire. It is OK if they both do.
It is essential that these fire as expected and that any login, registration or profile plugin or code does not interfere or replace their operation with non-standard WordPress actions. Note that passwords are NEVER stored on your computer in cleartext, but rather are stored using strong encryption in a cookie.
Depending upon the method used to link between the WordPress and TNG site, communications is either performed by direct read-write operations performed on the TNG database, or by Internet communications with a custom file placed on the TNG site. For more information see the TNG Link Method on this page.
FORMINATOR INTEGRATION
As mentioned above, the use of Forminator Forms to provide login, registration, password management, and profile operations is entirely optional. Any well-written plugin designed to perform these functions should work successfully, but that is not guaranteed. However, whichever one you use it must NOT allow passwords to be created that are shorter than 10 characters, as this is the minimum permitted by TNG.
We have found that Forminator Forms provides good functionality.
You can optionally download predesigned forms here for the 4 functions:
Once downloaded, the file can be opened and the contents copied to the clipboard and pasted into the imported popup in the Forminator Forms section. Make sure you review the forms for settings such as administrator email address and redirection links. Also each form uses Cloudflare’s Turnstile CAPTCHA form protection system, so you will need to enter your keys in the Forminator Setting page. See instructions on how to get your API Keys. Forminator does offer alternative protection schemes, however I found that Google’s ReCaptcha does not work properly in the Firefox browser. Removal of the reCaptcha form elements is not recommended.
The Login-Logout plugin here does a good job of giving control over what is used to implement those functions. Although not recently updated it is working on my WordPress installation V6.8.1. This is not your only choice though, as there are many other plugins that perform the same service.
Setting Screen Examples
The first screenshot is of the upper part of the settings page. The second is the lower part when the Forminator Integration is activated. Click the thumbnail to see them full size in a new browser tab.
 Screenshot #1 Basic Configuration |
 Screenshot #2 Optional Forminator Configuration |
INSTALLATION AND CONFIGURATION ASSISTANCE
I regret that it is not practical to provide assistance in this area. A degree of knowledge of WordPress is assumed and enough information has been provided here to arrive at a suitable outcome. Questions can be submitted here and I will do my best to provide answers.
Recent Comments