[GH-ISSUE #601] Authentication: match username from configurable header

BreizhHardware commented

2026-05-07 00:24:20 +02:00

Owner

Originally created by @ngerstle on GitHub (Feb 4, 2023).
Original GitHub issue: https://github.com/binwiederhier/ntfy/issues/601

I'd like to elevate https://github.com/binwiederhier/ntfy/issues/19#issuecomment-1023118885 as an explicit feature request, that I believe enables administrators/users that self-host to handle both https://github.com/binwiederhier/ntfy/issues/530 and https://github.com/binwiederhier/ntfy/issues/296 (and may make a custom solution for https://github.com/binwiederhier/ntfy/issues/297 easier for users to implement).

I'd propose a configuration option (user-header) specifying a trusted header that a proxy in front of ntfy could set, and whose value is matched to a username. If the value matches an existing username, then ntfy assumes the request/connection to originate from that user, delegating the responsibility for credential validation to the proxy.

Example:
If the configuration for the server (server.yml) has the following:

user-header: x-forwarded-user

Then a request reaching ntfy with

POST /mytopic HTTP/1.1
Host: ntfy.sh
x-forwarded-user: ngerstle

Backup successful

would be trusted to be made by the user ngerstle.

Authorization, and user management (excepting possible changes around passwords, if desired), would not change.

This would allow any number of different authentication options for access (depending on client support), ranging from the presently implemented basic, to LDAP, OIDC, OAuth2, JWT, mTLS, etc.
Options for proxies are numerous, and include (among others):

If a dependency on a proxy is an acceptable requirement for authentication, then existing password storage and validation code could be removed entirely.

Client support for different authentication forms would vary, but differences already exist between client support for different features (streams, for example). The selection of authentication mechanism(s) can be left to administrators, and they would need to evaluate which clients support what forms of authentication.
Ideally, all clients support all forms of authentication, but applications can add support independently, and as there is interest once reverse proxies are supported. I would suggest adding mTLS/OIDC/OAuth2 to the Android/iOS apps; most programming languages have support for acquiring credentials based on common authentication flows, and if there are custom tools built I'd suggest using standard libraries.

Open question:
I defer on whether it should be possible to enable multiple forms of authentication at a time.

There is the option to allow both forms of user determination to function concurrently (prioritizing the configured header if present ahead of/behind basic auth?), or making the two options mutually exclusive. Mutually exclusive authentication is easier to reason about, but makes migration between forms harder, and can result in users being locked out (if no admin user exists/can be authenticated to, though this may be a risk in any case).

I do want to compliment the project- barring some typos while switching reverse proxies, I was able to start hosting ntfy remarkably quickly, and have found it easy to use- thanks for the contribution to the opensource ecosystem!

Originally created by @ngerstle on GitHub (Feb 4, 2023). Original GitHub issue: https://github.com/binwiederhier/ntfy/issues/601 I'd like to elevate https://github.com/binwiederhier/ntfy/issues/19#issuecomment-1023118885 as an explicit feature request, that I believe enables administrators/users that self-host to handle both https://github.com/binwiederhier/ntfy/issues/530 and https://github.com/binwiederhier/ntfy/issues/296 (and may make a custom solution for https://github.com/binwiederhier/ntfy/issues/297 easier for users to implement). I'd propose a configuration option (`user-header`) specifying a trusted header that a proxy in front of ntfy could set, and whose value is matched to a username. If the value matches an existing username, then ntfy assumes the request/connection to originate from that user, delegating the responsibility for credential validation to the proxy. Example: If the configuration for the server (`server.yml`) has the following: ``` user-header: x-forwarded-user ``` Then a request reaching ntfy with ``` POST /mytopic HTTP/1.1 Host: ntfy.sh x-forwarded-user: ngerstle Backup successful ``` would be trusted to be made by the user `ngerstle`. Authorization, and user management (excepting possible changes around passwords, if desired), would not change. This would allow any number of different authentication options for access (depending on client support), ranging from the presently implemented basic, to LDAP, OIDC, OAuth2, JWT, mTLS, etc. Options for proxies are numerous, and include (among others): - [traefik](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) - [caddy](https://caddyserver.com/docs/caddyfile/directives/forward_auth) - [oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy) - [pomerium](https://www.pomerium.com/) - [cloudflare](https://developers.cloudflare.com/cloudflare-one/identity/) - [tailscale](https://github.com/tailscale/tailscale/tree/main/cmd/nginx-auth) If a dependency on a proxy is an acceptable requirement for authentication, then existing password storage and validation code could be removed entirely. Client support for different authentication forms would vary, but differences already exist between client support for different features (streams, for example). The selection of authentication mechanism(s) can be left to administrators, and they would need to evaluate which clients support what forms of authentication. Ideally, all clients support all forms of authentication, but applications can add support independently, and as there is interest once reverse proxies are supported. I would suggest adding mTLS/OIDC/OAuth2 to the Android/iOS apps; most programming languages have support for acquiring credentials based on common authentication flows, and if there are custom tools built I'd suggest using standard libraries. Open question: I defer on whether it should be possible to enable multiple forms of authentication at a time. 1. There is the option to allow both forms of user determination to function concurrently (prioritizing the configured header if present ahead of/behind basic auth?), or making the two options mutually exclusive. Mutually exclusive authentication is easier to reason about, but makes migration between forms harder, and can result in users being locked out (if no admin user exists/can be authenticated to, though this may be a risk in any case). I do want to compliment the project- barring some typos while switching reverse proxies, I was able to start hosting ntfy remarkably quickly, and have found it easy to use- thanks for the contribution to the opensource ecosystem!

BreizhHardware added the

🔥 HOT

enhancement

server

labels

2026-05-07 00:24:20 +02:00

BreizhHardware commented

2026-05-07 00:24:21 +02:00

Author

Owner

@binwiederhier commented on GitHub (Feb 5, 2023):

I do not have the time to fully answer, but I do like this idea, and the WIP implementation doesn't look half bad.

It is worth noting that Android/iOS/web client also need to support whatever you are implementing, which may makes things a lot trickier.

Also: Implementing anything on top of main right now is not a good idea. I have been working on the user-account branch for over a month now, so it may be a good idea to re-base (re-implement) on top of that.

@binwiederhier commented on GitHub (Feb 5, 2023): I do not have the time to fully answer, but I do like this idea, and the WIP implementation doesn't look half bad. It is worth noting that Android/iOS/web client also need to support whatever you are implementing, which may makes things a lot trickier. Also: Implementing anything on top of `main` right now is not a good idea. I have been working on the `user-account` branch for over a month now, so it may be a good idea to re-base (re-implement) on top of that.

BreizhHardware commented

2026-05-07 00:24:21 +02:00

Author

Owner

@ngerstle commented on GitHub (Feb 5, 2023):

On reflection, as long as the topic and operation are easily extracted from the request in a generic fashion, perhaps handling authorization external to ntfy is simpler.

It seems as though ("Publish as JSON" aside), the topic is always in the url; and the action (publish/subscribe) can be determined by http method (and url, in the case of webhooks)- if this is the case, then rules in a reverse proxy can handle a fair bit of the work, with significant flexibility (mTLS + OPA, client support aside).

It seems like there's quite a bit of work in the user-account branch, and while I see work towards token based auth, the change is significant enough that I think I'll defer future work on https://github.com/binwiederhier/ntfy/pull/602 until you've completed the user-account work.

@ngerstle commented on GitHub (Feb 5, 2023): On reflection, as long as the topic and operation are easily extracted from the request in a generic fashion, perhaps handling authorization external to ntfy is simpler. It seems as though ("Publish as JSON" aside), the topic is always in the url; and the action (publish/subscribe) can be determined by http method (and url, in the case of webhooks)- if this is the case, then rules in a reverse proxy can handle a fair bit of the work, with significant flexibility (mTLS + OPA, client support aside). It seems like there's quite a bit of work in the `user-account` branch, and while I see work towards token based auth, the change is significant enough that I think I'll defer future work on https://github.com/binwiederhier/ntfy/pull/602 until you've completed the `user-account` work.

BreizhHardware commented

2026-05-07 00:24:21 +02:00

Author

Owner

@binwiederhier commented on GitHub (Feb 8, 2023):

I do think the user-account branch is very close to completeness. Structurally nothing big will change. But if you'd like to wait a few days until I merge I understand.

I do not think that handling authorization should be done outside of ntfy. authn is easy to outsource to another app, but authz is really really bound to an application usually, because it depends on resources (topics).

@binwiederhier commented on GitHub (Feb 8, 2023): I do think the `user-account` branch is very close to completeness. Structurally nothing big will change. But if you'd like to wait a few days until I merge I understand. I do not think that handling authorization should be done outside of ntfy. authn is easy to outsource to another app, but authz is really really bound to an application usually, because it depends on resources (topics).

BreizhHardware commented

2026-05-07 00:24:21 +02:00

Author

Owner

@binwiederhier commented on GitHub (Feb 23, 2023):

FYI the user-account branch is merged.

@binwiederhier commented on GitHub (Feb 23, 2023): FYI the user-account branch is merged.

BreizhHardware commented

2026-05-07 00:24:21 +02:00

Author

Owner

@helmut72 commented on GitHub (Nov 3, 2024):

FYI the user-account branch is merged.

Is there any documentation? I don't find anything from:
https://github.com/binwiederhier/ntfy/pull/602

@helmut72 commented on GitHub (Nov 3, 2024): > FYI the user-account branch is merged. Is there any documentation? I don't find anything from: https://github.com/binwiederhier/ntfy/pull/602

BreizhHardware commented

2026-05-07 00:24:22 +02:00

Author

Owner

@vic1707 commented on GitHub (Sep 14, 2025):

@helmut72 hi, were you able to find any?

@vic1707 commented on GitHub (Sep 14, 2025): @helmut72 hi, were you able to find any?

BreizhHardware commented

2026-05-07 00:24:22 +02:00

Author

Owner

@binwiederhier commented on GitHub (Jan 11, 2026):

I believe this is the branch that we were discussing: https://github.com/binwiederhier/ntfy/pull/812

I think this would help people a lot, so I'll try to do this next time I work on the server.

@binwiederhier commented on GitHub (Jan 11, 2026): I believe this is the branch that we were discussing: https://github.com/binwiederhier/ntfy/pull/812 I think this would help people a lot, so I'll try to do this next time I work on the server.

BreizhHardware commented

2026-05-07 00:24:22 +02:00

Author

Owner

@binwiederhier commented on GitHub (Jan 31, 2026):

I've tried to implement this and I have parts of it working nicely. I have a "auth-user-header" config option and the web app mostly works with it (ntfy behind Authelia). The API is also fine with it, but it just came to me that I have no clue how the Android app would handle this setup.

I know lots of people want this, but the design is not clear to me.

@binwiederhier commented on GitHub (Jan 31, 2026): I've tried to implement this and I have parts of it working nicely. I have a "auth-user-header" config option and the web app mostly works with it (ntfy behind Authelia). The API is also fine with it, but it just came to me that I have no clue how the Android app would handle this setup. I know lots of people want this, but the design is not clear to me.

BreizhHardware commented

2026-05-07 00:24:22 +02:00

Author

Owner

@binwiederhier commented on GitHub (Feb 1, 2026):

Please see the current PR here: https://github.com/binwiederhier/ntfy/pull/1579

❗ ❗ I do not know how to resolve the "Android app" problem, so I will (for now) abandon this work until somebody chimes in with smart comments, or I have an epiphany. :-D Help is appreciated.

@binwiederhier commented on GitHub (Feb 1, 2026): Please see the current PR here: https://github.com/binwiederhier/ntfy/pull/1579 ❗ ❗ I do not know how to resolve the "Android app" problem, so I will (for now) abandon this work until somebody chimes in with smart comments, or I have an epiphany. :-D Help is appreciated.

BreizhHardware commented

2026-05-07 00:24:22 +02:00

Author

Owner

@JoeJoeTV commented on GitHub (Feb 1, 2026):

❗ ❗ I do not know how to resolve the "Android app" problem, so I will (for now) abandon this work until somebody chimes in with smart comments, or I have an epiphany. :-D Help is appreciated.

Not sure if the Android App currently supports this, but one idea would be to use access tokens.
Usually, if interacting with an API, one is not in a browser environment, so e.g. the Authelia login page can't be displayed. In that scenario, one might still want to use the API outside of a browser, so an access token can be created while logged in, which can then be used to access the API with authelitcation.
This could also be used for the android app and would also maybe make it easier to revoke access from android clients by just deleting the token in the web interface or from the CLI.

Just my two cents.

@JoeJoeTV commented on GitHub (Feb 1, 2026): > ❗ ❗ I do not know how to resolve the "Android app" problem, so I will (for now) abandon this work until somebody chimes in with smart comments, or I have an epiphany. :-D Help is appreciated. Not sure if the Android App currently supports this, but one idea would be to use access tokens. Usually, if interacting with an API, one is not in a browser environment, so e.g. the Authelia login page can't be displayed. In that scenario, one might still want to use the API outside of a browser, so an access token can be created while logged in, which can then be used to access the API with authelitcation. This could also be used for the android app and would also maybe make it easier to revoke access from android clients by just deleting the token in the web interface or from the CLI. Just my two cents.

BreizhHardware commented

2026-05-07 00:24:22 +02:00

Author

Owner

@JoeJoeTV commented on GitHub (Feb 1, 2026):

❗ ❗ I do not know how to resolve the "Android app" problem, so I will (for now) abandon this work until somebody chimes in with smart comments, or I have an epiphany. :-D Help is appreciated.

Another idea would be to integrate this token generation into the app, so if the instale is e.g. protected by e.g. Authelia, the app opens the browser, such that the user can log in and is redirected to some endpoint that generates a token and redirects to an app link, which is then handled by the ntfy app to store the generated token locally for accessing the API.

I think this is how this kind of integration is usually done, where a user wants to login to an remote service from an app. The app redirects to login page and that somehow sends the token that was generated after login back to the app so it can use it afterwards.

@JoeJoeTV commented on GitHub (Feb 1, 2026): > ❗ ❗ I do not know how to resolve the "Android app" problem, so I will (for now) abandon this work until somebody chimes in with smart comments, or I have an epiphany. :-D Help is appreciated. Another idea would be to integrate this token generation into the app, so if the instale is e.g. protected by e.g. Authelia, the app opens the browser, such that the user can log in and is redirected to some endpoint that generates a token and redirects to an app link, which is then handled by the ntfy app to store the generated token locally for accessing the API. I think this is how this kind of integration is usually done, where a user wants to login to an remote service from an app. The app redirects to login page and that somehow sends the token that was generated after login back to the app so it can use it afterwards.

BreizhHardware commented

2026-05-07 00:24:22 +02:00

Author

Owner

@ser commented on GitHub (Feb 1, 2026):

An ideal solution would be simply OpenID

@ser commented on GitHub (Feb 1, 2026): An ideal solution would be simply OpenID

BreizhHardware commented

2026-05-07 00:24:23 +02:00

Author

Owner

@ser commented on GitHub (Feb 1, 2026):

An ideal solution would be simply OpenID

@ser commented on GitHub (Feb 1, 2026): An ideal solution would be simply OpenID

BreizhHardware commented

2026-05-07 00:24:23 +02:00

Author

Owner

@KucharczykL commented on GitHub (May 4, 2026):

From my limited experience, OIDC should indeed solve this. For example Authentik will pull up a login page and then communicate with the app to authenticate the user. I am not an expert but I use header authentication where there is no other option but it seems it's not very suitable for more complex use cases (I would count mobile apps into this).

Maybe a good in-between would be to provide the header with the caveat that only web is supported and work on OIDC for all the other use cases.

@KucharczykL commented on GitHub (May 4, 2026): From my limited experience, OIDC should indeed solve this. For example Authentik will pull up a login page and then communicate with the app to authenticate the user. I am not an expert but I use header authentication where there is no other option but it seems it's not very suitable for more complex use cases (I would count mobile apps into this). Maybe a good in-between would be to provide the header with the caveat that only web is supported and work on OIDC for all the other use cases.

BreizhHardware referenced this issue

2026-05-07 01:01:29 +02:00

[PR #456] [MERGED] Add ansible-ntfy to Ansible section #1309

Rows
Columns

[GH-ISSUE #601] Authentication: match username from configurable header #456