Installation Instructions

Introduction

Feature List

  • Registration - AJAX, Responsive, Email Verification (can be switched off in Config), Email Verification Resend option
  • Log In - AJAX, Responsive, limited amount of retries within 30 minutes (can be switched off in Config), Remember Me
  • Password Reset / Forgotten Password - AJAX, Responsive, Email Resend option
  • Account Dashboard - Responsive
  • Password Change - AJAX, Responsive
  • Profile Update - AJAX, Responsive
  • Log Out - Responsive
  • Installation Instructions and Tutorial
  • Function documentation with examples
  • Unit Tests with PHPUnit
  • Customizable email templates
  • Native AWS SES support
  • Strong security features (strong password hashing, brute force countermeasures, replay countermeasures, PDO database connection with prepared statements)
  • Lots of optional Configuration settings
  • CRUD Aliases
  • Can be used under CLI
  • Built with PHP7 in mind

System Requirements

  • PHP 5.5 or newer (PHP7 is supported)
  • Extensions:
    • PDO / MySQLi
    • CURL (only if you plan to send emails using AWS SES)
    • openssl (only for PHP5)

Config.php - The Configuration File

  • Filename: Config.php
  • File Location: / (library root folder)

Database

Insert the database schema

  • Schema filename: NAuthentication.sql
  • Schema location: /install/NAuthentication.sql
  • How to insert using PhpMyAdmin:

Change database credentials

  • $DB_Host
    Database location. Remote connections are supported (for example, AWS RDS).
    1. Local database engine example:
      localhost
    2. Remote database engine example:
      instance_name.account_id.ap-southeast-1.rds.amazonaws.com:3306
  • $DB_Name
    Database name. You can use a database you already have, since the tables are prefixed with NAuthentication_, so you don't have to worry about table name clashing.
  • $DB_Username
    Database username.
  • $DB_Password
    Database password.

Account Activation & Password Reset URLs

Site Name

  • $Site_Name
    Your site name. The name is used in account activation and password reset emails sent by the library.

Account Activation Settings

  • $Account_Activation_Required
    true or false. Defaults to true. If set to false, then the account activation directives in this subsection won't apply, and account is automatically activated upon registration.
  • $Account_Activation_URI
    Web page address where the account activation is processed.
    Example:
    http://domain.com/NAuthentication/examples/register/activate-account.php
  • $Account_Activation_Subject
    Account activation email subject.
    Example:
    Confirm your registration at My Website

Password Reset Settings

  • $Password_Reset_URI
    Web page address where the password reset is processed.
    Example:
    http://domain.com/NAuthentication/examples/password-reset/password-reset-new-password-form.php
  • $Password_Reset_Subject
    Password reset email subject.
    Example:
    Your password reset request at My Website

 

Email

Sender Address

  • $No_Reply_Address
    When dispatching emails regarding account activation and password reset, this is the email address that will be used in the From header.
    Example:
    [email protected]
    Notice: if you decide to use AWS SES as your outbound gateway, make sure you verify this email as yours before trying to use it. You can do so in the AWS Management Console.

Outbound Email Gateway Settings

  1. Using your webserver (or to be more technically correct, mailserver) as an outbound email gateway (default)
    • $Use_SES false
    • Emails will be sent using PHP's mail() function, which should work on all shared hosting environments.
  2. Using Amazon Web Services Simple Email Service (AWS SES) as an outbound email gateway
    • $Use_SES true
    • Emails will be sent using AWS SES API. Recommended for VPS or dedicated servers.
      • $AWS_Email_Region
        AWS SES Email Region
        Example:
        email.eu-west-1.amazonaws.com
      • $AWS_Access_Key_ID
        AWS Access Key
        Example:
        AKIABY5B1APERBYAAMVK
      • $AWS_Secret_Key_ID
        AWS Secret Key
        Example:
        e915259c4b9a67d59fc216/222+bfdf407ef4b23d7059

 

END OF CONFIGURATION

You're done configuring. What follows are examples and tips that will help you get started.

Note: there are many more configuration directives in Config.php, including, but not limited to, error messages, which you can also customize. All Config directives can be changed on runtime, too.

 

Function Reference

Developer Manual

For a full function reference, please use the documentation shipped with this library - it can be found inside the docs folder, or by clicking here.

Library Implementation

This library has been implemented in full inside the examples folder. You can use that very folder for your own site, or just use it a quick reference when you're implementing the library into your project. The library was designed to work under webserver, fast-CGI and CLI environments; meaning that the usage of the library is not limited to websites.

Examples (desktop is 1024 pixels wide, large desktop is 1440 pixels wide)

  • Register
    • Register - Desktop Layout
    •  
    • Register - Tablet Layout
    •  
    • Register - Phone Layout
    •  
    • Register - Email Message
    •  
    • Register - Successful (on desktop)
    •  
    • Register - Resending Activation Email (on desktop)
    •  
    • Register - Error (on desktop)
  • Account Activation
    • Account Activation (on desktop)
  • Log In
    • Login - Desktop
    •  
    • Login - Tablet
    •  
    • Login - Phone
    •  
    • Login - Error (on desktop)
  • Members Area - Dashboard
    • Dashboard - Large Desktop
    •  
    • Dashboard - Desktop
    •  
    • Dashboard - Tablet
    •  
    • Dashboard - Phone
  • Members Area - Change Password
    • Change Password - Desktop
    •  
    • Change Password - Tablet
    •  
    • Change Password - Phone
  • Members Area - Update Profile
    • Update Profile - Desktop
    •  
    • Update Profile - Tablet
    •  
    • Update Profile - Phone
  • Log Out
    • Log Out - Desktop
    •  
    • Log Out - Tablet
    •  
    • Log Out - Phone
  • Password Reset (forgotten password)
    • Password Reset - Desktop
    •  
    • Password Reset - Tablet
    •  
    • Password Reset - Phone
    •  
    • Password Reset - Success (on desktop)
    •  
    • Password Reset - Error (on desktop)
    •  
    • Password Reset - Email
  • Password Reset - New Password
    • Password Reset > New Password - Desktop
    •  
    • Password Reset > New Password > Success - Desktop
    •  
    • Password Reset > New Password > Success - Tablet
    •  
    • Password Reset > New Password > Success - Phone

Library Insights & Tips

  • IPv6 Ready √
  • Amazon Web Services (AWS) Ready √
  • All Config directives can be changed on runtime. For instance, you might have one registration form where minimum password length of 6 chars, and another one where the minimum is 10 chars. All you need to do is \NAuthentication\Config::$Minimum_Password_Length = 6 where you want the enforce 6 chars as password length minimum, and \NAuthentication\Config::$Minimum_Password_Length = 10, and where you want 10 chars as password length minimum. This can be on the same page, too.
  • Database connection is handled by the library itself. A PDO link is used throughout the whole library, for every query. Database connections are very cheap when it comes to resources, but if you want to, you can make the library use a PDO link you've already establihed by pointing Utils::$dbInstance to your already established database connection. Consequently, you can have the library initiate the database connection, and then you can use that connection by using the aforementioned property.
  • Regarding cookie and session name: by default, session cookie and the session itself will be called PHPSESSID. I've made this the default for the sake of simplicity and ubiquity towards existing PHP code. If you want to use library's session name (which will, in turn, start setting a session cookie with that name), change $Use_Library_Session_Name directive inside Config.php
  • By default, minimum password length is 5, which can be changed by modifying $Minimum_Password_Length inside Config.php
  • By default, the maximum amount of incorrect passwords for email/IP combo is 10 attempts per 30 minutes. You can change it by modifying $Maximum_Log_In_Retries_In_30_Minutes inside Config.php (if you want to disable this feature, use PHP_INT_MAX constant instead of a number).
  • You can change which input fields are mandatory. The fields enforced by default are email address and password, but they can be completely turned off, other fields can be enforced instead or in conjunction with aforementioned, etc.
  • Never disclose tokens to users, except emailing them. I suggest storing them in a session. See examples too learn more (specifically register and password reset handlers).
  • The database is cleaned up automatically.

 

Unit Testing

Tests are written for PHPUnit testing suite. To run tests, go to the library folder and execute the following in your terminal:

phpunit

 

Addendum

Support, implementation and customization

If you'd like me to integrate this library into your project, please send an email to [email protected]. Please include details regarding what needs to be done, and I'll be reply back with availability and rates (I'll most likely be ready to start within 24 hours, and my rates will be ranging from $25 to $33 per hour, depending on the amount of work I have at that moment). If you only have a question to ask, feel free to send me an email and I'll reply free of charge.

Bug reports and feature requests

If you have any of these, feel free to send an email to [email protected]. Have in mind, though, that a lot of features are already on the TODO agenda. Thank you in advance.

Tell me about your implementation

Feel free to send me the idea and source of your implementation. If it's interesting, I'll include it in the docs pages with a link back to your project. It's good for everyone - people using this library will have more examples to go through, and your project gets more exposure.

 

Back to top