chris/frigate
1
0
Fork 0
forked from Github/frigate
Code Pull Requests Packages Activity

Auth! (#11347)

Browse Source 
* reload the window on 401

* backend apis for auth

* add login page

* re-enable web linter

* fix login page routing

* bypass csrf for internal auth endpoint

* disable healthcheck in devcontainer target

* include login page in vite build

* redirect to login page on 401

* implement config for users and settings

* implement JWT actual secret

* add brute force protection on login

* add support for redirecting from auth failures on api calls

* return location for redirect

* default cookie name should pass regex test

* set hash iterations to current OWASP recommendation

* move users to database instead of config

* config option to reset admin password on startup

* user management UI

* check for deleted user on refresh

* validate username and fixes

* remove password constraint

* cleanup

* fix user check on refresh

* web fixes

* implement auth via new external port

* use x-forwarded-for to rate limit login attempts by ip

* implement logout and profile

* fixes

* lint fixes

* add support for user passthru from upstream proxies

* add support for specifying a logout url

* add documentation

* Update docs/docs/configuration/authentication.md

Co-authored-by: Nicolas Mowen <nickmowen213@gmail.com>

* Update docs/docs/configuration/authentication.md

Co-authored-by: Nicolas Mowen <nickmowen213@gmail.com>

---------

Co-authored-by: Nicolas Mowen <nickmowen213@gmail.com>
This commit is contained in:
Blake Blackshear
2024-05-18 11:36:13 -05:00
committed by GitHub
parent a70dd02788
commit 1133202cbd
48 changed files with 2541 additions and 833 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
docs/docs/configuration/authentication.md Normal file
View File

@@ -0,0 +1,98 @@
---
id: authentication
title: Authentication
---
# Authentication
## Modes
Frigate supports two modes for authentication
| Mode | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `native` | (default) Use this mode if you don't implement authentication with a proxy in front of Frigate. |
| `proxy` | Use this mode if you have an existing proxy for authentication. Supports passing authenticated user downstream to Frigate for role-based authorization (future implementation). |
### Native mode
Frigate stores user information in its database. Password hashes are generated using industry standard PBKDF2-SHA256 with 600,000 iterations. Upon successful login, a JWT token is issued with an expiration date and set as a cookie. The cookie is refreshed as needed automatically. This JWT token can also be passed in the Authorization header as a bearer token.
Users are managed in the UI under Settings > Authentication.
#### Onboarding
On startup, an admin user and password are generated and printed in the logs. It is recommended to set a new password for the admin account after logging in for the first time under Settings > Authentication.
#### Resetting admin password
In the event that you are locked out of your instance, you can tell Frigate to reset the admin password and print it in the logs on next startup using the `reset_admin_password` setting in your config file.
#### Login failure rate limiting
In order to limit the risk of brute force attacks, rate limiting is available for login failures. This is implemented with Flask-Limiter, and the string notation for valid values is available in [the documentation](https://flask-limiter.readthedocs.io/en/stable/configuration.html#rate-limit-string-notation).
For example, `1/second;5/minute;20/hour` will rate limit the login endpoint when failures occur more than:
- 1 time per second
- 5 times per minute
- 20 times per hour
Restarting Frigate will reset the rate limits.
If you are running Frigate behind a proxy, you will want to set `trusted_proxies` or these rate limits will apply to the upstream proxy IP address. This means that a brute force attack will rate limit login attempts from other devices and could temporarily lock you out of your instance. In order to ensure rate limits only apply to the actual IP address where the requests are coming from, you will need to list the upstream networks that you want to trust. These trusted proxies are checked against the `X-Forwarded-For` header when looking for the IP address where the request originated.
If you are running a reverse proxy in the same docker compose file as Frigate, here is an example of how your auth config might look:
```yaml
auth:
mode: native
failed_login_rate_limit: "1/second;5/minute;20/hour"
trusted_proxies:
- 172.18.0.0/16 # <---- this is the subnet for the internal docker compose network
```
### Proxy mode
Proxy mode is designed to complement common upstream authentication proxies such as Authelia, Authentik, oauth2_proxy, or traefik-forward-auth.
#### Header mapping
If your proxy supports passing a header with the authenticated username, you can use the `header_map` config to specify the header name so it is passed to Frigate. For example, the following will map the `X-Forwarded-User` value. Header names are not case sensitive.
```yaml
auth:
...
header_map:
user: x-forwarded-user
```
Note that only the following list of headers are permitted by default:
```
Remote-User
Remote-Groups
Remote-Email
Remote-Name
X-Forwarded-User
X-Forwarded-Groups
X-Forwarded-Email
X-Forwarded-Preferred-Username
X-authentik-username
X-authentik-groups
X-authentik-email
X-authentik-name
X-authentik-uid
```
If you would like to add more options, you can overwrite the default file with a docker bind mount at `/usr/local/nginx/conf/proxy_trusted_headers.conf`. Reference the source code for the default file formatting.
Future versions of Frigate may leverage group and role headers for authorization in Frigate as well.
#### Login page redirection
Frigate gracefully performs login page redirection that should work with most authentication proxies. If your reverse proxy returns a `Location` header on `401`, `302`, or `307` unauthorized responses, Frigate's frontend will automatically detect it and redirect to that URL.
#### Custom logout url
If your reverse proxy has a dedicated logout url, you can specify using the `logout_url` config option. This will update the link for the `Logout` link in the UI.

2
docs/docs/configuration/index.md
View File

@@ -25,7 +25,7 @@ cameras:
## VSCode Configuration Schema
VSCode supports JSON schemas for automatically validating configuration files. You can enable this feature by adding `# yaml-language-server: $schema=http://frigate_host:5000/api/config/schema.json` to the beginning of the configuration file. Replace `frigate_host` with the IP address or hostname of your Frigate server. If you're using both VSCode and Frigate as an add-on, you should use `ccab4aaf-frigate` instead. Make sure to expose port `5000` for the Web Interface when accessing the config from VSCode on another machine.
VSCode supports JSON schemas for automatically validating configuration files. You can enable this feature by adding `# yaml-language-server: $schema=http://frigate_host:5000/api/config/schema.json` to the beginning of the configuration file. Replace `frigate_host` with the IP address or hostname of your Frigate server. If you're using both VSCode and Frigate as an add-on, you should use `ccab4aaf-frigate` instead. Make sure to expose the internal unauthenticated port `5000` when accessing the config from VSCode on another machine.
## Environment Variable Substitution

39
docs/docs/configuration/reference.md
View File

@@ -63,6 +63,45 @@ database:
# The path to store the SQLite DB (default: shown below)
path: /config/frigate.db
# Optional: Authentication configuration
auth:
# Optional: Authentication mode (default: shown below)
# Valid values are: native, proxy
mode: native
# Optional: Reset the admin user password on startup (default: shown below)
# New password is printed in the logs
reset_admin_password: False
# Optional: Cookie to store the JWT token for native auth (default: shown below)
cookie_name: frigate_token
# Optional: Session length in seconds (default: shown below)
session_length: 86400 # 24 hours
# Optional: Refresh time in seconds (default: shown below)
# When the session is going to expire in less time than this setting,
# it will be refreshed back to the session_length.
refresh_time: 43200 # 12 hours
# Optional: Mapping for headers from upstream proxies. Only used in proxy auth mode.
# NOTE: Many authentication proxies pass a header downstream with the authenticated
# user name. Not all values are supported. It must be a whitelisted header.
# See the docs for more info.
header_map:
user: x-forwarded-user
# Optional: Rate limiting for login failures to help prevent brute force
# login attacks (default: shown below)
# See the docs for more information on valid values
failed_login_rate_limit: None
# Optional: Trusted proxies for determining IP address to rate limit
# NOTE: This is only used for rate limiting login attempts and does not bypass
# authentication in any way
trusted_proxies: []
# Optional: Url for logging out a user. This only needs to be set if you are using
# proxy mode.
logout_url: /api/logout
# Optional: Number of hashing iterations for user passwords
# As of Feb 2023, OWASP recommends 600000 iterations for PBKDF2-SHA256
# NOTE: changing this value will not automatically update password hashes, you
# will need to change each user password for it to apply
hash_iterations: 600000
# Optional: model modifications
model:
# Optional: path to the model (default: automatic based on detector)

2
docs/docs/configuration/restream.md
View File

@@ -11,7 +11,7 @@ Frigate uses [go2rtc](https://github.com/AlexxIT/go2rtc/tree/v1.9.2) to provide
:::note
You can access the go2rtc stream info at `http://frigate_ip:5000/api/go2rtc/streams` which can be helpful to debug as well as provide useful information about your camera streams.
You can access the go2rtc stream info at `http://frigate_ip:8080/api/go2rtc/streams` which can be helpful to debug as well as provide useful information about your camera streams.
:::

10
docs/docs/development/contributing.md
View File

@@ -225,3 +225,13 @@ docker buildx create --name builder --driver docker-container --driver-opt netwo
docker buildx inspect builder --bootstrap
make push
```
## Other
### Nginx
When testing nginx config changes from within the dev container, the following command can be used to copy and reload the config for testing without rebuilding the container:
```console
sudo cp docker/main/rootfs/usr/local/nginx/conf/* /usr/local/nginx/conf/ && sudo /usr/local/nginx/sbin/nginx -s reload
```

18
docs/docs/frigate/installation.md
View File

@@ -28,6 +28,17 @@ Frigate uses the following locations for read/write operations in the container.
- `/tmp/cache`: Cache location for recording segments. Initial recordings are written here before being checked and converted to mp4 and moved to the recordings folder. Segments generated via the `clip.mp4` endpoints are also concatenated and processed here. It is recommended to use a [`tmpfs`](https://docs.docker.com/storage/tmpfs/) mount for this.
- `/dev/shm`: Internal cache for raw decoded frames in shared memory. It is not recommended to modify this directory or map it with docker. The minimum size is impacted by the `shm-size` calculations below.
### Ports
The following ports are used by Frigate and can be mapped via docker as required.
| Port | Description |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `8080` | Authenticated UI and API access. Reverse proxies should use this port. |
| `5000` | Internal unauthenticated UI and API access. Access to this port should be limited. Intended to be used within the docker network for services that integrate with Frigate. |
| `8554` | RTSP restreaming. By default, these streams are unauthenticated. Authentication can be configured in go2rtc section of config. |
| `8555` | WebRTC connections for low latency live views. |
#### Common docker compose storage configurations
Writing to a local disk or external USB drive:
@@ -111,7 +122,8 @@ services:
tmpfs:
size: 1000000000
ports:
- "5000:5000"
- "8080:8080"
# - "5000:5000" # Internal unauthenticated access. Expose carefully.
- "8554:8554" # RTSP feeds
- "8555:8555/tcp" # WebRTC over tcp
- "8555:8555/udp" # WebRTC over udp
@@ -133,7 +145,7 @@ docker run -d \
-v /path/to/your/config:/config \
-v /etc/localtime:/etc/localtime:ro \
-e FRIGATE_RTSP_PASSWORD='password' \
-p 5000:5000 \
-p 8080:8080 \
-p 8554:8554 \
-p 8555:8555/tcp \
-p 8555:8555/udp \
@@ -300,7 +312,7 @@ docker run \
--network=bridge \
--privileged \
--workdir=/opt/frigate \
-p 5000:5000 \
-p 8080:8080 \
-p 8554:8554 \
-p 8555:8555 \
-p 8555:8555/udp \

4
docs/docs/guides/getting_started.md
View File

@@ -117,7 +117,7 @@ services:
tmpfs:
size: 1000000000
ports:
- "5000:5000"
- "8080:8080"
- "8554:8554" # RTSP feeds
```
@@ -137,7 +137,7 @@ cameras:
- detect
```
Now you should be able to start Frigate by running `docker compose up -d` from within the folder containing `docker-compose.yml`. Frigate should now be accessible at `server_ip:5000` and you can finish the configuration using the built-in configuration editor.
Now you should be able to start Frigate by running `docker compose up -d` from within the folder containing `docker-compose.yml`. On startup, an admin user and password will be created and outputted in the logs. You can see this by running `docker logs frigate`. Frigate should now be accessible at `server_ip:8080` where you can login with the `admin` user and finish the configuration using the built-in configuration editor.
## Configuring Frigate

18
docs/docs/guides/reverse_proxy.md
View File

@@ -38,20 +38,20 @@ Here we access Frigate via https://cctv.mydomain.co.uk
ServerName cctv.mydomain.co.uk
ProxyPreserveHost On
ProxyPass "/" "http://frigatepi.local:5000/"
ProxyPassReverse "/" "http://frigatepi.local:5000/"
ProxyPass "/" "http://frigatepi.local:8080/"
ProxyPassReverse "/" "http://frigatepi.local:8080/"
ProxyPass /ws ws://frigatepi.local:5000/ws
ProxyPassReverse /ws ws://frigatepi.local:5000/ws
ProxyPass /ws ws://frigatepi.local:8080/ws
ProxyPassReverse /ws ws://frigatepi.local:8080/ws
ProxyPass /live/ ws://frigatepi.local:5000/live/
ProxyPassReverse /live/ ws://frigatepi.local:5000/live/
ProxyPass /live/ ws://frigatepi.local:8080/live/
ProxyPassReverse /live/ ws://frigatepi.local:8080/live/
RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://frigatepi.local:5000/$1 [P,L]
RewriteRule /(.*) ws://frigatepi.local:8080/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
RewriteRule /(.*) http://frigatepi.local:5000/$1 [P,L]
RewriteRule /(.*) http://frigatepi.local:8080/$1 [P,L]
</VirtualHost>
```
@@ -101,7 +101,7 @@ This is set in `$server` and `$port` this should match your ports you have expos
server {
set $forward_scheme http;
set $server "192.168.100.2"; # FRIGATE SERVER LOCATION
set $port 5000;
set $port 8080;
listen 80;
listen 443 ssl http2;

2
docs/docs/integrations/api.md
View File

@@ -164,7 +164,7 @@ Accepts the following query string parameters:
| `motion` | int | Draw blue boxes for areas with detected motion (0 or 1) |
| `regions` | int | Draw green boxes for areas where object detection was run (0 or 1) |
You can access a higher resolution mjpeg stream by appending `h=height-in-pixels` to the endpoint. For example `http://localhost:5000/api/back?h=1080`. You can also increase the FPS by appending `fps=frame-rate` to the URL such as `http://localhost:5000/api/back?fps=10` or both with `?fps=10&h=1000`.
You can access a higher resolution mjpeg stream by appending `h=height-in-pixels` to the endpoint. For example `http://localhost:8080/api/back?h=1080`. You can also increase the FPS by appending `fps=frame-rate` to the URL such as `http://localhost:8080/api/back?fps=10` or both with `?fps=10&h=1000`.
### `GET /api/<camera_name>/latest.jpg[?h=300]`

82
docs/docs/integrations/home-assistant.md
View File

@@ -47,7 +47,55 @@ that card.
## Configuration
When configuring the integration, you will be asked for the `URL` of your Frigate instance which is the URL you use to access Frigate in the browser. This may look like `http://<host>:5000/`. If you are using HassOS with the addon, the URL should be one of the following depending on which addon version you are using. Note that if you are using the Proxy Addon, you do NOT point the integration at the proxy URL. Just enter the URL used to access Frigate directly from your network.
When configuring the integration, you will be asked for the `URL` of your Frigate instance which needs to be pointed at the internal unauthenticated port (`5000`) for your instance. This may look like `http://<host>:5000/`.
### Docker Compose Examples
If you are running Home Assistant Core and Frigate with Docker Compose on the same device, here are some examples.
#### Home Assistant running with host networking
It is not recommended to run Frigate in host networking mode. In this example, you would use `http://172.17.0.1:5000` when configuring the integration.
```yaml
services:
homeassistant:
container_name: hass
image: ghcr.io/home-assistant/home-assistant:stable
network_mode: host
...
frigate:
image: ghcr.io/blakeblackshear/frigate:stable
...
ports:
- "172.17.0.1:5000:5000"
...
```
#### Home Assistant _not_ running with host networking or in a separate compose file
In this example, you would use `http://frigate:5000` when configuring the integration. There is no need to map the port for the Frigate container.
```yaml
services:
homeassistant:
container_name: hass
image: ghcr.io/home-assistant/home-assistant:stable
# network_mode: host
...
frigate:
image: ghcr.io/blakeblackshear/frigate:stable
...
ports:
# - "172.17.0.1:5000:5000"
...
```
### HassOS Addon
If you are using HassOS with the addon, the URL should be one of the following depending on which addon version you are using. Note that if you are using the Proxy Addon, you do NOT point the integration at the proxy URL. Just enter the URL used to access Frigate directly from your network.
| Addon Version | URL |
| ------------------------------ | -------------------------------------- |
@@ -56,7 +104,37 @@ When configuring the integration, you will be asked for the `URL` of your Frigat
| Frigate NVR Beta | `http://ccab4aaf-frigate-beta:5000` |
| Frigate NVR Beta (Full Access) | `http://ccab4aaf-frigate-fa-beta:5000` |
<a name="options"></a>
### Frigate running on a separate machine
If you run Frigate on a separate device within your local network, Home Assistant will need access to port 5000.
#### Local network
Use `http://<frigate_device_ip>:5000` as the URL for the integration. If you want to protect access to port 5000, you can use firewall rules to limit access to the device running Home Assistant.
```yaml
services:
frigate:
image: ghcr.io/blakeblackshear/frigate:stable
...
ports:
- "5000:5000"
...
```
#### Tailscale or other private networking
Use `http://<frigate_device_tailscale_ip>:5000` as the URL for the integration.
```yaml
services:
frigate:
image: ghcr.io/blakeblackshear/frigate:stable
...
ports:
- "<tailscale_ip>:5000:5000"
...
```
## Options

2
docs/docs/integrations/third_party_extensions.md
View File

@@ -4,7 +4,7 @@ title: Third Party Extensions
---
Being open source, others have the possibility to modify and extend the rich functionality Frigate already offers.
This page is meant to be an overview over additions one can make to the home NVR setup. The list is not exhaustive and can be extended via PR to the Frigate docs.
This page is meant to be an overview over additions one can make to the home NVR setup. The list is not exhaustive and can be extended via PR to the Frigate docs. Most of these services are designed to interface with Frigate's unauthenticated api over port 5000.
:::warning

1692
docs/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

14
docs/package.json
View File

@@ -4,19 +4,19 @@
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"start": "docusaurus start --host 0.0.0.0",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"serve": "docusaurus serve --host 0.0.0.0",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "^3.2.1",
"@docusaurus/preset-classic": "^3.2.1",
"@docusaurus/theme-mermaid": "^3.2.1",
"@docusaurus/core": "^3.3.2",
"@docusaurus/preset-classic": "^3.3.2",
"@docusaurus/theme-mermaid": "^3.3.2",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"prism-react-renderer": "^2.1.0",
@@ -37,8 +37,8 @@
]
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.2.1",
"@docusaurus/types": "^3.2.1",
"@docusaurus/module-type-aliases": "^3.3.2",
"@docusaurus/types": "^3.3.2",
"@types/react": "^18.2.79"
},
"engines": {

1
docs/sidebars.js
View File

@@ -50,6 +50,7 @@ module.exports = {
"configuration/stationary_objects",
],
"Extra Configuration": [
"configuration/authentication",
"configuration/hardware_acceleration",
"configuration/ffmpeg_presets",
"configuration/advanced",