Skip to content

Latest commit

 

History

History
204 lines (141 loc) · 8.1 KB

Setting-up-Authentication.md

File metadata and controls

204 lines (141 loc) · 8.1 KB
Raw

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

Warning

This page is a work in progress, follow the links to learn more about each authentication setup below.
To help make this page better, submit a pull request here: ArchiveBox/docs/Setting-Up-Authentication.md.

💬 If you encounter any issues or need help feel free to ask questions in our public forum: https://zulip.archivebox.io


Set Up Admin Web UI Permissions

Important

Make sure to set up your Web UI permissions first to allow/restrict public access according to your needs.
Configuring advanced auth methods below wont help you if your archive is set up to be visible to the public!


Admin Web UI Authentication Methods


Username & Password (the default)

Make sure you have an admin User created first, you can run the commands below to create/edit a user from the CLI:

archivebox manage createsuperuser
archivebox manage changepassword <username>

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

If using Docker or Docker Compose, you can alternatively configure ADMIN_USERNAME & ADMIN_PASSWORD to create an admin user automatically on first run.

Existing users can be managed from the Admin UI here: http://127.0.0.1:8000/admin/auth/user/,
and you can change your password in the UI here: http://127.0.0.1:8000/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 to 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)
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, pip-install the ldap add-on to use this feature (not needed if using Docker).

pip install archivebox[ldap]

Then set these configuration values to finish configuring LDAP:

LDAP=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 (e.g. Authentik, Authelia, etc.).

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 new REST API released 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://127.0.0.1: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://127.0.0.1:8000/admin/api/apitoken/add/

or by calling the http://127.0.0.1:8000/api/v1/auth/get_api_token endpoint:

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

Further Reading


Bearer Token Authentication

Pass Authorization=Bearer YOURAPITOKENHERE as a request header.

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

Request Header Authentication

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

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

Query Parameter Authentication

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

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

HTTP Basic Authentication

Pass your ArchiveBox admin username & password via HTTP Basic Authentication.

curl -X 'GET' \
  'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10' \
  -u 'YOURUSERNAMEHERE:YOURPASSWORDHERE'
  -H 'accept: application/json'

Session Cookie Authentication

Log in via the Admin Web UI: /admin/login/, you can then re-use your login session id (stored in the sessionid cookie) for REST API requests. This makes it convenient to test API requests from a browser environment where you're already logged in.

curl -X 'GET' \
  'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10' \
  -H 'accept: application/json' \
  -H 'Cookie: sessionid=YOURSESSIONIDVALUEHERE'