ExtAuth - external authentication API for VLESS (potential upstream contribution)

[thearialume]

Hi! I'm a founder building a VPN service, and I ran into a problem I think some of you know well.

Xray-core gives you two ways to manage users: hardcode them in a config file, or use the gRPC API. Both work, but neither is great at scale, with a cluster of nodes you're either editing files everywhere or hitting every server individually with no session visibility.

There are panels like Remnawave and Marzban that try to solve this, and I used them! But they come with significant overhead and sit between you and the core, which makes it hard to implement precise business logic on your end.

I also know such feature has been discussed before, but it never got implemented. So I decided to build it myself as a fork: cnap-core 🎉

What it adds: ExtAuth

A new extAuth block in VLESS (Only supported protocol for now) inbound config that delegates authentication to your HTTP API:

{
  "inbounds": [
    {
      "port": 443,
      "protocol": "vless",
      "settings": {
        "decryption": "none",
        "extAuth": {
          "url": "https://your-backend.com/auth",
          "timeout": 5,
          "ttl": 60,
          "headers": {
            "Authorization": "Bearer secret"
          },
          "notifications": {
            "connect": true,
            "heartbeat": 30,
            "disconnect": true
          }
        }
      }
    }
  ]
}

When a client connects, your server receives:

{
  "type":        "authorization",
  "credential":  "550e8400-e29b-41d4-a716-446655440000",
  "connection":  "a3f1c2d4-9b8e-4f1a-b2c3-d4e5f6a7b8c9",
  "email":       "alice@example.com",
  "level":       0, 
  "protocol":    "vless",
  "inboundTag":  "my-inbound",
  "sourceIP":    "1.2.3.4",
  "sourcePort":  52341,
  "localIP":     "10.0.0.1",
  "localPort":   443,
  "timestamp":   1710000000
}

Note: email and level are only present in notification events (connect, heartbeat, disconnect), not in authorization. protocol is currently only populated on heartbeat and disconnect events, fix coming.

Reply with user info to allow:

{ "user": { "email": "alice@example.com", "level": 0 } }

Or 401/403 to deny.

If notifications.connect, notifications.heartbeat, or notifications.disconnect are enabled, your server also receives lifecycle events for each connection: same endpoint, just a different type field (connect, heartbeat, disconnect). Useful for session tracking, usage metering, or kicking users mid-session by returning 401 on a heartbeat.

A few honest caveats:

The VLESS validator integration is not fully complete yet, some methods are currently no-ops since ExtAuth is read-only by nature. It works reliably for authentication and session tracking, but things like dynamic user management via gRPC API won't work when ExtAuth is enabled. I plan to address this before any upstream PR. Down the road I also want to extend ExtAuth to other protocols beyond VLESS.

If the maintainers are interested, I'm happy to submit a proper upstream PR, even if it needs significant changes to fit the codebase!

Full docs: GitHub Wiki

[thearialume]

Hiya! In case someone reads this discussion, quick update on the progress.

Honestly, forget everything I wrote above about the notifications block. I am completely rewriting this part! 😅

After some thinking and testing, I realized I built a monolithic module trying to solve too many problems at once. Mixing connection metrics with authentication is just a bad idea that completely breaks the separation of concerns.

Also, hitting the auth backend for every single connection is a guaranteed way to DDoS your own servers on scale. I even tried to fix this by batching events into single requests, but to be honest, the code just turned into a messy garbage that was overcomplicated and hard to maintain.

So, here is the new plan:
I am dropping all connection lifecycle events (connect, heartbeat, disconnect) and the type field entirely. ExtAuth module will now focus strictly on pure background authentication. It will silently refresh user cache in the background without causing any latency spikes for users and without melting down your database.

I'm currently rewriting the whole core module to reflect this clean, auth-only approach! So consider everything written in wiki out of date!

[ergoz]

I think first variant is better because i can have 1 million accounts in databse and store it in xray cache not good, too much memory usage. to prevent ddos user storage i can use load balancer + cache in my own api.

But idea about move out from auth module lifecycle events (connect, heartbeat, disconnect) is good. I think it should be another module in xray-core with another config for inbound (to have ability to set different event receivers for different inbounds).

[thearialume]

Hehehe, there is a slight misunderstanding about module architecture, my bad! And thanks for the feedback!

Yup, I absolutely agree with you on idea of separate module for lifecycle notifications, and it's already planned!

Now, to correct the misunderstanding! I'm a bit bad at explaining things and I was very vague last time, so sorry again!
Both solutions I introduced before are actually designed same way to solve same problem, but I guess this quote led to confusion:

It will silently refresh user cache in the background without causing any latency spikes for users and without melting down your database.

As I said, my problem is that I tried to solve many problems at once! One of which is user session renewal and tracking, which led me down the rabbit hole of over-engineering!

First solution was designed this way: Authorize user and send heartbeat notifications for long-living connections to renew it. So server knows user is still here and agrees to renew him by responding with 200 OK. So this way, the user will experience an HTTP API authorization delay only on the first connection!

But I dropped this idea, because of monolithic design and failure to maintain separation of concerns! So second solution was designed this way: Authorize user and in case he has active connections, renew him right before cache expiry (Using same authorization request to HTTP API). So it also provides delayless experience for user!

But after all, it's still an over-engineering, 30ms delay once in a minute to renew cache isn't that bad for a user experience. So I narrowed everything down once again and now I'm working on third variant (hopefully the last one)! Now the configuration looks like that:

{
  "inbounds": [
    {
      "port": 443,
      "protocol": "vless",
      "settings": {
        "decryption": "none",
        "extAuth": {
          "url": "https://your-backend.com/auth",
          "headers": {
            "Authorization": "Bearer secret"
          },
          "timeout": 1000 // Timeout to HTTP API in milliseconds
        }
      }
    }
  ]
}

Authorization request like that:

{
  "credential": "550e8400-e29b-41d4-a716-446655440000",
  "protocol": "vless",
  "inboundTag": "my-inbound",
  "sourceIP": "1.2.3.4",
  "sourcePort": 52341,
  "localIP": "10.0.0.1",
  "localPort": 443,
  "timestamp": 1710000000
}

And HTTP API response like that:

{
  "email": "user@example.com",
  "level": 0,
  "ttl": 3600, // Response cache time in seconds (Calculated from included timestamp)
  "timestamp": 1710000000
}

So cache ttl is now controlled by HTTP API response (It can be dropped or set to 0 to disable caching, every connection will be authorized with HTTP API). And once cache is expired, it will just make new authorization request (It will add some delay to one of user connections, since there is no silent renewal anymore, but it's negligible). timestamp in response is used as a reference point for TTL calculation, in case there is any network delay between HTTP API and Xray.

Sorry for the wall of text, just wanted to clearly explain current progress on ExtAuth!

[ergoz]

I have same problems with introduce something :)

About third variant - it looks awesome :) i will be glad if it will be released) but why do you plan to return timestamp in response, why not to use same that used in request to internal cache calculating.

And response could be just

{
  "email": "user@example.com",
  "level": 0,
  "ttl": 3600
}

And do we really need level here in response? what does this field mean?

And for future, why lifecicle "module" very important - it will be needed to detect how many users connected in one moment, to limit by ip or any other criteria)

Thank you for your work and explanation!