diff --git a/Setting-up-Authentication.md b/Setting-up-Authentication.md index 454a7aa..ccc6bc9 100644 --- a/Setting-up-Authentication.md +++ b/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) ```bash @@ -18,7 +27,9 @@ archivebox manage changepassword - 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_whitelist @@ -27,30 +38,92 @@ archivebox manage changepassword ### 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/pull/1214 - https://github.com/django-auth-ldap/django-auth-ldap#example-configuration - 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/). -You can read the API docs and test the authentication methods here: [`/api/v1/docs`](http://127.0.0.1:8000/api/v1/docs). +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). -- passing Bearer=xyz as a bearer token request header -- passing `X-API-Key=xyz` as a request header -- passing `api_key=xyz` as a GET/POST query parameter -- fallback: passing username & password via HTTP Basic Authentication (not recommended) +- https://www.cloudflare.com/learning/access-management/what-is-saml/ +- https://docs.goauthentik.io/docs/providers/saml/ +- https://docs.goauthentik.io/docs/providers/oauth2/ +- https://www.authelia.com/configuration/identity-providers/introduction/#openid-connect-10 -Screenshot 2024-05-03 at 4 40 22 PM +> *We'd welcome PRs to add support for more providers using `django-allauth`!* --- -## Web Server 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. +## REST API -- https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#public_index--public_snapshots--public_add_view -- https://github.com/ArchiveBox/ArchiveBox/wiki/Security-Overview \ No newline at end of file +The new REST API released in v0.8.0 supports several methods of authentication using an API token (or username & password). +You can read the API docs and test the authentication methods here: [`/api/v1/docs`](http://127.0.0.1:8000/api/v1/docs). + +Screenshot 2024-05-03 at 4 40 22 PM + +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' +``` \ No newline at end of file