Skip to Content
v2DeveloperAuthentication

Last Updated: 3/11/2026

Authentication & Authorization

LinkAce provides multiple authentication methods and a flexible authorization system for controlling access to resources.

Authentication Methods

1. Standard Email/Password Authentication

LinkAce uses Laravel Fortify for email/password authentication with the following features:

  • Login - Standard email and password login
  • Password Reset - Email-based password recovery
  • Profile Updates - Users can update their name and email
  • Password Changes - Users can change their password
  • Two-Factor Authentication (2FA) - Optional TOTP-based 2FA

Configuration:

Fortify features are configured in config/fortify.php:

'features' => [
    Features::resetPasswords(),
    Features::updateProfileInformation(),
    Features::updatePasswords(),
    Features::twoFactorAuthentication([
        'confirmPassword' => true,
    ]),
],

Note: User registration is disabled by default. New users must be invited by administrators.

2. Single Sign-On (SSO)

LinkAce supports SSO via OAuth 2.0 and OpenID Connect (OIDC) providers.

Supported Providers:

  • Auth0
  • Authentik
  • Azure AD (Microsoft)
  • AWS Cognito
  • FusionAuth
  • Google
  • GitHub
  • GitLab
  • Keycloak
  • Generic OIDC
  • Okta
  • Zitadel

Environment Configuration:

# Enable SSO
SSO_ENABLED=true
 
# Allow new users to register via SSO
SSO_REGISTRATION_ENABLED=true
 
# Disable regular email/password login (SSO only)
REGULAR_LOGIN_DISABLED=false
 
# Provider-specific settings (example for Google)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://your-linkace-instance.com/auth/google/callback

SSO Configuration:

SSO settings are defined in config/auth.php:

'sso' => [
    'enabled' => env('SSO_ENABLED', false),
    'registration_enabled' => env('SSO_REGISTRATION_ENABLED', true),
    'regular_login_disabled' => env('REGULAR_LOGIN_DISABLED', false),
    'providers' => [
        'auth0', 'authentik', 'azure', 'cognito',
        'fusionauth', 'google', 'github', 'gitlab',
        'keycloak', 'oidc', 'okta', 'zitadel',
    ],
],

Implementation:

SSO is implemented using Laravel Socialite with provider-specific packages from SocialiteProviders.

3. API Token Authentication

API access uses Laravel Sanctum for token-based authentication.

Token Types:

  1. User API Tokens - Generated by individual users for personal use
  2. System API Tokens - Generated by administrators for system-wide access

Token Generation:

Users can generate tokens from:

  • User Settings → API Tokens (for personal tokens)
  • System Settings → API Tokens (for system tokens, admin only)

Token Usage:

Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Token Abilities:

Sanctum supports token abilities (permissions), though LinkAce currently uses full-access tokens.

Configuration:

Sanctum settings are in config/sanctum.php:

'middleware' => [
    'auth:sanctum',
    'throttle:' . config('app.api_rate_limit'),
],

Authorization

User Roles & Permissions

LinkAce uses the spatie/laravel-permission package for role-based access control (RBAC).

Default Roles:

  1. Admin - Full system access

    • Manage users
    • Configure system settings
    • Generate system API tokens
    • Access all content

  2. User - Standard user access

    • Manage own content (links, lists, tags, notes)
    • Generate personal API tokens
    • Access shared content based on visibility

Permission System:

Permissions are enforced through:

  • Laravel policies (model-level authorization)
  • Middleware (route-level authorization)
  • Blade directives (view-level authorization)

Visibility-Based Access Control

All content (links, lists, tags, notes) uses a three-tier visibility system:

Visibility Levels

  1. Private (1)

    • Only visible to the owner
    • Hidden from other users, even admins
    • Not accessible via public pages or RSS feeds

  2. Internal (2)

    • Visible to all authenticated users
    • Hidden from guests
    • Useful for team sharing

  3. Public (3)

    • Visible to everyone, including unauthenticated guests
    • Accessible via public pages and RSS feeds
    • Indexed by search engines (if allowed)

Implementation

Visibility is enforced through:

Query Scopes:

// Get only public links
$links = Link::publicOnly()->get();
 
// Get links visible to current user
$links = Link::byUser(auth()->id())->get();

Policies:

// Check if user can view a link
if (auth()->user()->can('view', $link)) {
    // Show link
}

Middleware:

Route::get('/links/{link}', [LinkController::class, 'show'])
    ->middleware('can:view,link');

User Scoping

All content is scoped to users through the ScopesForUser trait:

// Get links for a specific user
$links = Link::byUser($userId)->get();
 
// Get links for the current authenticated user
$links = Link::byUser()->get();

This ensures users only see their own content plus content shared with them based on visibility.

Policies

LinkAce uses Laravel policies for model-level authorization. Policies are located in app/Policies/.

Common Policy Methods:

  • viewAny() - Can the user view a list of resources?
  • view() - Can the user view this specific resource?
  • create() - Can the user create a new resource?
  • update() - Can the user update this resource?
  • delete() - Can the user delete this resource?
  • restore() - Can the user restore this soft-deleted resource?
  • forceDelete() - Can the user permanently delete this resource?

Example Policy Check:

// In a controller
if ($request->user()->cannot('update', $link)) {
    abort(403);
}
 
// Using middleware
Route::patch('/links/{link}', [LinkController::class, 'update'])
    ->middleware('can:update,link');
 
// In Blade
@can('update', $link)
    <a href="{{ route('links.edit', $link) }}">Edit</a>
@endcan

User Management

User Invitations

Since registration is disabled by default, new users are added via invitations:

  1. Admin generates an invitation link
  2. Invitation is sent to the user’s email
  3. User clicks the link and sets their password
  4. Account is created and activated

Invitation Model:

UserInvitation {
    email: string,
    token: string (unique),
    created_by: int (admin user ID),
    used_at: datetime|null,
}

User States

  • Active - Normal user account
  • Soft Deleted - User account disabled but data retained
  • Email Verified - Email verification status (optional)

Multi-User Support

LinkAce supports multiple users on a single instance:

  • Each user has their own content
  • Content can be shared via visibility settings
  • Admins can manage all users
  • Users can be invited or removed

Session Management

Session Configuration:

Sessions are configured in config/session.php:

  • Driver: file, cookie, database, redis, etc.
  • Lifetime: Configurable (default: 120 minutes)
  • Secure: HTTPS-only cookies in production
  • HttpOnly: Prevents JavaScript access to session cookies
  • SameSite: CSRF protection

Session Security:

  • CSRF protection on all state-changing requests
  • Session regeneration on login
  • Session invalidation on logout
  • Remember me functionality (optional)

Rate Limiting

Login Rate Limiting

Fortify throttles login attempts to prevent brute-force attacks:

  • Default: 5 attempts per minute per email/IP combination
  • Configurable in config/fortify.php

API Rate Limiting

API requests are rate-limited:

  • Default: Configured via APP_API_RATE_LIMIT environment variable
  • Format: {requests}:{minutes} (e.g., 60:1 = 60 requests per minute)
  • Applied to all API routes via middleware

Configuration:

APP_API_RATE_LIMIT=60:1

Security Best Practices

Password Requirements

  • Minimum length: 8 characters (configurable)
  • No complexity requirements by default
  • Passwords are hashed using bcrypt
  • Password reset tokens expire after 60 minutes

Two-Factor Authentication (2FA)

  • TOTP-based (Time-based One-Time Password)
  • Compatible with Google Authenticator, Authy, etc.
  • Recovery codes provided during setup
  • Password confirmation required to enable/disable

API Security

  • All API routes require authentication
  • Rate limiting prevents abuse
  • Tokens can be revoked at any time
  • HTTPS recommended for production

CSRF Protection

  • Enabled for all web routes
  • CSRF token included in forms
  • SameSite cookie attribute prevents CSRF attacks

CORS

CORS is configured in config/cors.php for API access from external domains.

Environment Variables

Authentication-Related Variables:

# SSO Settings
SSO_ENABLED=false
SSO_REGISTRATION_ENABLED=true
REGULAR_LOGIN_DISABLED=false
 
# OAuth Provider Settings (example)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=
 
# API Rate Limiting
APP_API_RATE_LIMIT=60:1
 
# Session Settings
SESSION_DRIVER=file
SESSION_LIFETIME=120
  • SSO (Single-Sign-On) with OAuth or OIDC - Detailed SSO setup guide
  • User API Tokens - Managing user API tokens
  • System API Tokens - Managing system API tokens
  • User Management - Managing users and invitations
  • API Reference - API authentication examples
From V1Api Reference