DOCSEARCHbyAlgolia
Submit Docs

fief

repository·main·Indexed 20 days ago

https://github.com/fief-dev/fief

A Users and Authentication Management SaaS designed to handle user identities and access control. Built with FastAPI, it includes an Administration API for managing tenants, users, roles, and webhooks, as well as an Administration Dashboard for resource management. The system utilizes PostgreSQL and Redis for its infrastructure.

Tokens
12.2K
Snippets
46
Records
65
Agent score
71%

What's inside fief

  1. Important notice regarding Fief development status

    main

    ⚠️ Maintenance Status

    Fief is currently wrapping up its current chapter to transition to a new vision.

    Note for developers:

    • No new features will be added to the current codebase.
    • No new bugs will be fixed in the current codebase.
    • Please check the official website for updates on the future vision of the project.

  2. Use GitHub Codespaces for Fief development

    main

    For a pre-configured development environment including PostgreSQL and Redis, you can use GitHub Codespaces. When a Codespace is built, an admin user is automatically created with the following credentials:

    • Email: anne@bretagne.duchy
    • Password: herminetincture

  3. Run Fief in development mode

    main

    To run the Fief server in development mode, use the hatch command. You can also start the worker process separately using the provided hatch commands.

    # Start the Fief server
hatch run dev.server.start

# Start the worker
hatch run dev.worker.start

  5. Use the Fief CLI to manage your instance

    main

    The Fief CLI is the primary interface for managing a Fief instance. It is organized into command groups, including quickstart and admin commands. If your configuration settings are invalid or missing, the CLI will catch ValidationError exceptions and display a descriptive error message indicating which settings are problematic.

    # General usage pattern
fief [COMMAND] [ARGS]

  6. The Fief Administration API structure

    main

    The Fief Administration API is a FastAPI-based application that provides endpoints for managing core Fief resources. The API is served under the /admin/api base path. It includes specialized routers for managing tenants, users, roles, permissions, and other administrative entities.

    Key API resource groups include:

    • /clients: Client management
    • /email-templates: Email template configuration
    • /oauth-providers: OAuth provider settings
    • /permissions: Permission management
    • /roles: Role management
    • /tenants: Tenant management
    • /users: User management
    • /user-fields: Custom user field definitions
    • /webhooks: Webhook configurations

  7. Configure UserField settings

    main

    User fields are configured via specialized forms that define how the field behaves during user registration and profile updates.

    All configuration forms inherit from UserFieldConfigurationBase, which includes these common settings:

    • at_registration: Boolean. Whether to ask for this field during the registration process.
    • at_update: Boolean. Whether to ask for this field during a profile update.
    • required: Boolean. Whether the field is mandatory.

    Specific types include additional settings:

    • String/Integer/Boolean: Includes a default value field.
    • Choice: Includes a choices list where each item has a value and a label.
    • Timezone: Includes a default value using a TimezoneField.

  8. Redirect URI validation rules

    main
    Redirect URIs are validated using the RedirectURI type. If settings.client_redirect_uri_ssl_required is enabled, any URI using the http scheme will trigger a validation error (APIErrorCode.CLIENT_HTTPS_REQUIRED_ON_REDIRECT_URIS) unless the host is localhost.

  9. Initialize the Fief Authentication API

    main

    The Fief Authentication service is built using FastAPI. The app object is the primary entrypoint and includes several pre-configured routers and middlewares for security, localization, and authentication flows.

    Key features included in the app instance:

    • Security Middlewares: SecurityHeadersMiddleware, CSRFCookieSetterMiddleware, and CORSMiddlewarePath (configured for /api and /.well-known paths).
    • Localization: BabelMiddleware is integrated for multi-language support.
    • Routing Structure:
      • /api: Contains token and user routers.
      • /.well-known: Contains the well_known router.
      • /{tenant_slug}: A tenant-specific router prefix that includes auth, register, reset, token, user, and dashboard logic.
      • /static: Mounts static files from the configured STATIC_DIRECTORY.
    • Exception Handling: Custom handlers are registered via exception_handlers.
    from fief.apps.auth.app import app

# The 'app' object is a FastAPI instance ready to be served
# e.g., using uvicorn: uvicorn fief.apps.auth.app:app

  10. Manage tenants via the dashboard API

    main

    The Fief dashboard provides several endpoints for managing tenants. These endpoints are protected by is_authenticated_admin_session and allow for listing, retrieving, creating, updating, and deleting tenants. Most operations trigger webhooks (e.g., TenantCreated, TenantUpdated, TenantDeleted) and log actions via the AuditLogger.

    Available Endpoints

    MethodPathNameDescription
    GET/dashboard.tenants:listLists tenants with pagination and datatable support.
    GET/{id:uuid}dashboard.tenants:getRetrieves general information for a specific tenant.
    GET/POST/{id:uuid}/emaildashboard.tenants:emailManages tenant email settings and domain authentication.
    GET/{id:uuid}/email/domaindashboard.tenants:email_domain_authenticationAccesses email domain authentication interface.
    POST/{id:uuid}/email/verifydashboard.tenants:email_domain_verifyVerifies the tenant's email domain.
    GET/POST/createdashboard.tenants:createCreates a new tenant and an associated first-party client.
    GET/POST/{id:uuid}/editdashboard.tenants:updateUpdates tenant configuration (e.g., name, theme, OAuth providers).
    GET/DELETE/{id:uuid}/deletedashboard.tenants:deleteDeletes a tenant and its associated data.

  11. Configure the Fief infrastructure with Docker Compose

    main

    The docker-compose.yml file defines the standard infrastructure required for Fief, consisting of a PostgreSQL database and a Redis instance.

    Database Service (db)

    • Image: postgres:14-alpine
    • Default Credentials:
      • POSTGRES_USER: fief
      • POSTGRES_DB: fief
      • POSTGRES_PASSWORD: fiefpassword
    • Port: 5432
    • Persistence: Uses a named volume postgres-data mapped to /var/lib/postgresql/data/ to ensure data persists across container restarts.

    Redis Service (redis)

    • Image: redis:alpine
    • Port: 6379
    services:
  db:
    image: postgres:14-alpine
    environment:
      POSTGRES_USER: fief
      POSTGRES_DB: fief
      POSTGRES_PASSWORD: fiefpassword
    volumes:
      - postgres-data:/var/lib/postgresql/data/
    ports:
      - "5432:5432"
  redis:
    image: redis:alpine
    ports:
      - "6379:6379"

volumes:
  postgres-data:

  12. Preview a theme on a specific page

    main

    When editing a theme via the dashboard.themes:update endpoint, you can preview how the theme will look on a specific page by providing the preview query parameter.

    If preview is provided, the endpoint returns the edit form with preview_content injected into the context, allowing you to see the rendered page alongside the form. If preview is not provided, the theme is updated normally and the user is redirected to the theme list.

    Example URL structure: GET /admin/themes/{theme_id}/edit?preview=login