Skip to content

Setting-up-Authentication.md

Latest commit

 

History

History
195 lines (133 loc) · 8.86 KB

Setting-up-Authentication.md

File metadata and controls

195 lines (133 loc) · 8.86 KB
Raw

Setting Up Authentication

ArchiveBox supports several types of authentication for users logging in via the Admin Web UI or REST API.

Set Up Admin Web UI Permissions

Use these options to set up your desired permissions for non-admin guest users:

  • PUBLIC_INDEX=True: Default allows non-logged-in users to see Snapshot list
  • PUBLIC_ADD_VIEW=False: Default doesn't allow non-logged-in users to submit new URLs
  • PERMISSIONS=public: Default allows non-logged-in users to see Snapshot content (set to unlisted or private to gate it; replaces the removed legacy PUBLIC_SNAPSHOTS toggle, which was a global on/off — PERMISSIONS is now per-Snapshot)

Note

ArchiveBox does not currently support setting up non-admin users and groups with custom permissions.



Admin Web UI Authentication Methods


Username & Password (the default)

On a new server, open http://admin.archivebox.localhost:8000/admin/ to create the first admin through the setup UI. Existing users can be created or edited from the CLI:

archivebox manage createsuperuser
archivebox manage changepassword <username>

# equivalent: docker compose run --rm archivebox manage [...]
# equivalent: docker run -v $PWD:/data archivebox/archivebox:dev manage [...]

Existing users can be managed from the Admin UI here: /admin/auth/user/, and you can change your password here: /admin/password_change/.



Reverse Proxy Authentication

Can be used with a reverse proxy auth provider like oauth2-proxy, Cloudflare Zero Trust, Authentik, and others.

Set these ArchiveBox configuration values based on your reverse proxy setup and needs:

# REQUIRED: the header where your upstream reverse proxy will place the authenticated user's username/email
# EXAMPLE: Cf-Access-Authenticated-User-Email (if using Cloudflare Access / Zero Trust)
REVERSE_PROXY_USER_HEADER=X-Remote-User

# REQUIRED: the IP/CIDR of your upstream reverse proxy server
# WARNING: make sure this range contains ONLY your reverse proxy server!
# ArchiveBox will completely trust any IP in this range for authentication
REVERSE_PROXY_WHITELIST=192.0.2.3/32

# OPTIONAL: redirect users to an external URL after they log out
LOGOUT_REDIRECT_URL=https://auth.yourcompany.example.com/after/logout

LDAP Authentication

Can be used with an SSO provider like Authentik, Authelia, Okta / Auth0, Keycloak, and others.

First, install the ldap add-on to use this feature (not needed for Docker Archivebox).

uv tool install --python 3.13 --prerelease explicit --upgrade 'archivebox[ldap]>=0.9.0rc0,<0.10'

Then set these configuration values to finish configuring LDAP:

LDAP_ENABLED=True
LDAP_SERVER_URI="ldap://ldap.example.com:3389"
LDAP_BIND_DN="ou=archivebox,ou=services,dc=ldap.example.com"
LDAP_BIND_PASSWORD="secret-bind-user-password"
LDAP_USER_BASE="ou=users,ou=archivebox,ou=services,dc=ldap.example.com"
LDAP_USER_FILTER="(objectClass=user)"

LDAP_USERNAME_ATTR="uid"
LDAP_FIRSTNAME_ATTR="givenName"
LDAP_LASTNAME_ATTR="sn"
LDAP_EMAIL_ATTR="mail"

Not Yet Supported: SAML / OAuth2 / OpenID Authentication

We'd welcome PRs to add support for these using django-allauth!

These methods are not natively supported by ArchiveBox at the moment. However it is still possible to use them with ArchiveBox by running your own IdP (Identity Provider) server to act as a bridge (e.g. Authentik, Authelia, oauth2-proxy).

The IdP server can act as a middleman gateway to authenticate users using an external SAML/OAuth/OpenID/etc. provider (e.g. Google, Microsoft, Github, Facebook, etc.), and then pass on the authenticated user's session info to ArchiveBox using LDAP or reverse proxy headers (as described above).



REST API

The REST API (available starting in v0.8.0) supports several methods of authentication for convenience.

To see API docs, try endpoints interactively, and see how auth works, visit this URL on your ArchiveBox server:
http://api.archivebox.localhost:8000/api/v1/docs

Screenshot of django-ninja Swagger API docs page



To get started using the REST API, you can generate an API key for your user in the Admin Web UI: http://admin.archivebox.localhost:8000/admin/api/apitoken/add/

or by calling the http://api.archivebox.localhost:8000/api/v1/auth/get_api_token endpoint with a username & password:

curl -X 'POST' \
  'http://api.archivebox.localhost:8000/api/v1/auth/get_api_token' \
  -H 'Content-Type: application/json' \
  -d '{"username": "YOURUSERNAMEHERE", "password": "YOURPASSWORDHERE"}'

Tip

Bearer Tokens are the recommended method for the best balance of security and convenience.

API Bearer Token Authentication

Pass Authorization=Bearer YOURAPITOKENHERE as a request header.

curl -X 'GET' \
  'http://api.archivebox.localhost:8000/api/v1/core/snapshots?limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOURAPITOKENHERE'

API Request Header Authentication

This method is provided in case you have a reverse proxy in front of ArchiveBox that consumes the bearer header.

Pass X-ArchiveBox-API-Key=YOURAPITOKENHERE as a request header.

curl -X 'GET' \
  'http://api.archivebox.localhost:8000/api/v1/core/snapshots?limit=10' \
  -H 'accept: application/json' \
  -H 'X-ArchiveBox-API-Key: YOURAPITOKENHERE'

API Query Parameter Authentication

Warning

This method is sometimes known as "Capability URLs" because anyone in possession of the URL can perform API actions. It comes with important security caveats and is not recommended unless you fully understand the risks.

Pass api_key=YOURAPITOKENHERE as a GET/POST query parameter.

curl -X 'GET' \
  'http://api.archivebox.localhost:8000/api/v1/core/snapshots?limit=10&api_key=YOURAPITOKENHERE' \
  -H 'accept: application/json'

Further Reading