mirror of
https://github.com/btouchard/ackify.git
synced 2026-02-11 16:28:52 -06:00
68426bc882
- Implement PKCE (Proof Key for Code Exchange) with S256 method - Add crypto/pkce module with code verifier and challenge generation - Modify OAuth flow to include code_challenge in authorization requests - Update HandleCallback to validate code_verifier during token exchange - Extend session lifetime from 7 to 30 days - Add comprehensive unit tests for PKCE functions - Maintain backward compatibility with fallback for non-PKCE sessions - Add detailed logging for OAuth flow with PKCE tracking PKCE enhances security by preventing authorization code interception attacks, as recommended by OAuth 2.1 and OIDC standards. feat: add encrypted refresh token storage with automatic cleanup - Add oauth_sessions table for storing encrypted refresh tokens - Implement AES-256-GCM encryption for refresh tokens using cookie secret - Create OAuth session repository with full CRUD operations - Add SessionWorker for automatic cleanup of expired sessions - Configure cleanup to run every 24h for sessions older than 37 days - Modify OAuth flow to store refresh tokens after successful authentication - Track client IP and user agent for session security validation - Link OAuth sessions to user sessions via session ID - Add comprehensive encryption tests with security validations - Integrate SessionWorker into server lifecycle with graceful shutdown This enables persistent OAuth sessions with secure token storage, reducing the need for frequent re-authentication from 7 to 30 days.
209 lines
4.3 KiB
Markdown
209 lines
4.3 KiB
Markdown
# Getting Started
|
|
|
|
Installation and configuration guide for Ackify with Docker Compose.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose installed
|
|
- A domain (or localhost for testing)
|
|
- OAuth2 credentials (Google, GitHub, GitLab, or custom)
|
|
|
|
## Quick Installation
|
|
|
|
### 1. Clone the repository
|
|
|
|
```bash
|
|
git clone https://github.com/btouchard/ackify-ce.git
|
|
cd ackify-ce
|
|
```
|
|
|
|
### 2. Configuration
|
|
|
|
Copy the example file and edit it:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
nano .env
|
|
```
|
|
|
|
**Minimum required variables**:
|
|
|
|
```bash
|
|
# Public domain of your instance
|
|
APP_DNS=sign.your-domain.com
|
|
ACKIFY_BASE_URL=https://sign.your-domain.com
|
|
ACKIFY_ORGANISATION="Your Organization Name"
|
|
|
|
# PostgreSQL database
|
|
POSTGRES_USER=ackifyr
|
|
POSTGRES_PASSWORD=your_secure_password_here
|
|
POSTGRES_DB=ackify
|
|
|
|
# OAuth2 (example with Google)
|
|
ACKIFY_OAUTH_PROVIDER=google
|
|
ACKIFY_OAUTH_CLIENT_ID=your_google_client_id
|
|
ACKIFY_OAUTH_CLIENT_SECRET=your_google_client_secret
|
|
|
|
# Security - generate with: openssl rand -base64 32
|
|
ACKIFY_OAUTH_COOKIE_SECRET=your_base64_encoded_secret_key
|
|
```
|
|
|
|
### 3. Start
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
This command will:
|
|
- Download necessary Docker images
|
|
- Start PostgreSQL with healthcheck
|
|
- Apply database migrations
|
|
- Launch the Ackify application
|
|
|
|
### 4. Verification
|
|
|
|
```bash
|
|
# View logs
|
|
docker compose logs -f ackify-ce
|
|
|
|
# Check health endpoint
|
|
curl http://localhost:8080/api/v1/health
|
|
# Expected: {"status":"healthy","database":"connected"}
|
|
```
|
|
|
|
### 5. Access the interface
|
|
|
|
Open your browser:
|
|
- **Public interface**: http://localhost:8080
|
|
- **Admin dashboard**: http://localhost:8080/admin (requires email in ACKIFY_ADMIN_EMAILS)
|
|
|
|
## OAuth2 Configuration
|
|
|
|
Before using Ackify, configure your OAuth2 provider.
|
|
|
|
### Google OAuth2
|
|
|
|
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
|
2. Create a new project or select an existing one
|
|
3. Enable the "Google+ API"
|
|
4. Create OAuth 2.0 credentials:
|
|
- Type: Web application
|
|
- Authorized redirect URIs: `https://sign.your-domain.com/api/v1/auth/callback`
|
|
5. Copy the Client ID and Client Secret to `.env`
|
|
|
|
```bash
|
|
ACKIFY_OAUTH_PROVIDER=google
|
|
ACKIFY_OAUTH_CLIENT_ID=123456789-abc.apps.googleusercontent.com
|
|
ACKIFY_OAUTH_CLIENT_SECRET=GOCSPX-xyz...
|
|
```
|
|
|
|
### GitHub OAuth2
|
|
|
|
1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
|
|
2. Create a new OAuth App
|
|
3. Configuration:
|
|
- Homepage URL: `https://sign.your-domain.com`
|
|
- Callback URL: `https://sign.your-domain.com/api/v1/auth/callback`
|
|
4. Generate a client secret
|
|
|
|
```bash
|
|
ACKIFY_OAUTH_PROVIDER=github
|
|
ACKIFY_OAUTH_CLIENT_ID=Iv1.abc123
|
|
ACKIFY_OAUTH_CLIENT_SECRET=ghp_xyz...
|
|
```
|
|
|
|
See [OAuth Providers](configuration/oauth-providers.md) for GitLab and custom providers.
|
|
|
|
## Generating Secrets
|
|
|
|
```bash
|
|
# Cookie secret (required)
|
|
openssl rand -base64 32
|
|
|
|
# Ed25519 private key (optional, auto-generated if missing)
|
|
openssl rand -base64 64
|
|
```
|
|
|
|
## First Steps
|
|
|
|
### Create your first signature
|
|
|
|
1. Go to `http://localhost:8080/?doc=test_document`
|
|
2. Click "Sign this document"
|
|
3. Login via OAuth2
|
|
4. Validate the signature
|
|
|
|
### Access the admin dashboard
|
|
|
|
1. Add your email in `.env`:
|
|
```bash
|
|
ACKIFY_ADMIN_EMAILS=admin@company.com
|
|
```
|
|
2. Restart:
|
|
```bash
|
|
docker compose restart ackify-ce
|
|
```
|
|
3. Login and access `/admin`
|
|
|
|
### Embed in a page
|
|
|
|
```html
|
|
<!-- Embeddable widget -->
|
|
<iframe src="https://sign.your-domain.com/?doc=test_document"
|
|
width="600" height="200"
|
|
frameborder="0"
|
|
style="border: 1px solid #ddd; border-radius: 6px;"></iframe>
|
|
```
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
# View logs
|
|
docker compose logs -f ackify-ce
|
|
|
|
# Restart
|
|
docker compose restart ackify-ce
|
|
|
|
# Stop
|
|
docker compose down
|
|
|
|
# Rebuild after changes
|
|
docker compose up -d --force-recreate ackify-ce --build
|
|
|
|
# Access the database
|
|
docker compose exec ackify-db psql -U ackifyr -d ackify
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Application doesn't start
|
|
|
|
```bash
|
|
# Check logs
|
|
docker compose logs ackify-ce
|
|
|
|
# Check PostgreSQL health
|
|
docker compose ps ackify-db
|
|
```
|
|
|
|
### Migration error
|
|
|
|
```bash
|
|
# Manually re-run migrations
|
|
docker compose up ackify-migrate
|
|
```
|
|
|
|
### OAuth callback error
|
|
|
|
Verify that:
|
|
- `ACKIFY_BASE_URL` exactly matches your domain
|
|
- The callback URL in the OAuth2 provider is correct
|
|
- The cookie secret is properly configured
|
|
|
|
## Next Steps
|
|
|
|
- [Complete configuration](configuration.md)
|
|
- [Production deployment](deployment.md)
|
|
- [Features configuration](features/)
|
|
- [API Reference](api.md)
|