Authentication¶

Farm provides user authentication and management capabilities to control access to the platform.

Overview¶

The authentication system in Farm supports:

• User login with JWT access tokens
• Refresh token rotation for session continuity
• Social login via GitHub and Google (OAuth 2.0)
• LDAP / Active Directory login
• User management for administration

sequenceDiagram
    participant Client as HTTP Client
    participant API as Farm API
    participant DB as PostgreSQL
    participant Cache as Redis

    Client->>API: POST /api/v1/auth/login<br/>(username, password)
    API->>DB: Verify credentials
    DB-->>API: User found
    API->>API: Generate JWT + Refresh Token
    API->>DB: Store refresh token (bcrypt hash)
    API-->>Client: { accessToken, refreshToken, user }

    Note over Client,API: Subsequent requests
    Client->>API: GET /api/v1/resource<br/>(Authorization: Bearer token)
    API->>API: Validate JWT signature
    API-->>Client: 200 OK + data

    Note over Client,API: Token refresh
    Client->>API: POST /api/v1/auth/refresh<br/>(refreshToken)
    API->>DB: Validate refresh token hash
    DB-->>API: Valid
    API-->>Client: { accessToken, refreshToken }

User Properties¶

Each user in Farm has the following properties:

User Operations¶

Logging In via LDAP¶

If your organization uses an LDAP directory or Active Directory, log in with your directory credentials:

curl -X POST http://localhost:3000/api/v1/auth/login/ldap \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "your_ldap_password"
  }'

The response is identical to the standard login response. The endpoint returns 503 Service Unavailable when the server is not configured for LDAP.

Logging In¶

To authenticate and receive a JWT access token and refresh token:

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "SecurePass1"
  }'

Response:

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "displayName": "John Doe",
    "roles": ["user"],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "a1b2c3d4e5f6..."
}

Use the token value in the Authorization header for subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Refreshing a Token¶

When your access token expires, use the refresh token to obtain a new one without re-entering credentials:

curl -X POST http://localhost:3000/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "refreshToken": "a1b2c3d4e5f6..."
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "f6e5d4c3b2a1..."
}

The refresh token is rotated on each use. The old refresh token is immediately invalidated.

Listing Users¶

Retrieving all registered users requires a valid JWT with the admin role:

curl http://localhost:3000/api/v1/auth/users \
  -H "Authorization: Bearer <your-admin-token>"

Error Handling¶

Login Errors¶

Security Considerations¶

Password Requirements¶

Passwords are validated with the following rules:

• Minimum 8 characters long
• Must contain at least one lowercase letter
• Must contain at least one uppercase letter
• Must contain at least one digit

JWT Tokens¶

• Access tokens are short-lived (configurable via JWT_EXPIRATION, default 3600s)
• Store tokens securely on the client side
• Do not expose tokens in URLs or logs
• Include the token in the Authorization: Bearer <token> header

Refresh Tokens¶

• Refresh tokens are long-lived and stored as bcrypt hashes in the database
• Each use rotates the token (old token is invalidated)
• If a previously used refresh token is reused, all refresh tokens for the user are invalidated (replay attack protection)

Rate Limiting¶

Authentication endpoints are rate-limited to prevent brute force attacks:

• Login: 5 requests per minute
• Refresh: 10 requests per minute

Best Practices¶

• Use HTTPS in production environments
• Set a strong JWT_SECRET environment variable (minimum 32 characters, enforced in production)
• Configure ALLOWED_ORIGINS for CORS instead of using the wildcard default
• Regularly audit user accounts and access