---
title: "Introduction"
description: "Authentication and Authorization"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-09-09"
last_update: "2026-09-09"
time_minutes: 2
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/core/auth/introduction"
---

# Derafu: Auth

PSR-15 compliant authentication and authorization library for PHP applications with Keycloak integration.

## Features

- **PSR-15 Middleware**: Standard-compliant middleware.
- **Keycloak Integration**: OAuth2/OpenID Connect.
- **Session Management**: Secure session handling.
- **Token Refresh**: Automatic token refresh.
- **Route Protection**: Flexible route-based auth.
- **CSRF Protection**: State parameter validation.

## Quick Start

### Installation

Install the package:

```bash
composer require derafu/auth
```

### Environment Variables

Configure, at the very least, the following environment variables:

```env
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_REDIRECT_URI=http://localhost/auth/callback
```

### Routes

Import the routes to your `routes.yaml`:

```yaml
imports:
    - { resource: '../vendor/derafu/auth/resources/config/auth-routes.yaml' }
```

### Services

Import the services to your `services.yaml`:

```yaml
imports:
    - { resource: '../vendor/derafu/auth/resources/config/auth-services.yaml' }
```

### Middleware

Add the middleware to your `services.yaml`:

```yaml
Psr\Http\Server\RequestHandlerInterface:
    class: Derafu\Http\Service\RequestHandler
    public: true
    arguments:
        $middlewares:
            - '@Derafu\Auth\Middleware\AuthenticationMiddleware'
```

**Note**: the `AuthenticationMiddleware` needs to be placed before the `DispatcherMiddleware`.

### Access User Information

Directly with the attribute `user` or `access_token`:

```php
$user = $request->getAttribute('user');
$accessToken = $request->getAttribute('access_token');
```

Using the `UserInterface` from the `mezzio/mezzio-authentication` package:

```php
$user = $request->getAttribute(UserInterface::class);
if ($user) {
    $identity = $user->getIdentity();
    $roles = iterator_to_array($user->getRoles());
    $email = $user->getDetail('email');
}
```



---
Last updated on 09/09/2026