PHP SDK (auris/sdk)

auris/sdk v0.1.0

auris/sdk ist die offizielle PHP-Client-Bibliothek für Auris IAM. Sie implementiert den OAuth2 Authorization Code Flow mit PKCE (S256) und bietet eine saubere API für den Abruf von Benutzerinformationen und die Verwaltung von Tokens.

Die Bibliothek hat keine externen Abhängigkeiten — sie verwendet nur PHP-Builtins (curl, session, hash, openssl) und funktioniert mit PHP 7.4 und höher.

Voraussetzungen

PHP 7.4 oder höher
curl-Extension aktiviert
openssl-Extension aktiviert (für PKCE)
session-Extension aktiviert (für den Standard-SessionTokenStore)

Installation


composer require auris/sdk

Klassen

`AurisConfig`

Enthält alle Konfigurationsdaten für den Auris-Client.


use Auris\AurisConfig;
 
$config = new AurisConfig(
    domain: 'auth.yourdomain.com',               // Erforderlich — dein Auris-Tenant-Domain
    clientId: 'app_xxxxx',                       // Erforderlich — Anwendungs-Client-ID
    redirectUri: 'https://app.com/callback.php', // Erforderlich — muss in der Console registriert sein
    clientSecret: null,                          // Optional — nur für vertrauliche Clients
    scope: 'openid profile email',               // Optional — OAuth2-Scopes
    tenant: 'my-tenant',                         // Optional — als x-tenant-Header gesendet
    tokenStore: null,                            // Optional — benutzerdefinierte TokenStore-Instanz
);

Konstruktor-Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
`domain`	`string`	Ja	—	Auris-Tenant-Domain, ohne `https://`
`clientId`	`string`	Ja	—	Anwendungs-Client-ID aus der Console
`redirectUri`	`string`	Ja	—	Muss exakt mit einer registrierten Callback-URL übereinstimmen
`clientSecret`	`?string`	Nein	`null`	Client-Secret für vertrauliche serverseitige Apps
`scope`	`string`	Nein	`'openid profile email'`	Leerzeichen-getrennte OAuth2-Scopes
`tenant`	`string`	Nein	`'default'`	Tenant-Bezeichner
`tokenStore`	`?TokenStore`	Nein	`null`	Benutzerdefiniertes Speicher-Backend. Standard: `SessionTokenStore`.

`AurisClient`

Die Haupt-Client-Klasse. Mit einem AurisConfig-Objekt instanziieren.


use Auris\AurisClient;
use Auris\AurisConfig;
 
$config = new AurisConfig(
    domain: 'auth.yourdomain.com',
    clientId: 'your-client-id',
    redirectUri: 'https://yourapp.com/callback.php'
);
 
$auris = new AurisClient($config);

`getLoginUrl(options?): string`

Generiert die Auris-gehostete Login-URL einschließlich PKCE-Parametern und einem CSRF-State-Token.


// Zur gehosteten Login-Seite weiterleiten
$loginUrl = $auris->getLoginUrl();
header('Location: ' . $loginUrl);
exit;
 
// Mit zusätzlichen Optionen
$loginUrl = $auris->getLoginUrl([
    'login_hint'  => '[email protected]',
    'screen_hint' => 'signup',
    'locale'      => 'de',
    'prompt'      => 'login',
]);

Verfügbare Optionen:

Option	Typ	Beschreibung
`login_hint`	`string`	E-Mail-Feld vorausfüllen
`screen_hint`	`'signup'`	Registrierungsbildschirm öffnen
`prompt`	`'login' \| 'none'`	Re-Auth erzwingen oder stillen Check
`locale`	`string`	UI-Sprache (en, it, de, fr, es)
`connection`	`string`	Bestimmte SSO-Verbindung erzwingen

`handleCallback(code, state): TokenResult`

Tauscht den auf der Callback-URL empfangenen Authorization Code gegen Tokens. Validiert den State-Parameter gegen den gespeicherten Wert.

Wirft AurisException, wenn der State ungültig ist, der Code-Austausch fehlschlägt oder ein Netzwerkfehler auftritt.


// callback.php
session_start();
 
try {
    $result = $auris->handleCallback(
        code: $_GET['code'] ?? '',
        state: $_GET['state'] ?? ''
    );
 
    echo 'Authentifiziert! Access-Token läuft ab in ' . $result->expiresIn . ' Sekunden.';
 
} catch (Auris\AurisException $e) {
    http_response_code(400);
    echo 'Authentifizierung fehlgeschlagen: ' . htmlspecialchars($e->getMessage());
}

`isAuthenticated(): bool`

Gibt true zurück, wenn der Benutzer ein gültiges (nicht abgelaufenes) Access-Token in der aktuellen Sitzung hat.


if (!$auris->isAuthenticated()) {
    header('Location: /login.php');
    exit;
}

`getUser(): ?AurisUser`

Gibt den aktuell authentifizierten Benutzer durch Decodierung des gespeicherten ID-Tokens zurück.


$user = $auris->getUser();
 
if ($user !== null) {
    echo 'Hallo, ' . htmlspecialchars($user->firstName);
    echo ' (ID: ' . $user->id . ')';
    echo ' Rollen: ' . implode(', ', $user->roles);
}

`getAccessToken(): ?string`

Gibt den gespeicherten Access-Token-String zurück, oder null, wenn nicht authentifiziert.


$token = $auris->getAccessToken();
 
if ($token !== null) {
    $ch = curl_init('https://api.yourapp.com/data');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
}

`refreshToken(): TokenResult`

Tauscht das gespeicherte Refresh-Token gegen ein neues Access-Token- und Refresh-Token-Paar.


try {
    $result = $auris->refreshToken();
    echo 'Neues Access-Token läuft ab in ' . $result->expiresIn . ' Sekunden.';
} catch (Auris\AurisException $e) {
    // Erneuerung fehlgeschlagen — zum Login weiterleiten
    header('Location: /login.php');
    exit;
}

`logout(returnTo?): void`

Löscht die gespeicherten Tokens aus der Sitzung und leitet optional den Browser weiter.


$auris->logout(returnTo: 'https://yourapp.com/');

`AurisUser`

Repräsentiert den authentifizierten Benutzer, dekodiert aus dem ID-Token.


class AurisUser
{
    public string  $id;             // Auris-Benutzer-ID
    public string  $sub;            // JWT-Subject-Claim (identisch mit $id)
    public string  $email;
    public bool    $emailVerified;
    public string  $name;           // Vollständiger Anzeigename
    public string  $firstName;
    public string  $lastName;
    public string  $username;
    public ?string $picture;        // Profilbild-URL
    public array   $roles;          // string[] — zugewiesene Rollennamen
    public array   $metadata;       // Benutzerdefinierte Schlüssel-Wert-Metadaten
    public string  $tenant;
    public string  $createdAt;
}

Benutzerdefinierter `TokenStore`

Das TokenStore-Interface implementieren, um Tokens in einem beliebigen Speicher-Backend zu speichern.


use Auris\TokenStore;
 
class DatabaseTokenStore implements TokenStore
{
    public function __construct(
        private \PDO $pdo,
        private string $userId
    ) {}
 
    public function get(string $key): ?string
    {
        $stmt = $this->pdo->prepare(
            'SELECT value FROM auris_tokens WHERE user_id = :uid AND key = :key'
        );
        $stmt->execute([':uid' => $this->userId, ':key' => $key]);
        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
        return $row ? $row['value'] : null;
    }
 
    public function set(string $key, string $value): void
    {
        $stmt = $this->pdo->prepare(
            'INSERT INTO auris_tokens (user_id, key, value)
             VALUES (:uid, :key, :val)
             ON DUPLICATE KEY UPDATE value = :val'
        );
        $stmt->execute([':uid' => $this->userId, ':key' => $key, ':val' => $value]);
    }
 
    public function remove(string $key): void
    {
        $stmt = $this->pdo->prepare(
            'DELETE FROM auris_tokens WHERE user_id = :uid AND key = :key'
        );
        $stmt->execute([':uid' => $this->userId, ':key' => $key]);
    }
}
 
$config = new AurisConfig(
    domain: 'auth.yourdomain.com',
    clientId: 'your-client-id',
    redirectUri: 'https://yourapp.com/callback.php',
    tokenStore: new DatabaseTokenStore($pdo, $currentUserId)
);

`AurisException`

Von AurisClient bei Fehlern geworfen. Enthält einen maschinenlesbaren $code und eine lesbare $message.

Häufige Fehlercodes:

Code	Beschreibung
`invalid_state`	CSRF-State-Konflikt — möglicher Angriff oder abgelaufene Sitzung
`invalid_grant`	Authorization Code ungültig, abgelaufen oder bereits verwendet
`invalid_client`	Client-ID oder Redirect-URI stimmt nicht mit der registrierten Anwendung überein
`network_error`	cURL-Anfrage an die Auris-API fehlgeschlagen
`token_expired`	Access-Token abgelaufen — `refreshToken()` aufrufen
`no_refresh_token`	Kein Refresh-Token in der Sitzung — Benutzer muss sich erneut anmelden

Reines PHP-Beispiel

Ein vollständiger Login-Flow über vier Dateien:


<?php
// login.php — zu Auris-gehosteter Login-Seite weiterleiten
require 'vendor/autoload.php';
 
use Auris\AurisClient;
use Auris\AurisConfig;
 
session_start();
 
$config = new AurisConfig(
    domain: 'auth.yourdomain.com',
    clientId: 'your-client-id',
    redirectUri: 'http://localhost:8000/callback.php'
);
$auris = new AurisClient($config);
 
header('Location: ' . $auris->getLoginUrl());
exit;


<?php
// callback.php — Rückleitung von Auris verarbeiten
require 'vendor/autoload.php';
 
use Auris\AurisClient;
use Auris\AurisConfig;
use Auris\AurisException;
 
session_start();
 
$config = new AurisConfig(
    domain: 'auth.yourdomain.com',
    clientId: 'your-client-id',
    redirectUri: 'http://localhost:8000/callback.php'
);
$auris = new AurisClient($config);
 
try {
    $auris->handleCallback(
        code: $_GET['code'] ?? '',
        state: $_GET['state'] ?? ''
    );
    header('Location: /dashboard.php');
    exit;
} catch (AurisException $e) {
    http_response_code(400);
    echo '<p>Anmeldung fehlgeschlagen: ' . htmlspecialchars($e->getMessage()) . '</p>';
    echo '<a href="/login.php">Erneut versuchen</a>';
}


<?php
// dashboard.php — geschützte Seite
require 'vendor/autoload.php';
 
use Auris\AurisClient;
use Auris\AurisConfig;
 
session_start();
 
$config = new AurisConfig(
    domain: 'auth.yourdomain.com',
    clientId: 'your-client-id',
    redirectUri: 'http://localhost:8000/callback.php'
);
$auris = new AurisClient($config);
 
if (!$auris->isAuthenticated()) {
    header('Location: /login.php');
    exit;
}
 
$user = $auris->getUser();
?>
<!DOCTYPE html>
<html lang="de">
<head><title>Dashboard</title></head>
<body>
  <h1>Willkommen, <?= htmlspecialchars($user->firstName) ?></h1>
  <p>E-Mail: <?= htmlspecialchars($user->email) ?></p>
  <p>Rollen: <?= htmlspecialchars(implode(', ', $user->roles)) ?></p>
  <a href="/logout.php">Abmelden</a>
</body>
</html>


<?php
// logout.php — Sitzung löschen und weiterleiten
require 'vendor/autoload.php';
 
use Auris\AurisClient;
use Auris\AurisConfig;
 
session_start();
 
$config = new AurisConfig(
    domain: 'auth.yourdomain.com',
    clientId: 'your-client-id',
    redirectUri: 'http://localhost:8000/callback.php'
);
$auris = new AurisClient($config);
$auris->logout(returnTo: 'http://localhost:8000/');

Laravel-Integration

Service Provider

AurisClient als Singleton im Laravel-Service-Container registrieren:


// app/Providers/AurisServiceProvider.php
namespace App\Providers;
 
use Auris\AurisClient;
use Auris\AurisConfig;
use Illuminate\Support\ServiceProvider;
 
class AurisServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(AurisClient::class, function () {
            $config = new AurisConfig(
                domain: config('auris.domain'),
                clientId: config('auris.client_id'),
                redirectUri: config('auris.redirect_uri'),
                clientSecret: config('auris.client_secret'),
                tenant: config('auris.tenant', 'default'),
            );
            return new AurisClient($config);
        });
    }
}

Konfigurationsdatei


// config/auris.php
return [
    'domain'        => env('AURIS_DOMAIN'),
    'client_id'     => env('AURIS_CLIENT_ID'),
    'client_secret' => env('AURIS_CLIENT_SECRET'),
    'redirect_uri'  => env('AURIS_REDIRECT_URI'),
    'tenant'        => env('AURIS_TENANT', 'default'),
];

Controller


// app/Http/Controllers/AuthController.php
namespace App\Http\Controllers;
 
use Auris\AurisClient;
use Auris\AurisException;
use Illuminate\Http\Request;
 
class AuthController extends Controller
{
    public function __construct(private AurisClient $auris) {}
 
    public function login()
    {
        return redirect($this->auris->getLoginUrl());
    }
 
    public function callback(Request $request)
    {
        try {
            $this->auris->handleCallback(
                $request->query('code', ''),
                $request->query('state', '')
            );
            return redirect('/dashboard');
        } catch (AurisException $e) {
            return redirect('/login')->withErrors(['auth' => $e->getMessage()]);
        }
    }
 
    public function logout()
    {
        $this->auris->logout(returnTo: config('app.url'));
        return redirect('/');
    }
}

Middleware


// app/Http/Middleware/RequireAurisAuth.php
namespace App\Http\Middleware;
 
use Auris\AurisClient;
use Closure;
use Illuminate\Http\Request;
 
class RequireAurisAuth
{
    public function __construct(private AurisClient $auris) {}
 
    public function handle(Request $request, Closure $next)
    {
        if (!$this->auris->isAuthenticated()) {
            return redirect('/login');
        }
        return $next($request);
    }
}


// routes/web.php
use App\Http\Controllers\AuthController;
use App\Http\Middleware\RequireAurisAuth;
 
Route::get('/auth/login',    [AuthController::class, 'login']);
Route::get('/auth/callback', [AuthController::class, 'callback']);
Route::get('/auth/logout',   [AuthController::class, 'logout']);
 
Route::middleware(RequireAurisAuth::class)->group(function () {
    Route::get('/dashboard', fn() => view('dashboard'));
    Route::get('/settings',  fn() => view('settings'));
});

PHP SDK (auris/sdk)

Voraussetzungen

Installation

Klassen

AurisConfig

AurisClient

getLoginUrl(options?): string

handleCallback(code, state): TokenResult

isAuthenticated(): bool

getUser(): ?AurisUser

getAccessToken(): ?string

refreshToken(): TokenResult

logout(returnTo?): void

AurisUser

Benutzerdefinierter TokenStore

AurisException