add new authentication system

README.md

@@ -57,7 +57,7 @@ And can be recorded and played back with:
 * Serve multiple streams at once in separate paths
 * Record streams to disk
 * Playback recorded streams
-* Authenticate users; use internal or external authentication
+* Authenticate users
 * Redirect readers to other RTSP servers (load balancing)
 * Control the server through the Control API
 * Reload the configuration without disconnecting existing clients (hot reloading)
@@ -113,6 +113,9 @@ _rtsp-simple-server_ has been rebranded as _MediaMTX_. The reason is pretty obvi
 * [Other features](#other-features)
   * [Configuration](#configuration)
   * [Authentication](#authentication)
+    * [Internal](#internal)
+    * [HTTP-based](#http-based)
+    * [JWT-based](#jwt-based)
   * [Encrypt the configuration](#encrypt-the-configuration)
   * [Remuxing, re-encoding, compression](#remuxing-re-encoding-compression)
   * [Record streams to disk](#record-streams-to-disk)
@@ -1028,31 +1031,44 @@ There are 3 ways to change the configuration:
 
 ### Authentication
 
-Edit `mediamtx.yml` and set `publishUser` and `publishPass`:
+#### Internal
 
-```yml
-pathDefaults:
-  publishUser: myuser
-  publishPass: mypass
-```
+The server provides three way to authenticate users:
+* Internal: users are stored in the configuration file
+* HTTP-based: an external HTTP URL is contacted to perform authentication
+* JWT: an external identity server provides authentication through JWTs
 
-Only publishers that provide both username and password will be able to proceed:
+The internal authentication method is the default one. Users are stored inside the configuration file, in this format:
+
+```yml
+authInternalUsers:
+  # Username. 'any' means any user, including anonymous ones.
+- user: any
+  # Password. Not used in case of 'any' user.
+  pass:
+  # IPs or networks allowed to use this user. An empty list means any IP.
+  ips: []
+  # List of permissions.
+  permissions:
+    # Available actions are: publish, read, playback, api, metrics, pprof.
+  - action: publish
+    # Paths can be set to further restrict access to a specific path.
+    # An empty path means any path.
+    # Regular expressions can be used by using a tilde as prefix.
+    path:
+  - action: read
+    path:
+  - action: playback
+    path:
+```
+
+Only clients that provide username and passwords will be able to perform a given action:
 
 ```
 ffmpeg -re -stream_loop -1 -i file.ts -c copy -f rtsp rtsp://myuser:mypass@localhost:8554/mystream
 ```
 
-It's possible to setup authentication for readers too:
-
-```yml
-pathDefaults:
-  readUser: myuser
-  readPass: mypass
-```
-
-If storing plain credentials in the configuration file is a security problem, username and passwords can be stored as hashed strings. The Argon2 and SHA256 hashing algorithms are supported.
-
-To use Argon2, the string must be hashed using Argon2id (recommended) or Argon2i:
+If storing plain credentials in the configuration file is a security problem, username and passwords can be stored as hashed strings. The Argon2 and SHA256 hashing algorithms are supported. To use Argon2, the string must be hashed using Argon2id (recommended) or Argon2i:
 
 ```
 echo -n "mypass" | argon2 saltItWithSalt -id -l 32 -e
@@ -1061,9 +1077,11 @@ echo -n "mypass" | argon2 saltItWithSalt -id -l 32 -e
 Then stored with the `argon2:` prefix:
 
 ```yml
-pathDefaults:
-  readUser: argon2:$argon2id$v=19$m=4096,t=3,p=1$MTIzNDU2Nzg$OGGO0eCMN0ievb4YGSzvS/H+Vajx1pcbUmtLp2tRqRU
-  readPass: argon2:$argon2i$v=19$m=4096,t=3,p=1$MTIzNDU2Nzg$oct3kOiFywTdDdt19kT07hdvmsPTvt9zxAUho2DLqZw
+authInternalUsers:
+- user: argon2:$argon2id$v=19$m=4096,t=3,p=1$MTIzNDU2Nzg$OGGO0eCMN0ievb4YGSzvS/H+Vajx1pcbUmtLp2tRqRU
+  pass: argon2:$argon2i$v=19$m=4096,t=3,p=1$MTIzNDU2Nzg$oct3kOiFywTdDdt19kT07hdvmsPTvt9zxAUho2DLqZw
+  permissions:
+  - action: publish
 ```
 
 To use SHA256, the string must be hashed with SHA256 and encoded with base64:
@@ -1075,37 +1093,40 @@ echo -n "mypass" | openssl dgst -binary -sha256 | openssl base64
 Then stored with the `sha256:` prefix:
 
 ```yml
-pathDefaults:
-  readUser: sha256:j1tsRqDEw9xvq/D7/9tMx6Jh/jMhk3UfjwIB2f1zgMo=
-  readPass: sha256:BdSWkrdV+ZxFBLUQQY7+7uv9RmiSVA8nrPmjGjJtZQQ=
+authInternalUsers:
+- user: sha256:j1tsRqDEw9xvq/D7/9tMx6Jh/jMhk3UfjwIB2f1zgMo=
+  pass: sha256:BdSWkrdV+ZxFBLUQQY7+7uv9RmiSVA8nrPmjGjJtZQQ=
+  permissions:
+  - action: publish
 ```
 
 **WARNING**: enable encryption or use a VPN to ensure that no one is intercepting the credentials in transit.
 
+#### HTTP-based
+
 Authentication can be delegated to an external HTTP server:
 
 ```yml
+authMethod: http
 externalAuthenticationURL: http://myauthserver/auth
 ```
 
 Each time a user needs to be authenticated, the specified URL will be requested with the POST method and this payload:
 
 ```json
 {
-  "ip": "ip",
   "user": "user",
   "password": "password",
+  "ip": "ip",
+  "action": "publish|read|playback|api|metrics|pprof",
   "path": "path",
-  "protocol": "rtsp|rtmp|hls|webrtc",
+  "protocol": "rtsp|rtmp|hls|webrtc|srt",
   "id": "id",
-  "action": "read|publish",
   "query": "query"
 }
 ```
 
-If the URL returns a status code that begins with `20` (i.e. `200`), authentication is successful, otherwise it fails.
-
-Please be aware that it's perfectly normal for the authentication server to receive requests with empty users and passwords, i.e.:
+If the URL returns a status code that begins with `20` (i.e. `200`), authentication is successful, otherwise it fails. Be aware that it's perfectly normal for the authentication server to receive requests with empty users and passwords, i.e.:
 
 ```json
 {
@@ -1114,7 +1135,87 @@ Please be aware that it's perfectly normal for the authentication server to rece
 }
 ```
 
-This happens because a RTSP client doesn't provide credentials until it is asked to. In order to receive the credentials, the authentication server must reply with status code `401`, then the client will send credentials.
+This happens because RTSP clients don't provide credentials until they are asked to. In order to receive the credentials, the authentication server must reply with status code `401`, then the client will send credentials.
+
+Some actions can be excluded from the process:
+
+```yml
+# Actions to exclude from HTTP-based authentication.
+# Format is the same as the one of user permissions.
+authHTTPExclude:
+- action: api
+- action: metrics
+- action: pprof
+```
+
+#### JWT-based
+
+Authentication can be delegated to an external identity server, that is capable of generating JWTs and provides a JWKS endpoint. With respect to the HTTP-based method, this has the advantage that the external server is contacted just once, and not for every request, greatly improving performance. In order to use the JWT-based authentication method, set `authMethod` and `authJWTJWKS`:
+
+```yml
+authMethod: jwt
+authJWTJWKS: http://my_identity_server/jwks_endpoint
+```
+
+The JWT is expected to contain the `mediamtx_permissions` scope, with a list of permissions in the same format as the one of user permissions:
+
+```json
+{
+ ...
+ "mediamtx_permissions": [
+    {
+      "action": "publish",
+      "path": ""
+    }
+  ]
+}
+```
+
+Clients are expected to pass the JWT in query parameters, for instance:
+
+```
+ffmpeg -re -stream_loop -1 -i file.ts -c copy -f rtsp rtsp://localhost:8554/mystream?jwt=MY_JWT
+```
+
+Here's a tutorial on how to setup the [Keycloak identity server](https://www.keycloak.org/) in order to provide such JWTs:
+
+1. Start Keycloak:
+
+   ```
+   docker run --rm -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:23.0.7 start-dev
+   ```
+
+2. Open the Keycloak administration console, click on "master" in the top left corner, "create realm", set realm name to `mediamtx`, Save
+
+3. Click on "Client scopes", "create client scope", set name to `mediamtx`, Save
+
+4. Tab "Mappers", "Configure a new Mapper", "User Attribute"
+
+   * Name: `mediamtx_permissions`
+   * User Attribute: `mediamtx_permissions`
+   * Token Claim Name: `mediamtx_permissions`
+   * Claim JSON Type: `JSON`
+   * Multivalued: `On`
+
+   Save
+
+5. Page "Clients", "Create client", set Client ID to `mediamtx`, Next, Client authentication `On`, Next, Save
+
+6. Open Tab "Credentials", copy client secret somewhere
+
+7. Tab "Client scopes", "Add client scope", Select `mediamtx`, Add, Default
+
+8. Page "Users", "Create user", Username `testuser`, Tab credentials, "Set password", pick a password, Save
+
+9. Tab "Attributes", "Add an attribute"
+   * Key: mediamtx_permissions
+   * Value: {"action":"publish", "paths": "all"}
+
+10. In MediaMTX, use the following URL:
+
+    ```yml
+    authJWTJWKS: http://localhost:8080/realms/mediamtx/protocol/openid-connect/certs
+    ```
 
 ### Encrypt the configuration
 

go.mod

@@ -4,6 +4,7 @@ go 1.21
 
 require (
 	code.cloudfoundry.org/bytefmt v0.0.0
+	github.com/MicahParks/keyfunc/v3 v3.2.5
 	github.com/abema/go-mp4 v1.2.0
 	github.com/alecthomas/kong v0.8.1
 	github.com/bluenviron/gohlslib v1.2.2
@@ -12,6 +13,7 @@ require (
 	github.com/datarhei/gosrt v0.5.7
 	github.com/fsnotify/fsnotify v1.7.0
 	github.com/gin-gonic/gin v1.9.1
+	github.com/golang-jwt/jwt/v5 v5.2.0
 	github.com/google/uuid v1.6.0
 	github.com/gookit/color v1.5.4
 	github.com/gorilla/websocket v1.5.1
@@ -32,6 +34,7 @@ require (
 )
 
 require (
+	github.com/MicahParks/jwkset v0.5.12 // indirect
 	github.com/asticode/go-astikit v0.30.0 // indirect
 	github.com/asticode/go-astits v1.13.0 // indirect
 	github.com/benburkert/openpgp v0.0.0-20160410205803-c2471f86866c // indirect
@@ -67,6 +70,7 @@ require (
 	golang.org/x/arch v0.3.0 // indirect
 	golang.org/x/net v0.21.0 // indirect
 	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/time v0.5.0 // indirect
 	google.golang.org/protobuf v1.30.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,3 +1,7 @@
+github.com/MicahParks/jwkset v0.5.12 h1:wEwKZXB77yHFIHBtYoawNKIUwqC1X24S8tIhWutJHMA=
+github.com/MicahParks/jwkset v0.5.12/go.mod h1:q8ptTGn/Z9c4MwbcfeCDssADeVQb3Pk7PnVxrvi+2QY=
+github.com/MicahParks/keyfunc/v3 v3.2.5 h1:eg4s2zd2nfadnAzAsv9xvJCdCfLNy4s/aSiAxRn+aAk=
+github.com/MicahParks/keyfunc/v3 v3.2.5/go.mod h1:8hmM7h/hNerfF8uC8cFVnT+afxBgh6nKRTR/0vAm5So=
 github.com/abema/go-mp4 v1.2.0 h1:gi4X8xg/m179N/J15Fn5ugywN9vtI6PLk6iLldHGLAk=
 github.com/abema/go-mp4 v1.2.0/go.mod h1:vPl9t5ZK7K0x68jh12/+ECWBCXoWuIDtNgPtU2f04ws=
 github.com/alecthomas/assert/v2 v2.1.0 h1:tbredtNcQnoSd3QBhQWI7QZ3XHOVkw1Moklp2ojoH/0=
@@ -57,6 +61,8 @@ github.com/go-playground/validator/v10 v10.14.0/go.mod h1:9iXMNT7sEkjXb0I+enO7QX
 github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE=
 github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
 github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
+github.com/golang-jwt/jwt/v5 v5.2.0 h1:d/ix8ftRUorsN+5eMIlF4T6J8CAt9rch3My2winC1Jw=
+github.com/golang-jwt/jwt/v5 v5.2.0/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8=
 github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA=
@@ -285,6 +291,8 @@ golang.org/x/text v0.12.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/time v0.5.0 h1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk=
+golang.org/x/time v0.5.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=

internal/api/api.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net"
 	"net/http"
 	"os"
 	"reflect"
@@ -17,6 +18,7 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
 
+	"github.com/bluenviron/mediamtx/internal/auth"
 	"github.com/bluenviron/mediamtx/internal/conf"
 	"github.com/bluenviron/mediamtx/internal/defs"
 	"github.com/bluenviron/mediamtx/internal/logger"
@@ -159,6 +161,7 @@ type API struct {
 	Address      string
 	ReadTimeout  conf.StringDuration
 	Conf         *conf.Conf
+	AuthManager  *auth.Manager
 	PathManager  PathManager
 	RTSPServer   RTSPServer
 	RTSPSServer  RTSPServer
@@ -178,7 +181,7 @@ func (a *API) Initialize() error {
 	router := gin.New()
 	router.SetTrustedProxies(nil) //nolint:errcheck
 
-	group := router.Group("/")
+	group := router.Group("/", a.mwAuth)
 
 	group.GET("/v3/config/global/get", a.onConfigGlobalGet)
 	group.PATCH("/v3/config/global/patch", a.onConfigGlobalPatch)
@@ -287,6 +290,30 @@ func (a *API) writeError(ctx *gin.Context, status int, err error) {
 	})
 }
 
+func (a *API) mwAuth(ctx *gin.Context) {
+	user, pass, hasCredentials := ctx.Request.BasicAuth()
+
+	err := a.AuthManager.Authenticate(&auth.Request{
+		User:   user,
+		Pass:   pass,
+		IP:     net.ParseIP(ctx.ClientIP()),
+		Action: conf.AuthActionAPI,
+	})
+	if err != nil {
+		if !hasCredentials {
+			ctx.Header("WWW-Authenticate", `Basic realm="mediamtx"`)
+			ctx.AbortWithStatus(http.StatusUnauthorized)
+			return
+		}
+
+		// wait some seconds to mitigate brute force attacks
+		<-time.After(auth.PauseAfterError)
+
+		ctx.AbortWithStatus(http.StatusUnauthorized)
+		return
+	}
+}
+
 func (a *API) onConfigGlobalGet(ctx *gin.Context) {
 	a.mutex.RLock()
 	c := a.Conf