the-kbA-team/micro-auth-lib

# Micro Auth Lib

[![License: MIT]](LICENSE)
[![Build Status]][travis-ci]
[![Maintainability]][maintainability]
[![Test Coverage]][coverage]

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

![Sequence diagram for this library]

## 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.

```apacheconf
<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
<?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
<?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);
```

[Sequence diagram for this library]: https://www.planttext.com/api/plantuml/svg/bPFVQy8m4CVV-rSSKgp2jCEnbqBzCIWJnfXitPimilQs1cjQagl--xlMrZcrcti9bylT9vTyxwQ6XAPYdLeYpuU4Xc0mXiRsm9On-A25YdlzfR8rVg16xIT4kV5Sjmbq2uFQJRDFgJWgIZ1Q-OamISys8YKOLXnUwtn66II8icmb4RQIaZB0-b73dSws3FLW7eOBkBaUWIWe6R9h8oDqgqsUv9EbaZudTxNVqBkHlol1icf8oUiSfaDlbWkE6VKx7jm78Lo6QsFypgzDU43zZZepIpNZK5Ga8q4oK__YBkQBakay1uzFOV3s-X8yEoU0AgWzUIDI6Gl2tkvTLz2gaatS7-kSMy1HsTPXHoaqRm-kRmHdxpd9Qm9RPMg_lTPJmPj2zgAGN-EwXL_XpalztRwLj4sFNeGvFmP__TZH8_aYitUEgx-30TmQPrATiFWQGHptFn_6c2BXoM1CKSKyery0
[composer]: https://getcomposer.org/
[License: MIT]: https://img.shields.io/badge/license-MIT-blue.svg
[Build Status]: https://api.travis-ci.com/the-kbA-team/micro-auth-lib.svg?branch=main
[travis-ci]: https://travis-ci.org/the-kbA-team/micro-auth-lib
[Maintainability]: https://api.codeclimate.com/v1/badges/4a476b8f42f9f6dfe89c/maintainability
[maintainability]: https://codeclimate.com/github/the-kbA-team/micro-auth-lib/maintainability
[Test Coverage]: https://api.codeclimate.com/v1/badges/4a476b8f42f9f6dfe89c/test_coverage
[coverage]: https://codeclimate.com/github/the-kbA-team/micro-auth-lib/test_coverage