Loading...

Preface

AuthStack provides an Authentication framework which serves as a toolset for creating custom drivers. We understand that we cannot provide a solution that fits every requirement out of the box, therefore we have provided flexibility for you to adapt AuthStack to suit your individual needs. This document serves as an introduction to concepts within AuthStack and should be reviewed before creating a custom driver.

AuthStack is written in PHP, code examples and code-related documentation will be provided in PHP.

Terminology

Term Description
Authentication Source   A service that stores user information. This can be a database (MySQL, Postgres, MSSQL), LDAP-server (OpenLDAP, Active Directory) or even a web resource (RESTFul service). This is an abstraction in AuthStack
Driver Driver performs the logic behind connecting to Authentication Source and authenticating the user.
Connection Connection supplies configuration for the Driver. It contains config information about the service (IP, ports, username and password if needed, certificates, etc) and which user attributes to retrieve.
Provisioned User When a user authenticates for the first time, they are provisioned to AuthStack's database. AuthStack provisions only one attribute - the username and which connection has been used to authenticate the user.

Introduction to Drivers

A driver is a set of functions and classes that connect to a service, which can be MySQL, MSSQL, MongoDB, RESTful endpoint, SOAP API, etc. The logic behind a driver is to allow for completely bespoke logic, on a per installation basis, according to your business requirements.

AuthStack doesn't make a distinction between a driver for an RDBMS or for RESTful endpoint, flat file and so on. If there exists a service which contains user information, AuthStack can be adjusted to connect to that service.

Connection provides configuration values so that Driver can connect to authentication source. Driver passes user-supplied credentials to authentication source. If successful, Driver creates a User object which is used internally by AuthStack.

There are four important tasks that Drivers perform:

  1. Connecting to an endpoint / service
  2. Implement logic behind authentication
  3. Query the data source about the user
  4. Return attributes / data related to the authenticated user

AuthStack bundles with existing driver(s) and tools to create new custom drivers, including a demo MySQL driver, which contains a detailed explanation within the code. The demo MySQL driver ships with a demo SQL file, the whole process is available to view and recreate.

To view existing drivers, run the following CLI command:

authstack-ctl driver:list

The title, description and class path will be displayed.

Further Explanation and Examples

Driver

  1. Connects to a service
  2. Implements logic that verifies if entered credentials are correct

Connection

  1. Contains information that the driver uses for connecting; IP, port, usernames, passwords, certificates - what connection stores is dependent on what the driver needs to establish the connection
  2. Contains a list of attributes that we'll get from the authentication source. Attribute list is a simple list of attribute names.

Note: There can be multiple connections for a single driver.

Provisioned User

When users are authenticated, AuthStack saves them to its own database. Light provisioning allows AuthStack to link users to multi-factor authentication keys and to maintain correct licensing metrics.

Visualising Driver, Connection and Provisioned User

To demonstrate how a Driver, Connection and Provisioned User relate to one another, we are going to use a classic example, connecting to a MySQL database:

Assumptions

  • MySQL is installed on 127.0.0.1
  • We're using users table
  • We're using PDO
  • User password is stored in the database using PHP's password_hash function
<?php

// Define MySQL connection information

$db_host = '127.0.0.1';
$db_database = 'test_database';
$db_username = 'test_user';
$db_password = 'test_password';

$dsn = sprintf("mysql:dbname=%s;host=%s;charset=UTF8", $db_host, $db_database);

// Connect to MySQL
try
{
    $pdo = new PDO($dsn, $db_username, $db_password);

    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
}
catch(PDOException $e)
{
    printf("An error occurred while connecting: %s", $e->getMessage());
    exit(1);
}

// Let's assume that there's a $_POST superglobal that contains $_POST['username'] and $_POST['password']

try
{
    // Prepare the statement which pulls the user out
    $stmt = $pdo->prepare("SELECT id, username, password, first_name, last_name FROM users WHERE username = :username");

    // Bind the username value
    $stmt->bindValue(':username', $_POST['username']);

    $stmt->execute();

    $attributes = $stmt->fetchAll(PDO::FETCH_ASSOC);

    // If $attributes is empty, then we got no record back - user doesn't exist
    if(!count($attributes))
    {
        printf("No such user in database: %s", $_POST['username']);
    }

    // There's one user, advance the array and save the data into $user variable
    $user = $attributes[0];

    // Let's verify the password in $_POST with the hash in the database
    $verified = password_hash($_POST['password'], $user['password']);

    // Password is incorrect
    if(!$verified)
    {
        echo "Incorrect credentials";
        exit(1);
    }

    // If we got to this line, the variable $user will contain the following:
    //
    // id
    // username
    // password
    // first_name
    // last_name

    echo <<<EOF
    <h4>Authenticated successfully!</h4>

    <p>Information we have on you:</p>

    <ul>
        <li>ID: $user['id']</li>
        <li>First name: $user['first_name']</li>
        <li>Last name: $user['last_name']</li>
        <li>Email: $user['email']</li>
    </ul>
EOF;

}
catch(PDOException $e)
{
    printf("An error occurred while querying database: %s", $e->getMessage());
    exit(1);
}

The script above connects to MySQL, performs a query and retrieves data from query. The screenshot below highlights areas of code related to the AuthStack process.

  1. Red lines are Connection, which relates to configuration
  2. Green lines are Driver, it uses configuration and implements logic behind connecting and authenticating
  3. Blue line is User, it contains user information

file


Previous Article

Localisation

Next Article

Creating a new Driver

We're happy to talk

Our offices are open 8.30am - 7pm GMT, Monday to Friday - but you can always contact us via email. When we receive your email during opening hours, we aim to respond within 30 minutes or less. Should your email reach us out of hours, we will contact you when the office re-opens.

You can contact us using live chat