JWT Authentication

Accept externally-signed JWT tokens for secure authentication, enabling single sign-on, proxy authentication, and iframe embedding scenarios.

info

requires v1.3.x or newer

Basic Configuration

YAML
1
2
3
4
5
auth:
  methods:
    jwt:
      enabled: true
      secret: "your-shared-secret-key-here"  # Use environment variable

Configuration Options

Option	Default	Description
`enabled`	`false`	Enable JWT external authentication
`secret`	required	Shared secret for verifying JWT signatures
`algorithm`	`HS256`	JWT signing algorithm (HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512)
`header`	`X-JWT-Assertion`	HTTP header name to check for JWT token
`userIdentifier`	`sub`	JWT claim field to use as username
`groupsClaim`	`groups`	JWT claim field containing user groups
`adminGroup`	`""`	Group name that grants admin privileges
`userGroups`	`[]`	List of allowed groups (empty = allow all)
`logoutRedirectUrl`	`""`	URL to redirect after logout

How It Works

External authentication service generates a JWT token with user identity
Token is passed to FileBrowser via HTTP header or query parameter
FileBrowser verifies the token signature using the shared secret
If valid, FileBrowser extracts username and creates the user if needed
A FileBrowser session token is generated for subsequent requests

Token Delivery

HTTP Header (Recommended)

Pass the JWT token in the configured header:

BASH
1
2
curl -H "X-JWT-Assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://filebrowser.example.com/api/resources

Query Parameter

The query parameter is hardcoded to jwt:

`1`	`https://filebrowser.example.com?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`

warning

Security Note: Query parameter authentication exposes tokens in URLs, which may appear in logs and browser history. Always use HTTPS and prefer header-based authentication for sensitive deployments.

JWT Token Requirements

Required Claims

Your JWT token must contain:

sub (or configured userIdentifier) - The username
exp - Expiration timestamp (Unix timestamp)
Valid signature using the configured secret and algorithm

Optional Claims

email - User’s email address
name - User’s full name
groups - Array of group names for authorization
iat - Issued at timestamp
nbf - Not before timestamp

Example JWT Payload

JSON
1
2
3
4
5
6
7
8
{
  "sub": "john.doe",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "groups": ["users", "admin"],
  "exp": 1735689600,
  "iat": 1735603200
}

Generating JWT Tokens

Node.js

JAVASCRIPT
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    sub: 'john.doe',
    email: 'john.doe@example.com',
    groups: ['users', 'admin'],
    exp: Math.floor(Date.now() / 1000) + 3600  // 1 hour
  },
  'your-shared-secret-key-here',
  { algorithm: 'HS256' }
);

Python

PYTHON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import jwt
import time

token = jwt.encode(
    {
        'sub': 'john.doe',
        'email': 'john.doe@example.com',
        'groups': ['users', 'admin'],
        'exp': int(time.time()) + 3600  # 1 hour
    },
    'your-shared-secret-key-here',
    algorithm='HS256'
)

Go

GO
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import (
    "time"
    "github.com/golang-jwt/jwt/v4"
)

claims := jwt.MapClaims{
    "sub":    "john.doe",
    "email":  "john.doe@example.com",
    "groups": []string{"users", "admin"},
    "exp":    time.Now().Add(time.Hour).Unix(),
}

token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
tokenString, _ := token.SignedString([]byte("your-shared-secret-key-here"))

Group-Based Authorization

Admin Group

Automatically grant admin privileges to users in a specific group:

YAML
1
2
3
4
5
6
7
auth:
  methods:
    jwt:
      enabled: true
      secret: "your-secret"
      adminGroup: "admin"
      groupsClaim: "groups"

Users with "groups": ["admin"] in their JWT token will have admin access.

User Group Restrictions

Restrict access to specific groups only:

YAML
1
2
3
4
5
6
auth:
  methods:
    jwt:
      enabled: true
      secret: "your-secret"
      userGroups: ["employees", "contractors"]

Only users with JWT tokens containing these groups can log in.

Advanced Configuration

Custom Username Field

Use a different JWT claim for username:

YAML
1
2
3
4
5
6
auth:
  methods:
    jwt:
      enabled: true
      secret: "your-secret"
      userIdentifier: "email"  # Use email as username

JWT token payload:

JSON
1
2
3
4
{
  "email": "john.doe@example.com",
  "exp": 1735689600
}

Custom Header Name

Use a different HTTP header:

YAML
1
2
3
4
5
6
auth:
  methods:
    jwt:
      enabled: true
      secret: "your-secret"
      header: "Authorization"

Then use:

BASH
1
curl -H "Authorization: <token>" https://filebrowser.example.com

Different Signing Algorithm

Use RS256 (RSA) or ES256 (ECDSA) instead of HS256:

YAML
1
2
3
4
5
6
auth:
  methods:
    jwt:
      enabled: true
      secret: "your-public-key-here"
      algorithm: "RS256"

info

Note: For asymmetric algorithms (RS256, RS384, RS512, ES256, ES384, ES512), the secret field should contain the public key used to verify signatures.

Integration Examples

NGINX Reverse Proxy

Generate JWT tokens from authenticated users:

NGINX
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
server {
    listen 80;
    server_name filebrowser.example.com;

    location / {
        # Your custom logic to generate JWT token
        # This example assumes $jwt_token is set by auth module
        proxy_set_header X-JWT-Assertion $jwt_token;
        proxy_pass http://filebrowser:80;
    }
}

Iframe Embedding

Embed FileBrowser with user identity:

HTML
1
2
3
4
5
<iframe 
  src="https://filebrowser.example.com?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  width="100%" 
  height="600">
</iframe>

Windows NTLM Proxy

Example Express.js proxy with NTLM authentication:

JAVASCRIPT
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
const express = require('express');
const jwt = require('jsonwebtoken');
const ntlm = require('express-ntlm');

const app = express();

app.use(ntlm({
  domain: 'DOMAIN',
  domaincontroller: 'dc.domain.com'
}));

app.use((req, res, next) => {
  const token = jwt.sign(
    { sub: req.ntlm.UserName },
    'your-shared-secret-key-here',
    { algorithm: 'HS256', expiresIn: '1h' }
  );
  req.headers['x-jwt-assertion'] = token;
  // Proxy to FileBrowser
});

Security Best Practices

warning

Security Checklist:

✅ Always use HTTPS in production
✅ Use strong secrets (minimum 32 characters, random)
✅ Set short expiration times (1-2 hours recommended)
✅ Rotate secrets regularly
✅ Use header authentication instead of query params when possible
✅ Monitor failed authentication attempts
✅ Store secrets in environment variables, not config files

Environment Variable Best Practice

BASH
1
export FILEBROWSER_JWT_SECRET="your-generated-secret-here"

Then reference in config:

YAML
1
2
3
4
5
auth:
  methods:
    jwt:
      enabled: true
      secret: "${FILEBROWSER_JWT_SECRET}"

Troubleshooting