Single Sign On For TNG Plugin
OVERVIEW
This plugin improves the user experience when WordPress and the TNG Genealogy Software are on the same server.
User accounts for both systems are managed through the WordPress user registration system. This includes account creation, deletion, certain account information, and password change.
Logging in and out of the users WordPress account automatically logs in an 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 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.
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 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 that pages where each shortcode is installed.
Login Page
Select the page where you installed to log-in form shortcode.
Registration Page
Select the page where you installed to registration form shortcode.
Profile Page
Select the page where you installed to profile form shortcode.
Password Reset Page
Select the page where you installed to password reset form shortcode.
New Password Page
If you are using the provided Password Reset Page Select the page where you installed to [sso_for_tng_new_password] shortcode.
Forminator Forms
Log In Form
Select the name of the form intended for this purpose. Choose “No Selection” if you do not intend using this form.
Profile Form
Select the name of the form intended for this purpose. Choose “No Selection” if you do not intend using this form.
Lost Password Form
Select the name of the form intended for this purpose. Choose “No Selection” if you do not intend using this form.
Registration Form
Select the name of the form intended for this purpose. When you select the form a second box will appear where you must enter the password field name. This is to allow for the minimum length of 10 characters to be enforced, as wll as the strength of the password. Choose “No Selection” if you do not intend using this form.
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.
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 Google’s reCaptcha form protection system, so you will need to enter your keys in the Forminator Setting page. Instructions are there if you don’t have keys yet. Removal of the reCaptcha form elements is not recommended. However, Forminator does offer alternative protection schemes.
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