mirror/archivebox
1
0
Fork 0
mirror of https://github.com/pirate/ArchiveBox.git synced 2025-08-26 15:54:36 +02:00
Code Issues Releases Wiki Activity

Updated Setting up Authentication (markdown)

Nick Sweeting
2024-05-03 17:30:21 -07:00
parent 99a700e272
commit 15f8b50411
1 changed files with 87 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
Setting-up-Authentication.md

@@ -8,6 +8,15 @@ If you encounter any issues or need help feel free to ask questions in our publi
--- ---
## Admin Web UI Permissions
Make sure to set up your Web UI permissions to allow or prevent guest access to content according to your needs. See the links below for more information.
- https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#public_index--public_snapshots--public_add_view
- https://github.com/ArchiveBox/ArchiveBox/wiki/Security-Overview
## Admin Web UI Authentication
### Username & Password (the default) ### Username & Password (the default)
```bash ```bash
@@ -18,7 +27,9 @@ archivebox manage changepassword
- https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#admin_username--admin_password - https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#admin_username--admin_password
### Reverse Proxy Authentication (e.g. Authelia) ### Reverse Proxy Authentication
> Can be used with reverse proxy auth provider like [oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy), [Cloudflare Zero Trust](), [Authentik](https://docs.goauthentik.io/docs/providers/proxy/), and others.
- https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#reverse_proxy_user_header - https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#reverse_proxy_user_header
- https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#reverse_proxy_whitelist - https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#reverse_proxy_whitelist
@@ -27,30 +38,92 @@ archivebox manage changepassword
### LDAP Authentication ### LDAP Authentication
> Can be used with an SSO provider like [Authentik](https://github.com/goauthentik/authentik), [Authelia](https://github.com/authelia/authelia), [Okta / Auth0](https://www.okta.com/), [Keycloak](https://www.keycloak.org/), and others.
- https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#ldap - https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#ldap
- https://github.com/ArchiveBox/ArchiveBox/pull/1214 - https://github.com/ArchiveBox/ArchiveBox/pull/1214
- https://github.com/django-auth-ldap/django-auth-ldap#example-configuration - https://github.com/django-auth-ldap/django-auth-ldap#example-configuration
- https://jumpcloud.com/blog/what-is-ldap-authentication - https://jumpcloud.com/blog/what-is-ldap-authentication
### API Token Authentication ### Not Yet Supported: SAML / OAuth2 / OpenID Authentication
The new REST API released in v0.8.0 supports several methods of authentication using an API token. 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)](https://www.cloudflare.com/learning/access-management/what-is-an-identity-provider/) server (e.g. [Authentik](https://docs.goauthentik.io/docs/providers/saml/), [Authelia](https://www.authelia.com/configuration/identity-providers/introduction/#openid-connect-10), etc.).
First, generate your API key in your Admin UI: `[/admin/api/apitoken/add/`](http://127.0.0.1:8000/admin/api/apitoken/add/). 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).
You can read the API docs and test the authentication methods here: [`/api/v1/docs`](http://127.0.0.1:8000/api/v1/docs).
- passing Bearer=xyz as a bearer token request header - https://www.cloudflare.com/learning/access-management/what-is-saml/
- passing `X-API-Key=xyz` as a request header - https://docs.goauthentik.io/docs/providers/saml/
- passing `api_key=xyz` as a GET/POST query parameter - https://docs.goauthentik.io/docs/providers/oauth2/
- fallback: passing username & password via HTTP Basic Authentication (not recommended) - https://www.authelia.com/configuration/identity-providers/introduction/#openid-connect-10
<img width="738" alt="Screenshot 2024-05-03 at 4 40 22 PM" src="https://github.com/ArchiveBox/ArchiveBox/assets/511499/ad914143-f48b-4d4e-aa8c-f89a2c70cee7"> > *We'd welcome PRs to add support for more providers using `django-allauth`!*
--- ---
## Web Server UI Permissions <br/>
Make sure to set up your Web UI permissions to allow or prevent guest access to content according to your needs. See the links below for more information. ## REST API
- https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#public_index--public_snapshots--public_add_view The new REST API released in v0.8.0 supports several methods of authentication using an API token (or username & password).
- https://github.com/ArchiveBox/ArchiveBox/wiki/Security-Overview You can read the API docs and test the authentication methods here: [`/api/v1/docs`](http://127.0.0.1:8000/api/v1/docs).
<img width="738" alt="Screenshot 2024-05-03 at 4 40 22 PM" src="https://github.com/ArchiveBox/ArchiveBox/assets/511499/ad914143-f48b-4d4e-aa8c-f89a2c70cee7">
To get started using the REST API, generate an API key for your user through the Admin Web UI: `[/admin/api/apitoken/add/`](http://127.0.0.1:8000/admin/api/apitoken/add/) or by calling the `/api/v1/auth/get_api_token` endpoint:
```bash
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
- https://github.com/ArchiveBox/ArchiveBox/blob/dev/archivebox/api/auth.py#:~:text=API_AUTH_METHODS
- https://github.com/ArchiveBox/ArchiveBox/blob/dev/archivebox/api/v1_auth.py
- https://django-ninja.dev/guides/authentication/
- https://swagger.io/docs/specification/authentication/
### Bearer Token Authentication
Pass `Bearer=YOURAPITOKENHERE` as a bearer token request header.
```bash
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.
```bash
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.
```bash
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 user's username & password via HTTP Basic Authentication (not recommended).
```bash
curl -X 'GET' \
'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10' \
-u 'YOURUSERNAMEHERE:YOURPASSWORDHERE'
-H 'accept: application/json'
```