From 4e54dfb3b88884ed2b7d8e66379f9ac178ffcc5f Mon Sep 17 00:00:00 2001 From: root Date: Fri, 23 Oct 2026 14:55:15 +0000 Subject: [PATCH] Clarify docs: name integration modes, link the guide from the README Found while integrating the first real app (live bot test): - Rename "Mode 1/Mode 2" to "OpenID Connect"/"Forward auth" and order the guide's sections accordingly. - README: add a documentation map pointing to the integration guide; drop the outdated pre-release image note. - Explain that `user invite` only prints a Telegram link to open, that TeleLogin usernames need not match Telegram usernames, and that the bot must be dedicated to TeleLogin. - nginx: how to use an existing server block and protect several apps. Co-Authored-By: Claude Opus 5.5 --- README.md | 36 +++++++++++------ docs/INTEGRATION.md | 99 +++++++++++++++++++++++++++++---------------- 2 files changed, 89 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index e538d69..4dc9190 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,27 @@ # TeleLogin TeleLogin provides Telegram-confirmed login through a self-hosted bot. Protect apps with -Mode 2 forward auth through nginx, Traefik or Caddy, connect standard clients with Mode 1 -OpenID Connect, or build a custom UI with the raw API. Shared browser sessions and per-app -access policies let connected apps reuse one Telegram confirmation. Python 3.11+. +forward auth through nginx, Traefik or Caddy, connect standard clients with OpenID Connect, +or build a custom UI with the raw API. Shared browser sessions and per-app access policies +let connected apps reuse one Telegram confirmation. Python 3.11+. + +| I want to... | Read | +| --- | --- | +| Install the TeleLogin server | [Quick start](#quick-start) below | +| Protect an app or connect it to TeleLogin | **[Integration guide](docs/INTEGRATION.md)**: which mode to choose, proxy examples, OIDC | +| Manage users and apps | [Operator CLI](docs/INTEGRATION.md#operator-cli) | +| Build a custom login UI | [API](#api) and the [JavaScript client](examples/js_client/) | +| Upgrade from 1.x | [Upgrading from 1.x](#upgrading-from-1x) | ## Quick start Run these commands from the root of this checkout with Docker Compose v2 installed. -The release image below becomes available when the maintainer publishes 2.0.0. -For a pre-release walkthrough, build it locally first: -`docker build -f docker/Dockerfile -t ghcr.io/downlevel/telelogin:2.0.0 .`. +They install the server; connecting your app is covered in the +[integration guide](docs/INTEGRATION.md). -1. Create a Telegram bot with **@BotFather**. Save its token and username (without `@`). +1. Create a Telegram bot with **@BotFather** and dedicate it to TeleLogin: TeleLogin polls it + for updates, so do not reuse a bot that another program reads. Save its token and + username (without `@`). 2. Generate the two server secrets: ```bash @@ -43,8 +52,11 @@ For a pre-release walkthrough, build it locally first: Admin commands run as the application user (`--user 10001`) so that SQLite files in the data volume stay owned by it. The hosted `/login` page signs in existing users; it has no registration control. - Open the printed link and press Start in Telegram. Replace `alice` consistently with - your chosen username in these commands. + The command sends no Telegram message: it prints a single-use `https://t.me/...` link, + valid for 30 minutes. Open it in Telegram and press **Start** to link your account. + `alice` is your TeleLogin username, used on the login page; it need not match your Telegram + username. Replace it consistently in these commands. `user list` shows a numeric + `telegram_id` once linked; if the link expired, run `user remove alice` and invite again. 5. Register and authorize the first app: ```bash @@ -59,7 +71,7 @@ For a pre-release walkthrough, build it locally first: ``` 6. Paste the nginx, Traefik or Caddy protection snippet from - [the integration guide](docs/INTEGRATION.md), using app id `myapp` and your actual + [the integration guide](docs/INTEGRATION.md#forward-auth), using app id `myapp` and your actual hostnames/upstream. Host proxy → `127.0.0.1:8000` (replace `8000` with `API_PORT`); proxy in Docker → `telelogin:8000` after joining the TeleLogin Compose network (`deploy_telelogin_network` by default). For Docker, start with the [port-removal override and network setup](docs/INTEGRATION.md#docker-proxy-networking): @@ -72,7 +84,7 @@ For a pre-release walkthrough, build it locally first: For an optional OIDC app, use `app add` with `--redirect-uri` and configure the printed client secret, discovery URL and `openid profile` scopes as described in -[Mode 1](docs/INTEGRATION.md#mode-1-openid-connect). +[OpenID Connect](docs/INTEGRATION.md#openid-connect). ## Upgrading from 1.x @@ -433,5 +445,5 @@ for the full terms. ## OpenID Connect integration TeleLogin supports confidential OIDC clients with authorization code flow, PKCE S256, RS256 ID -tokens, and shared browser SSO. See [the integration guide](docs/INTEGRATION.md#mode-1-openid-connect) +tokens, and shared browser SSO. See [the integration guide](docs/INTEGRATION.md#openid-connect) and [the Authlib example](examples/oidc_fastapi/app.py). diff --git a/docs/INTEGRATION.md b/docs/INTEGRATION.md index 9320ff1..eca1d2a 100644 --- a/docs/INTEGRATION.md +++ b/docs/INTEGRATION.md @@ -8,20 +8,36 @@ One Telegram confirmation creates a browser session lasting `REFRESH_TOKEN_TTL_D | Mode | Use when | Integration | | --- | --- | --- | -| Forward auth (Mode 2) | Your app shares TeleLogin's origin or a trusted parent domain | Reverse proxy configuration; no app login code | -| OpenID Connect (Mode 1) | An app uses a standard OIDC library or an unrelated domain | Confidential clients; standard OIDC library | -| Raw API | You need a custom login UI and token lifecycle | Existing `/register` and `/auth/*` API, [README](../README.md) | +| [Forward auth](#forward-auth) | Your app shares TeleLogin's origin or a trusted parent domain | Reverse proxy configuration; no app login code | +| [OpenID Connect](#openid-connect) | An app uses a standard OIDC library or an unrelated domain | Confidential clients; standard OIDC library | +| [Raw API](#advanced-custom-ui-with-the-raw-api) | You need a custom login UI and token lifecycle | Existing `/register` and `/auth/*` API, [README](../README.md) | + +Most apps behind your own reverse proxy want forward auth: it needs no code in the app. All Compose commands below use the release installation in `deploy/`, run from the checkout root. Developers using `docker/` substitute `docker/docker-compose.yml` for that path. -## Mode 2: forward auth +## Before you start + +- The TeleLogin server is running as described in the [README quick start](../README.md#quick-start), + with a bot dedicated to TeleLogin. TeleLogin polls that bot for updates, so do not share its + token with another program that also reads updates. +- Usernames are TeleLogin's own, chosen when the user is invited or registers. They need not + match the Telegram username: the account is linked to whichever Telegram account presses + Start on the registration link. +- `user invite USERNAME` sends nothing by itself. It prints a `https://t.me/?start=...` + link: open it in Telegram and press **Start**. The link is single-use and expires after + `REGISTRATION_TOKEN_TTL_SECONDS` (30 minutes by default); to issue a new one, run + `user remove USERNAME` then `user invite USERNAME`. `user list` shows a numeric + `telegram_id` once the account is linked. + +## Forward auth 1. Configure `PUBLIC_URL` to the externally visible TeleLogin base URL, without a trailing slash. - Set up your bot and API as described in the README. Register a user via `POST /register` and - follow the returned Telegram link, or invite one with - `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin user invite alice`. - With `REGISTRATION_MODE=closed`, only CLI invitations create users. + Create users with `POST /register` (follow the returned Telegram link) or with + `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin user invite alice` + (see [Before you start](#before-you-start)). With `REGISTRATION_MODE=closed`, only CLI + invitations create users. 2. Register your app on the server: ```sh docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app add myapp --name 'My App' @@ -123,6 +139,21 @@ For a shared host, copy [telelogin.conf](../examples/nginx/telelogin.conf) and [prefix server](../examples/nginx/prefix.conf). For sibling subdomains use [subdomain.conf](../examples/nginx/subdomain.conf) and the same `protect-app.conf`. The app id is `set $telelogin_app myapp` in the protection snippet, included inside the app location. +If your HTTPS `server` block already exists, do not add a new one: add +`include /etc/nginx/telelogin.conf;` at its server scope and the protection include inside each +app location. To protect several apps with one snippet, delete the `set` line from +`protect-app.conf` and set the id in each location before the include: + +```nginx +location ^~ /app1/ { + set $telelogin_app app1; + include /etc/nginx/protect-app.conf; + proxy_pass http://127.0.0.1:9001/; +} +``` + +Remove any other access control the location had (basic auth, token checks) once TeleLogin +protects it. Install your own TLS certificate/key at the paths shown in the server blocks. The app upstream placeholder is `127.0.0.1:9000`. nginx uses `auth_request`: 401 becomes a 302 via `X-TeleLogin-Login` and a named location. @@ -163,7 +194,7 @@ preserves header-removal-before-auth ordering, then `copy_headers` supplies the some WSGI servers) treat `_` and `-` as the same header name. - `SSO_COOKIE_DOMAIN` shares the browser credential with **every subdomain** of that domain. Use it only when all subdomains are trusted. A registered app origin controls redirects; it - does not isolate cookies. Unrelated domains require Mode 1. + does not isolate cookies. Unrelated domains require [OpenID Connect](#openid-connect). - Keep `SSO_COOKIE_SECURE=true` for HTTPS. Set false only for plain HTTP local development. Cookies are HttpOnly, SameSite=Lax, Path=/; empty domain means host-only. Browser POST endpoints require JSON (logout also accepts form data) and reject an Origin other than `PUBLIC_URL`'s @@ -182,31 +213,9 @@ preserves header-removal-before-auth ordering, then `copy_headers` supplies the `/auth/logout-all` revokes both kinds. Unlink/delete removes the account, sessions and allowlist memberships. Return URLs are app-scoped and default to `PUBLIC_URL/` if invalid. -## Operator CLI +## OpenID Connect -Run `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin --help`. -Prefix the subcommands below with `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin`. -Shell access is admin access. `gen-secrets` needs no `.env` or database and prints random -`SECRET_KEY` and `INTERNAL_API_KEY` assignments. Never share them. - -```text -app add ID --name NAME [--policy allowlist|all] [--redirect-uri URI ...] -app list | app show ID | app remove ID -app policy ID allowlist|all -app allow ID USERNAME | app disallow ID USERNAME -app origin add|remove ID ORIGIN -app redirect-uri add|remove ID URI -app rotate-secret ID -user invite USERNAME | user list | user remove USERNAME -gen-secrets -``` - -`user invite` prints a one-use expiring Telegram link; `user remove` has the same deletion cascade -as unlink. `app remove` also removes its allowlist. No stored secret is printed. - -## Mode 1: OpenID Connect - -Use Mode 1 for apps on unrelated domains or apps with a standard OIDC client library. +Use OpenID Connect for apps on unrelated domains or apps with a standard OIDC client library. The operator trusts every registered app; there is no consent screen. 1. Register a confidential client and its exact callback URL: @@ -271,7 +280,7 @@ are mutually unusable. Codes are single use; replay revokes the access tokens is code. Removing app access also prevents `/userinfo` and code redemption. Only confidential clients with a backend and a secret are supported. Browser-only SPAs should -use Mode 2 or a small backend. There are no OIDC refresh tokens, dynamic registration, consent +use forward auth or a small backend. There are no OIDC refresh tokens, dynamic registration, consent screens, RP-initiated logout, or back-channel logout. `max_age`, `claims`, and `ui_locales` are unsupported and ignored. `prompt=none` fails with `login_required` without a browser session; `prompt=login` forces a new Telegram confirmation. Otherwise the browser session is reused. @@ -291,3 +300,25 @@ The existing `/register`, `/auth/*`, `/internal/*` and JavaScript client retain See the [API documentation and JS client](../README.md). Raw API clients own their login page, number-matching polling, token storage/rotation and logout. Browser SSO cookies cannot be used as API refresh tokens, and API tokens cannot authorize forward-auth requests. + +## Operator CLI + +Run `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin --help`. +Prefix the subcommands below with `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin`. +Shell access is admin access. `gen-secrets` needs no `.env` or database and prints random +`SECRET_KEY` and `INTERNAL_API_KEY` assignments. Never share them. + +```text +app add ID --name NAME [--policy allowlist|all] [--redirect-uri URI ...] +app list | app show ID | app remove ID +app policy ID allowlist|all +app allow ID USERNAME | app disallow ID USERNAME +app origin add|remove ID ORIGIN +app redirect-uri add|remove ID URI +app rotate-secret ID +user invite USERNAME | user list | user remove USERNAME +gen-secrets +``` + +`user invite` prints a one-use expiring Telegram link; `user remove` has the same deletion cascade +as unlink. `app remove` also removes its allowlist. No stored secret is printed.