~HowTo.txt

                                MYDBLOGIN-PMW

                        MyDBLogin - Version 2021_02_12

  
               External MySQL user authentication for PMWiki  
    Original content Copyright 2021 Kirk Siqveland (Kirk@CyberTamer.com)

    This file is distributed under the terms of the GNU General Public 
    License as published by the Free Software Foundation; either 
    version 2 of the License, or (at your option) any later version.  

    MyDBLogin uses a simple set of MySQL pages embedded via an iFrame to be
    used within a PMWiki installation to control access to page Groups or 
    even individual pages.  You will need the other files in the recipe for
    this to work.

    For all the files and instructions goto:
    https://www.pmwiki.org/wiki/Cookbook/MyDBLogin


----------------------------------------------------------------------------------


-- By default all examples assume you are using /pmwiki/ as your PMWiki directory.
If you did not install to the default directory, just adjust accordingly.
Your PMWiki directory is where you installed the pmwiki.php file:
E.g.   www.myexampledomain.org/pmwiki/pmwiki.php
Examples such as "/cookbook" assume you start from that PMWiki directory -
E.g.   www.myexampledomain.org/pmwiki/cookbook



For your first time through, if you are not already an expert I suggest using just 
the default settings to prove it works, then make changes.
- I often make full pmwiki installations just to have a default baseline to test
  how some recipe or idea works, before loading up to a live installation.



----------------------------------------------------------------------------------

INSTALLATION SUMMARY:

To use MyDBLogin as a parallel user-authorization tool for PMWiki you will need:

1. The MyDBLogin Zip archive - if you didn't get this file from the archive visit
  https://www.pmwiki.org/wiki/Cookbook/MyDBLogin-PMW and download MyDBLogin.zip
2. A MySQL database you can access programatically (usually on your web-server)
3. A copy of PHPMailer installed on your webserver - instructions below.

It is best to start with the non-PMWiki parts
I can't take on a full tutorial on setting these up when the web is full of good
information and when different web-hosting services have different requirements.
But, here's the short-and-sweet version:


MySQL -

  The MySQL database needs one or two tables with specific fields.  
  Scripts are provided below to make creating the tables easy.  
  - !! If you are using a White-List to limit available users, 
        you need to populate the White-List table with the approved emails.
       If not, in _setup.php make the value of $UseWhitelist  = false;

    Everyone has their preferrences, but I'm used to handling my admin
    tasks for MySQL with PHPMyAdmin (built-in to my hosting service)
      https://www.phpmyadmin.net/

    [ I happen to love using MySQL for Excel for Windows to update 
    [  large blocks of data.
    [  I don't know if it is still being developed but it works great for me!
    [    https://downloads.mysql.com/archives/excel/  

  - I recommend you test simple programmatic connections to the database first
      https://www.w3schools.com/php/php_mysql_connect.asp

Once you have the table(s) set up and tested -  Let's move on...


PHPMailer - 

  This lets the Wiki, automatically email from the server hosting the wiki-site.
  Other providers may have different rules but mine makes it quite easy and
  has a tutorial to walk you through setting it up.

  Below are the details on that.

  Again, I would make a few simple tests to be sure everything works before 
  moving on.


PMWiki -
  This is a pretty standard recipe install now.

  From the Recipe page download the mydblogin.zip

  The Zip archive (mydblogin.zip) has three subdirectories.
  - The contents of /cookbook should go to your pmwiki/cookbook directory
  - The contents of /local should go to your pmwiki/local directory
  - and the contents of /mydblogin need to go to their own /mydblogin directory:

  The MyDBLogin files should be in the Same domain as your PMWiki installation 
  - BUT NOT in the same directory as the PMWiki installation.
    e.g. PMWiki is installed at     www.myexampledomain.org/pmwiki
    and MyDBLogin is installed at   www.myexampledomain.org/mydblogin
    (good practice: be sure you have an .htacces file protecting this directory.)

  - Note: the /local/Turnstile.Template.php is a Template
    You will want to make a copy and then rename it depending on what you want to protect:

    the copy should be named to match the PMWiki Group or Page you want protected
    e.g. to protect all pages in the Members group:   rename the copy to "Members.php" (no quotes)
    or for just the Members.Directory page, rename the copy to "Members.Directory.php" (no quotes)

    for more on how PMWiki uses Groups and Customization of Groups:
       https://www.pmwiki.org/wiki/PmWiki/GroupCustomizations

  You can edit the Template file to set the user authorization level allowed to read/access the page.
  - Since we are sorting by authorization Class to identify individuals and groups, 
    you can use the stub-code provided to allow you to do special things.
    BUT,you do not need anything more than changing the name for the file to provide simple
    Pass/Faill permission to read/access the Group or the Page.
    (The Turnstile.Template.php file also contains lots of detailed instructions.)



Now for the Recipe Code... 

To your  /local/config.php   file
Add the following lines.
IF you did not use the default locations, MODIFY to match your installation


##----- MYDBLOGIN  Authorization Recipe ------
  session_start() ;
  $_SESSION['Synch_ID']= session_id() ; 
## Define the path (same domain, different directory) for all the 
##   MyDBLogin files.
##   (This is the path relative to the domain root, not the full URL)
##   So for  https://www.myexampledomain.org/mydblogin you only need:
##      $MyDBLoginDir  = '/mydblogin'           ;
  $MyDBLoginDir   = '/mydblogin'          ;
## - WikiPage is the Groupname/Pagename for the PMWiki page you will use to
##   host the MyDBLogin pages - You only need one page for MyDBLogin.   
##   REMEMBER - This page cannot be password protected!!
##   by default this would be 'Turnstile/Validate'
##   - NOTICE - no "/" to start!
  $MyDBL_WikiPage = 'Turnstile/Validate'      ;
## - AuthFail is the Groupname/Pagename for the PMWiki page you will use to
##   host the MyDBLogin pages - You only need one page for MyDBLogin.   
##   REMEMBER - This page cannot be password protected!!
##   by default this would be 'Turnstile/Validate'
##   - NOTICE - no "/" to start!
  $MyDBL_NeedAuth = 'Turnstile/NeedAuth'      ;  
##  Now we can include the code for the MyDBLogin recipe:
  include_once("$FarmD/cookbook/mydblogin.php")   ;


ALMOST THERE  - WE JUST NEED TO DOCUMENT WHAT WE HAVE DONE:

After you have set up PHPMailer and your MySQL database and your /local/config.php
you will need to add all the Configuration details to /mydblogin/_setup.php 
located in the /mydblogin directory - not in your /pmwiki directory.

I have tried to make this file as clear and full of instructions as you need.
- Once you have filled in all the details it asks, save to the /mydblogin directory.

------------------------
--- Ready to Try it Out?

In your PMWiki, create the page to host the Login screens - I use the default of
Turnstile/Validate
If you use something else be sure to set $MyDBLoginPage in the _setup.php file.

Now simply edit the [[Turnstile/Validate]] wiki page with the following markup
- being sure to use the path to YOUR MyDBLogin directory:

(:MyDBLogin https://www.myexampledomain.org/mydblogin/ :)     


You should now be able to see and use the /Turnstile/Validate page
- try Registering, Validating, Changing your password Loging-in and Loging-out

Once all that works, you can set up a Wiki-Group, add the renamed copy of 
Turnstile.Template.php to your /local directory, and add a few pages with content and
you should see things work!

For example 

1. Create a link to [[Members/Members]]
2. Follow the link, add some content, maybe add more pages.
3. Copy Turnstile.Template.php and rename the copy to /local/Members.php 
4. Now logout and try to follow the link to [[Members/Members]]

Fingers crossed, you can't get in, until you Log-in using the MyDBLogin page!


I hope you enjoy using MyDBLogin!
If you find bugs, or have recommendations please share them on the recipe talk page!


-----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------

Details for For PHPMailer

- if you don't already have it set up:
Your Web Host may have different requirements, so I'd start by looking up what they say.
Here's what I do, and I think it's pretty standard for many servers:

1 - Log into your server via SSH.
    Make sure you're in your user's home directory.

    [server]$ cd ~

2 - Download the PHPMailer zip file from GitHub.com.

    [server]$ wget https://github.com/PHPMailer/PHPMailer/archive/master.zip

3 - Unzip the file.

    [server]$ unzip master.zip

4 - This creates a directory named PHPMailer-master.
    Rename this directory to just PHPMailer.

    [server]$ mv PHPMailer-master PHPMailer

That's it!


	
---------------------------------------------------------------------------------

Details for For MySQL 

- Your server needs to be set up for MySQL - I've never had to install it on a server...
  so -  if your server doesn't have it you will have to do some research.

We need a database with two tables (name them as you please but change the settings.)

mydbl_whitelist   
mydbl_users	
	
the whitelist table only really needs the emails - but you should have an index too e.g.:
Table: mydb_whitelist
Field: wlst_idx 
Field: wlst_email

The user table might well be used for other things but here's the bare bones for MyDBLogin:
Table: mydb_users
Field: user_idx
Field: user_name
Field: user_email
Field: user_pw
Field: user_auth_level
Field: user_auth_code
Field: user_status
Field: user_token


To Make it Even Easier, here are the Create - Scripts for both tables:

MySQL create table code for the
WHITELIST Table:


CREATE TABLE `mydb_whitelist` (
 `wlst_idx` int(4) NOT NULL AUTO_INCREMENT,
 `wlst_sid` varchar(60) DEFAULT NULL,
 `wlst_email` varchar(255) NOT NULL,
 PRIMARY KEY (`wlst_idx`)
) ENGINE=InnoDB AUTO_INCREMENT=209 DEFAULT CHARSET=utf8


The mydb_usders table by default adds Edit permission and the
Edit password to each new user.

MySQL create table code for the
VALIDATED USER Table:
  ( !! NOTE the Defualt for the user_auth_code 
    That needs to change to your PMWiki 'edit' password. )


CREATE TABLE `mydb_users` (
 `user_idx` int(11) NOT NULL AUTO_INCREMENT,
 `user_name` varchar(100) NOT NULL,
 `user_email` varchar(100) NOT NULL,
 `user_pw` varchar(100) NOT NULL,
 `user_auth_level` varchar(8) NOT NULL DEFAULT 'Edit',
 `user_auth_code` varchar(255) NOT NULL DEFAULT '3ditP@ssw0rd',
 `user_status` enum('Y','N') NOT NULL DEFAULT 'N',
 `user_token` varchar(100) NOT NULL,
 PRIMARY KEY (`user_idx`),
 UNIQUE KEY `userEmail` (`user_email`)
) ENGINE=InnoDB AUTO_INCREMENT=90 DEFAULT CHARSET=utf8



-------------------------------------------------------------------
-------------------------------------------------------------------
OPTION - 
If you don't want any JavaScript you can edit it out, but you will need
to write your Markup with an iframe height declaration.

(:MyDBLogin https://www.myexampledomain.org/mydblogin/ style="height:850px;" :)
