118 lines
4.7 KiB
Markdown
118 lines
4.7 KiB
Markdown
# Authelia API
|
|
|
|
A Go-based REST API and management layer that sits alongside an Authelia instance. Provides a "Source of Truth" in SQLite, handles bulk user onboarding via JSON, manages access control policies dynamically, and automates synchronization of the Authelia `users_database.yml` file.
|
|
|
|
## Features
|
|
|
|
- **Sovereign Bootstrap**: Automatically imports existing Authelia users on first run
|
|
- **Bulk User Management**: Create multiple users via JSON API with automatic password generation
|
|
- **Policy Management**: Full CRUD for access control policies with dry-run verification
|
|
- **Real-time Sync**: SQLite changes automatically sync to Authelia's YAML configuration
|
|
- **SMTP Onboarding**: Send welcome emails using Authelia's SMTP configuration
|
|
- **Secure API**: Bearer token authentication with bcrypt hashing
|
|
- **Drop-in Deployment**: Runs alongside existing Authelia installation
|
|
- **OpenAPI 3.0 Spec**: Complete API specification at [`openapi.yml`](openapi.yml)
|
|
|
|
## Installation
|
|
|
|
### Docker Deployment (Recommended)
|
|
|
|
A combined container with **both Authelia and Authelia-API** is available on Docker Hub as [`git24hcom/authelia-api`](https://hub.docker.com/r/git24hcom/authelia-api):
|
|
|
|
```bash
|
|
# Create config directory with your Authelia configuration
|
|
mkdir -p config data certs
|
|
# Copy and edit the example config:
|
|
# docker/configuration.yml.example → config/configuration.yml
|
|
# Set secrets, domains, and other settings.
|
|
|
|
# Pull and start
|
|
docker compose up -d
|
|
```
|
|
|
|
| Port | Service |
|
|
|------|---------|
|
|
| `9091` | Authelia web portal |
|
|
| `8080` | Authelia-API (user management API) |
|
|
|
|
**First-time authentication**: The container creates an admin user automatically on startup by reading the `session.secret` from your Authelia config. Whatever value you set for `session.secret` in `configuration.yml` becomes your initial bearer token — there is nothing to fetch. For example:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer your-session-secret-value" http://localhost:8080/api/health
|
|
```
|
|
|
|
**Authelia configuration reference**: The example file at `docker/configuration.yml.example` covers the essentials, but Authelia has many more options. See the [official Authelia configuration docs](https://www.authelia.com/configuration/) for details on secrets, domains, authentication backends, and access control rules.
|
|
|
|
### Bare Metal (Quick Installation)
|
|
|
|
Runs the install script directly on the host alongside an existing Authelia installation:
|
|
|
|
```bash
|
|
curl -fsSL https://git.lohmar.co.uk/cclohmar/authelia-api/raw/branch/main/install-authelia-api.sh | sudo bash
|
|
```
|
|
|
|
### Manual Installation
|
|
|
|
1. **Clone the repository**:
|
|
```bash
|
|
git clone https://git.lohmar.co.uk/cclohmar/authelia-api.git
|
|
cd authelia-api
|
|
```
|
|
|
|
2. **Run the installer**:
|
|
```bash
|
|
sudo ./install-authelia-api.sh
|
|
```
|
|
|
|
### Development Installation
|
|
|
|
For building from source, see the [src/README.md](src/README.md) file.
|
|
|
|
**Note for local development**: When installing from a cloned repository, set the environment variable to use the local binary:
|
|
|
|
```bash
|
|
AUTHELIA_API_DEVELOPMENT_MODE=true sudo ./install-authelia-api.sh
|
|
```
|
|
|
|
**Get your bearer token:**
|
|
|
|
- **Docker:** The token is whatever you set as `session.secret` in your `configuration.yml`.
|
|
- **Bare metal:** Read it from your existing Authelia configuration:
|
|
```bash
|
|
grep -A2 "session:" /opt/authelia/configuration.yml | grep "secret:" | awk '{print $2}'
|
|
```
|
|
|
|
Then test the API:
|
|
```bash
|
|
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/health
|
|
```
|
|
|
|
## API Testing with Postman
|
|
|
|
Postman collection and environment files are provided for API testing:
|
|
|
|
- `authelia-api.postman_collection.json` - Complete API collection with all endpoints
|
|
- `authelia-api.postman_environment.json` - Environment variables (base URL, token)
|
|
- `POSTMAN_GUIDE.md` - Setup and usage guide
|
|
|
|
See [POSTMAN_GUIDE.md](POSTMAN_GUIDE.md) for detailed setup and usage instructions.
|
|
|
|
## Files in This Repository
|
|
|
|
- `Dockerfile` - 3-stage build: Authelia download → Go build → runtime image
|
|
- `docker-compose.yml` - Quick Docker deployment with volumes
|
|
- `docker/` - Container entrypoint and configuration templates
|
|
- `src/` - Go source code (cmd/server, internal packages, migrations)
|
|
- `openapi.yml` - OpenAPI 3.0.3 specification for all endpoints
|
|
- `install-authelia-api.sh` - Bare-metal installation script
|
|
- `POSTMAN_GUIDE.md` - API testing guide with examples
|
|
- `authelia-api.postman_collection.json` - Postman collection (12 endpoints)
|
|
- `authelia-api.postman_environment.json` - Postman environment
|
|
|
|
## Mirror
|
|
|
|
This project is developed on [git.lohmar.co.uk](https://git.lohmar.co.uk/cclohmar/authelia-api) and mirrored to [Codeberg](https://codeberg.org/cclohmar/authelia-api).
|
|
|
|
## License
|
|
|
|
MIT License
|