Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,9 @@ jobs:
run: docker compose -f docker/docker-compose.yml config --quiet

- name: Validate release compose file
run: docker compose -f deploy/docker-compose.yml config --quiet
run: |
docker compose -f deploy/docker-compose.yml config --quiet
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.docker-proxy.yml config --quiet

- name: Build images
run: docker compose -f docker/docker-compose.yml build
Expand Down
11 changes: 10 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ name: Release image

on:
push:
tags: ['v*.*.*']
# Final releases (v2.0.0) and prereleases (v2.1.0-rc.1); prereleases never move latest.
tags: ['v[0-9]+.[0-9]+.[0-9]+', 'v[0-9]+.[0-9]+.[0-9]+-*']

permissions: {}

Expand Down Expand Up @@ -41,6 +42,14 @@ jobs:
org.opencontainers.image.description=Telegram authentication with forward auth and OpenID Connect
org.opencontainers.image.licenses=Apache-2.0
org.opencontainers.image.version=${{ steps.image.outputs.version }}
- name: Require a semver tag
env:
TAGS: ${{ steps.meta.outputs.tags }}
run: |
if [ -z "$TAGS" ]; then
echo "::error::${GITHUB_REF_NAME} is not a semver tag (vMAJOR.MINOR.PATCH[-PRERELEASE])"
exit 1
fi
- uses: docker/build-push-action@v6
with:
context: .
Expand Down
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,23 +38,24 @@ For a pre-release walkthrough, build it locally first:
4. Invite yourself (works with both open and closed registration):

```bash
docker compose -f deploy/docker-compose.yml exec api python -m src.admin user invite alice
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin user invite alice
```

The hosted `/login` page signs in existing users; it has no registration control.
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.
5. Register and authorize the first app:

```bash
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app add myapp --name "My App"
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app allow myapp alice
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app add myapp --name "My App"
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app allow myapp alice
```

For a sibling app, register its actual origin too:

```bash
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app origin add myapp https://app.example.com
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app origin add myapp https://app.example.com
```

6. Paste the nginx, Traefik or Caddy protection snippet from
Expand Down
38 changes: 19 additions & 19 deletions docs/INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,17 +20,17 @@ root. Developers using `docker/` substitute `docker/docker-compose.yml` for that
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 api python -m src.admin user invite alice`.
`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.
2. Register your app on the server:
```sh
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app add myapp --name 'My App'
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app allow myapp alice
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app add myapp --name 'My App'
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app allow myapp alice
```
Default policy is `allowlist`; each username must already exist and be linked to Telegram.
To allow every registered, linked user instead:
```sh
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app policy myapp all
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app policy myapp all
```
3. Choose a deployment shape:

Expand All @@ -41,7 +41,7 @@ root. Developers using `docker/` substitute `docker/docker-compose.yml` for that

In the sibling shape, restart API and bot with the updated settings, then run:
```sh
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app origin add myapp https://app.example.com
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app origin add myapp https://app.example.com
```
The origin must receive the configured cookie. Origins have no path, query or fragment. HTTPS
is required except localhost/127.0.0.1 development. Cookie domains must be a non-public parent
Expand Down Expand Up @@ -184,8 +184,8 @@ preserves header-removal-before-auth ordering, then `copy_headers` supplies the

## Operator CLI

Run `docker compose -f deploy/docker-compose.yml exec api python -m src.admin --help`.
Prefix the subcommands below with `docker compose -f deploy/docker-compose.yml exec api python -m src.admin`.
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.

Expand All @@ -212,8 +212,8 @@ The operator trusts every registered app; there is no consent screen.
1. Register a confidential client and its exact callback URL:

```sh
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app add myapp --name "My App" --redirect-uri https://app.example.com/callback
docker compose -f deploy/docker-compose.yml exec api python -m src.admin app allow myapp alice
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app add myapp --name "My App" --redirect-uri https://app.example.com/callback
docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app allow myapp alice
```

Save the printed client secret: it is shown once and only its SHA-256 hash is stored.
Expand Down Expand Up @@ -254,6 +254,16 @@ The operator trusts every registered app; there is no consent screen.
)
```

### Running the Authlib example behind a proxy

Set `APP_ORIGIN` to the app's external origin (`scheme://host[:port]`, no path or
trailing slash), for example `https://app.example.com`. Logout compares the browser
Origin against this value; when unset it uses the origin part of `request.base_url`.
Behind a trusted reverse proxy, start uvicorn with `--proxy-headers
--forwarded-allow-ips <trusted-proxy-addresses>` so callback URLs use the external
scheme. Configure the proxy to preserve the external Host and set forwarded headers.
Never trust forwarded headers from arbitrary public callers.

The stable UUID `sub` identifies the user. `profile` adds `preferred_username` and `name`.
ID tokens are signed with RS256 and a public key from `/jwks.json`; access tokens are opaque,
last 10 minutes by default, and work only at `/userinfo`. Raw API HS256 tokens and OIDC tokens
Expand Down Expand Up @@ -281,13 +291,3 @@ 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.

### Running the Authlib example behind a proxy

Set `APP_ORIGIN` to the app's external origin (`scheme://host[:port]`, no path or
trailing slash), for example `https://app.example.com`. Logout compares the browser
Origin against this value; when unset it uses the origin part of `request.base_url`.
Behind a trusted reverse proxy, start uvicorn with `--proxy-headers
--forwarded-allow-ips <trusted-proxy-addresses>` so callback URLs use the external
scheme. Configure the proxy to preserve the external Host and set forwarded headers.
Never trust forwarded headers from arbitrary public callers.
Loading