mediamtx/docs/2-usage/6-authentication.md

Authentication

Overview

The server provides three methods 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

Internal

The internal authentication method is the default one. Users are stored inside the configuration file, in this format:

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 certain action:

ffmpeg -re -stream_loop -1 -i file.ts -c copy -f rtsp rtsp://myuser:mypass@localhost:8554/mystream

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

Then stored with the argon2: prefix:

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:

echo -n "mypass" | openssl dgst -binary -sha256 | openssl base64

Then stored with the sha256: prefix:

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:

authMethod: http
authHTTPAddress: http://myauthserver/auth

Each time a user needs to be authenticated, the specified URL will be requested with the POST method and this payload:

{
  "user": "user",
  "password": "password",
  "token": "token",
  "ip": "ip",
  "action": "publish|read|playback|api|metrics|pprof",
  "path": "path",
  "protocol": "rtsp|rtmp|hls|webrtc|srt",
  "id": "id",
  "query": "query"
}

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.:

{
  "user": "",
  "password": ""
}

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:

# 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 once, and not for every request, greatly improving performance. In order to use the JWT-based authentication method, set authMethod and authJWTJWKS:

authMethod: jwt
authJWTJWKS: http://my_identity_server/jwks_endpoint
authJWTClaimKey: mediamtx_permissions

The JWT is expected to contain a claim, with a list of permissions in the same format as the one of user permissions:

{
  "mediamtx_permissions": [
    {
      "action": "publish",
      "path": ""
    }
  ]
}

Clients are expected to pass the JWT in one of the following ways (from best to worst):

1. Through the Authorization: Bearer HTTP header. This is possible if the protocol or feature is based on HTTP, like HLS, WebRTC, API, Metrics, pprof.

2. As password. Username is arbitrary.

3. As query parameter in the URL, with the jwt key. This method is discouraged since the JWT is publicly shared when the URL is shared, causing a security issue.

These are the recommended methods for each client:

client	protocol	method	notes
Web browsers	HLS	Authorization: Bearer
Web browsers	WebRTC	Authorization: Bearer
OBS Studio	WebRTC	Authorization: Bearer
OBS Studio	RTMP	Query parameter
FFmpeg	RTSP	Query parameter	password is truncated and cannot be used
FFmpeg	RTMP	unsupported	Passwords and query parameters are currently truncated to 1024 characters by FFmpeg, so it's impossible to use FFMPEG+RTMP+JWT
GStreamer	RTSP	Password
GStreamer	RTMP	Query parameter
any	SRT	unsupported	SRT truncates passwords and query parameters to 512 characters, so it's impossible to use SRT+JWT. See #3430

Keycloak setup

Here's a tutorial on how to setup the Keycloak identity server in order to provide JWTs:

1. Start Keycloak:

   docker run --name=keycloak -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 on http://localhost:8080, click on master in the top left corner, create realm, set realm name to mediamtx, Save

3. Open page Client scopes, create client scope, set name to mediamtx, Save

4. Open 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. Open page Clients, Create client, set Client ID to mediamtx, Next, Client authentication On, Next, Save

6. Open tab Credentials, copy client secret somewhere

7. Open tab Client scopes, Add client scope, Select mediamtx, Add, Default

8. Open page Users, Add user, Username testuser, Tab credentials, Set password, pick a password, Save

9. Open tab Attributes, Add an attribute

   • Key: mediamtx_permissions
   • Value: {"action":"publish", "path": ""}

   You can add as many attributes with key mediamtx_permissions as you want, each with a single permission in it

10. In MediaMTX, use the following URL:

    authJWTJWKS: http://localhost:8080/realms/mediamtx/protocol/openid-connect/certs
    

11. Perform authentication on Keycloak:

    curl \
    -d "client_id=mediamtx" \
    -d "client_secret=$CLIENT_SECRET" \
    -d "username=$USER" \
    -d "password=$PASS" \
    -d "grant_type=password" \
    http://localhost:8080/realms/mediamtx/protocol/openid-connect/token
    

    The JWT is inside the access_token key of the response:

    {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyNzVjX3ptOVlOdHQ0TkhwWVk4Und6ZndUclVGSzRBRmQwY3lsM2wtY3pzIn0.eyJleHAiOjE3MDk1NTUwOTIsImlhdCI6MTcwOTU1NDc5MiwianRpIjoiMzE3ZTQ1NGUtNzczMi00OTM1LWExNzAtOTNhYzQ2ODhhYWIxIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tZWRpYW10eCIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiI2NTBhZDA5Zi03MDgxLTQyNGItODI4Ni0xM2I3YTA3ZDI0MWEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJtZWRpYW10eCIsInNlc3Npb25fc3RhdGUiOiJjYzJkNDhjYy1kMmU5LTQ0YjAtODkzZS0wYTdhNjJiZDI1YmQiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIi8qIl0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiZGVmYXVsdC1yb2xlcy1tZWRpYW10eCJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoibWVkaWFtdHggcHJvZmlsZSBlbWFpbCIsInNpZCI6ImNjMmQ0OGNjLWQyZTktNDRiMC04OTNlLTBhN2E2MmJkMjViZCIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwibWVkaWFtdHhfcGVybWlzc2lvbnMiOlt7ImFjdGlvbiI6InB1Ymxpc2giLCJwYXRocyI6ImFsbCJ9XSwicHJlZmVycmVkX3VzZXJuYW1lIjoidGVzdHVzZXIifQ.Gevz7rf1qHqFg7cqtSfSP31v_NS0VH7MYfwAdra1t6Yt5rTr9vJzqUeGfjYLQWR3fr4XC58DrPOhNnILCpo7jWRdimCnbPmuuCJ0AYM-Aoi3PAsWZNxgmtopq24_JokbFArY9Y1wSGFvF8puU64lt1jyOOyxf2M4cBHCs_EarCKOwuQmEZxSf8Z-QV9nlfkoTUszDCQTiKyeIkLRHL2Iy7Fw7_T3UI7sxJjVIt0c6HCNJhBBazGsYzmcSQ_GrmhbUteMTg00o6FicqkMBe99uZFnx9wIBm_QbO9hbAkkzF923I-DTAQrFLxT08ESMepDwmzFrmnwWYBLE3u8zuUlCA",
      "expires_in": 300,
      "refresh_expires_in": 1800,
      "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3OTI3Zjg4Zi05YWM4LTRlNmEtYWE1OC1kZmY0MDQzZDRhNGUifQ.eyJleHAiOjE3MDk1NTY1OTIsImlhdCI6MTcwOTU1NDc5MiwianRpIjoiMGVhZWFhMWItYzNhMC00M2YxLWJkZjAtZjI2NTRiODlkOTE3IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tZWRpYW10eCIsImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9yZWFsbXMvbWVkaWFtdHgiLCJzdWIiOiI2NTBhZDA5Zi03MDgxLTQyNGItODI4Ni0xM2I3YTA3ZDI0MWEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoibWVkaWFtdHgiLCJzZXNzaW9uX3N0YXRlIjoiY2MyZDQ4Y2MtZDJlOS00NGIwLTg5M2UtMGE3YTYyYmQyNWJkIiwic2NvcGUiOiJtZWRpYW10eCBwcm9maWxlIGVtYWlsIiwic2lkIjoiY2MyZDQ4Y2MtZDJlOS00NGIwLTg5M2UtMGE3YTYyYmQyNWJkIn0.yuXV8_JU0TQLuosNdp5xlYMjn7eO5Xq-PusdHzE7bsQ",
      "token_type": "Bearer",
      "not-before-policy": 0,
      "session_state": "cc2d48cc-d2e9-44b0-893e-0a7a62bd25bd",
      "scope": "mediamtx profile email"
    }