Override authentication page templates

If you want to fully customize authentication pages (login, registration, forgot password, etc.), you can override the built-in templates. Fief templates are powered by Jinja, a powerful templating system for Python.

Step 1: implement your templates

We recommend you to start from the built-in templates of Fief and copy them into a local folder. The files you override should have the same name as the original ones and nested in a folder named auth.

Here is a simple example of an override of layout.html, which is the base layout for all authentication pages, using the Bootstrap framework.

templates/auth/layout.html

{% extends "auth/base.html" %}

{% block style %}
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" crossorigin="anonymous"></script>
{% endblock %}

{% block body %}
<div class="px-4 py-5 my-5 text-center">
  {% if tenant.logo_url %}
    <img src="{{ tenant.logo_url }}" alt="{{ tenant.name }}" class="d-block mx-auto mb-4" />
  {% endif %}
  <h1 class="display-5 fw-bold text-body-emphasis">{{ tenant.name }}</h1>
  <div class="col-lg-6 mx-auto">
    {% if error is defined %}
      <p class="text-danger">{{error}}</p>
    {% endif %}
    {% if success is defined %}
    <p class="text-success">{{success}}</p>
    {% endif %}
    {% if not fatal_error %}
      {% block auth_form %}
      {% endblock %}
    {% endif %}
  </div>
</div>
{% endblock %}

Step 2: adding your templates to your Docker build

You should now add your templates to your Docker image. For this, create a Dockerfile (if not already) in your project. In its simplest form, it can look like this:

Dockerfile

FROM ghcr.io/fief-dev/fief:latest

COPY templates /app/templates
ENV OVERRIDE_TEMPLATES_DIRECTORY=/app/templates

Basically, we start from the base image, copy our templates and set the OVERRIDE_TEMPLATES_DIRECTORY environment variable.

You don't need to override every files

If you just want to override some files but not the others, you can just provide the one you're interested in. If some templates don't exist, Fief will simply fall back to the default ones.

Step 3: build and run your image

Now, all you need is to build and run your image to see the result.

docker build -t fief-templates .