kba-team/micro-auth-lib

External micro-service authentication library used by the service and the clients.

v1.1.0 2024-04-05 18:24 UTC

Requires

• php: ^7.4|^8.1

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

• Gregor

README

External micro-service authentication library used by the service and the clients.

Usage

Require kba-team/micro-auth-lib using composer.

Server

The browser gets redirected to the protected authentication micro-service. The micro-service reads the request and redirects the browser back to the specified referer with the authenticated result.

In this example the micro-service is protected by a kerberos authentication. After successful authentication Apache2 writes the authenticated name to the REMOTE_USER server variable.

Create a keytab file for the authentication, enable the auth_kerb Apache2 module and add the following to your (virtual hosts) configuration.

<Directory /path/to/your/micro-service>
    AuthName "Kerberos Login"
    AuthType Kerberos
    Krb5Keytab /etc/apache2/keytabs/auth.service.test.keytab
    KrbSaveCredentials off
    KrbVerifyKDC off
    KrbMethodNegotiate on
    KrbMethodK5Passwd on
    KrbServiceName HTTP
    KrbLocalUserMapping on
    Require valid-user
    Require env
    Options FollowSymLinks
    AllowOverride All
</Directory>

The micro-service itself is just the following PHP file.

<?php
require_once 'vendor/autoload.php';

use kbATeam\MicroAuthLib\AuthResult;
use kbATeam\MicroAuthLib\Checksum;
use kbATeam\MicroAuthLib\Exceptions\InvalidParameterException;
use kbATeam\MicroAuthLib\Request;
use kbATeam\MicroAuthLib\Response;

//shared secret of client and server
Checksum::setSecret('shared secret');
try {
    //read and validate the GET request
    $request = Request::read($_GET);
    //get the authentication result from apache2 in REMOTE_USER
    $authResult = AuthResult::read($_SERVER);
} catch (InvalidParameterException $exception) {
    header($_SERVER['SERVER_PROTOCOL'] . ' 500 Internal Server Error', true, 500);
    exit(500); //This is just a quick example. Please don't do this in your code.
}

//build client response and redirect there
$response = new Response($authResult->getAuthName(), $request->getId());
header('Location: ' . $response->getLocation($request->getReferer()), true, 302);

Client

Redirect the browser to the micro-service and read its response encoded in the following GET request.

<?php
require_once 'vendor/autoload.php';

use kbATeam\MicroAuthLib\Checksum;
use kbATeam\MicroAuthLib\Exceptions\InvalidParameterException;
use kbATeam\MicroAuthLib\Request;
use kbATeam\MicroAuthLib\Response;
use kbATeam\MicroAuthLib\Url;

//Insert the shared secret for kba-auth here.
Checksum::setSecret('shared secret');

if (isset($_COOKIE['micro-auth-id'])) {
    //Get the ID from the cookie and delete the cookie.
    $kbaAuthId = (int)$_COOKIE['micro-auth-id'];
    setcookie('micro-auth-id', null, -1);
    //Read the parameters from the GET request generated by kba-auth.
    try {
        $response = Response::read($_GET);
    } catch (InvalidParameterException $exception) {
        echo $exception->getMessage();
        die(); //This is just a quick example. Please don't do this in your code.
    }
    //Compare the ID from the request and the cookie for extra security.
    if ($response->getId() === $kbaAuthId) {
        echo 'Hello ' . $response->getAuthName() . '!';
        die(); //This is just a quick example. Please don't do this in your code.
    }
}

//Generate a random ID and save it to a cookie.
$kbaAuthId = rand(1000, 9999);
setcookie('micro-auth-id', $kbaAuthId);
//Generate a new request for kba-auth and add the ID and the referer.
$referer = new Url('https://myapp.test/test.php');
$request = new Request($referer, $kbaAuthId);
//Redirect the browser to the kba-auth service.
$kbaAuth = new Url('https://auth.service.test/');
header('Location: ' . $request->getLocation($kbaAuth), true, 302);