matrix-tuwunel: add labels to expose the /_tuwunel API path

The /_tuwunel namespace carries Tuwunel's ad-hoc routes (server_version,
local_user_count) and its native OpenID Connect provider endpoints
(/_tuwunel/oidc/...), which a reverse proxy must route for OIDC login
to work. Add public (enabled by default, like the client API) and
internal Traefik label groups.

CHANGELOG.md

@@ -1,3 +1,14 @@
+# 2026-07-19
+
+## Tuwunel now exposes its administration and /_tuwunel API paths
+
+The [Tuwunel](docs/configuring-playbook-tuwunel.md) role previously routed only the `/_matrix` path through the reverse proxy. It now also exposes the two other API paths that Tuwunel serves.
+
+The Synapse-compatible administration API (`/_synapse/admin`) powers administration dashboards and moderation bots. As with Synapse and Dendrite, the playbook now exposes it automatically when such a tool is installed: publicly for [Ketesa](docs/configuring-playbook-ketesa.md) or [Element Admin](docs/configuring-playbook-element-admin.md), and on the internal entrypoint for [Draupnir](docs/configuring-playbook-bot-draupnir.md). To expose it yourself, set `matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: true` (or the `internal_` variant).
+
+Tuwunel also serves first-party routes under `/_tuwunel`, including its native OpenID Connect provider endpoints, which the reverse proxy must route for OIDC login to work. This path is now routed on the public entrypoint by default. To keep it off the public entrypoint, set `matrix_tuwunel_container_labels_public_tuwunel_api_enabled: false`.
+
+
 # 2026-07-18
 
 ## LiveKit Server port configuration must be unambiguous now

docs/configuring-playbook-tuwunel.md

@@ -180,6 +180,17 @@ When enabled, rooms with a valid `m.room.policy` state event have outgoing event
 
 The role sets `default_room_version: '12'`, so newly created rooms default to Matrix [room version 12](https://github.com/matrix-org/matrix-spec-proposals/pull/4289) ("Hydra"). Override `matrix_tuwunel_config_default_room_version` if you need an earlier version for client compatibility.
 
+### The `/_tuwunel` API path
+
+Besides `/_matrix`, Tuwunel serves its own first-party routes under `/_tuwunel`. This namespace carries ad-hoc endpoints such as `/_tuwunel/server_version` and `/_tuwunel/local_user_count`, and the [native OpenID Connect provider](https://matrix-construct.github.io/tuwunel/authentication/oidc-server.html) endpoints (`/_tuwunel/oidc/...`) that clients use when Tuwunel handles OIDC login itself, rather than delegating to an upstream provider as described above. The role routes `/_tuwunel` on the public entrypoint by default so these features work out of the box.
+
+To keep this namespace off the public entrypoint and expose it only on the internal one, set:
+
+```yaml
+matrix_tuwunel_container_labels_public_tuwunel_api_enabled: false
+matrix_tuwunel_container_labels_internal_tuwunel_api_enabled: true
+```
+
 ### Exposing the Administration API
 
 Tuwunel serves a Synapse-compatible Administration API under the `/_synapse/admin` path, so administration dashboards (such as synapse-admin and ketesa) and moderation bots (such as Draupnir and Meowlnir) work against it. The served endpoints are listed on the [Tuwunel Synapse Admin API page](https://matrix-construct.github.io/tuwunel/development/compliance/synapse-admin.html).

group_vars/matrix_servers

@@ -5829,6 +5829,7 @@ matrix_tuwunel_container_labels_public_federation_api_traefik_tls: "{{ matrix_fe
 
 matrix_tuwunel_container_labels_internal_client_api_enabled: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_enabled }}"
 matrix_tuwunel_container_labels_internal_client_api_traefik_entrypoints: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_name }}"
+matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_entrypoints: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_name }}"
 
 matrix_tuwunel_config_well_known_livekit_url: "{{ matrix_livekit_jwt_service_public_url if matrix_livekit_jwt_service_enabled else '' }}"
 

roles/custom/matrix-tuwunel/defaults/main.yml

@@ -106,6 +106,26 @@ matrix_tuwunel_container_labels_public_federation_api_traefik_entrypoints: ''
 matrix_tuwunel_container_labels_public_federation_api_traefik_tls: true
 matrix_tuwunel_container_labels_public_federation_api_traefik_tls_certResolver: "{{ matrix_tuwunel_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
 
+# Controls whether labels will be added that expose Tuwunel's first-party API (`/_tuwunel`) on a public Traefik entrypoint.
+# This namespace carries ad-hoc routes such as `/_tuwunel/server_version` and `/_tuwunel/local_user_count`, as well as the
+# native OpenID Connect provider endpoints (`/_tuwunel/oidc/...`) that clients use when Tuwunel performs OIDC login itself.
+# It is enabled by default because the reverse proxy must route it for those features to work.
+matrix_tuwunel_container_labels_public_tuwunel_api_enabled: true
+matrix_tuwunel_container_labels_public_tuwunel_api_traefik_hostname: "{{ matrix_tuwunel_hostname }}"
+matrix_tuwunel_container_labels_public_tuwunel_api_traefik_path_prefix: /_tuwunel
+matrix_tuwunel_container_labels_public_tuwunel_api_traefik_rule: "Host(`{{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_path_prefix }}`)"
+matrix_tuwunel_container_labels_public_tuwunel_api_traefik_priority: 0
+matrix_tuwunel_container_labels_public_tuwunel_api_traefik_entrypoints: "{{ matrix_tuwunel_container_labels_traefik_entrypoints }}"
+matrix_tuwunel_container_labels_public_tuwunel_api_traefik_tls: "{{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_entrypoints != 'web' }}"
+matrix_tuwunel_container_labels_public_tuwunel_api_traefik_tls_certResolver: "{{ matrix_tuwunel_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# Controls whether labels will be added that expose Tuwunel's first-party API (`/_tuwunel`) on the internal Traefik entrypoint.
+matrix_tuwunel_container_labels_internal_tuwunel_api_enabled: false
+matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_path_prefix: /_tuwunel
+matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_rule: "PathPrefix(`{{ matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_path_prefix }}`)"
+matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_priority: 0
+matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_entrypoints: ""
+
 # Controls whether labels will be added that expose the Synapse-compatible Administration API (`/_synapse/admin`) on a public Traefik entrypoint.
 # Tuwunel serves this API so that administration dashboards (synapse-admin, ketesa) and moderation bots (Draupnir, Meowlnir) work against it.
 # Every endpoint requires an administrator access token. It is disabled by default; you may prefer to expose it only on the internal entrypoint below.

roles/custom/matrix-tuwunel/templates/labels.j2

@@ -136,6 +136,59 @@ traefik.http.routers.matrix-tuwunel-public-federation-api.tls.certResolver={{ ma
 {% endif %}
 
 
+{% if matrix_tuwunel_container_labels_public_tuwunel_api_enabled %}
+############################################################
+#                                                          #
+# Public Tuwunel API (/_tuwunel)                           #
+#                                                          #
+############################################################
+
+traefik.http.routers.matrix-tuwunel-public-tuwunel-api.rule={{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_rule }}
+
+{% if matrix_tuwunel_container_labels_public_tuwunel_api_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-tuwunel-public-tuwunel-api.priority={{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_priority }}
+{% endif %}
+
+traefik.http.routers.matrix-tuwunel-public-tuwunel-api.service=matrix-tuwunel
+traefik.http.routers.matrix-tuwunel-public-tuwunel-api.entrypoints={{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_entrypoints }}
+
+traefik.http.routers.matrix-tuwunel-public-tuwunel-api.tls={{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_tls | to_json }}
+{% if matrix_tuwunel_container_labels_public_tuwunel_api_traefik_tls %}
+traefik.http.routers.matrix-tuwunel-public-tuwunel-api.tls.certResolver={{ matrix_tuwunel_container_labels_public_tuwunel_api_traefik_tls_certResolver }}
+{% endif %}
+
+############################################################
+#                                                          #
+# /Public Tuwunel API (/_tuwunel)                          #
+#                                                          #
+############################################################
+{% endif %}
+
+
+{% if matrix_tuwunel_container_labels_internal_tuwunel_api_enabled %}
+############################################################
+#                                                          #
+# Internal Tuwunel API (/_tuwunel)                         #
+#                                                          #
+############################################################
+
+traefik.http.routers.matrix-tuwunel-internal-tuwunel-api.rule={{ matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_rule }}
+
+{% if matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-tuwunel-internal-tuwunel-api.priority={{ matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_priority }}
+{% endif %}
+
+traefik.http.routers.matrix-tuwunel-internal-tuwunel-api.service=matrix-tuwunel
+traefik.http.routers.matrix-tuwunel-internal-tuwunel-api.entrypoints={{ matrix_tuwunel_container_labels_internal_tuwunel_api_traefik_entrypoints }}
+
+############################################################
+#                                                          #
+# /Internal Tuwunel API (/_tuwunel)                        #
+#                                                          #
+############################################################
+{% endif %}
+
+
 {% if matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled %}
 ############################################################
 #                                                          #