# Logto.io Authentication Setup Guide This guide explains how to configure [logto.io](https://logto.io) as an OIDC identity provider for TomoTree. **Why logto.io?** Logto is an open-source identity platform that aggregates many upstream sign-in methods (Google, GitHub, Apple ID, Microsoft, WeChat, and more) under a single OIDC endpoint. By pointing TomoTree at your logto tenant you can offer your users *all* the sign-in methods you have enabled in logto — without any extra code in TomoTree itself. --- ## Requirements - **Streamlit 1.42 or higher** (with built-in multi-provider OIDC support) - A **logto.io** account (cloud or self-hosted) - Access to the **TomoTree configuration** files --- ## Step 1: Create a Logto Application ### 1a. Sign in to logto - **Cloud**: Go to [https://cloud.logto.io](https://cloud.logto.io) and sign in. - **Self-hosted**: Open your logto admin console (e.g., `http://localhost:3002`). ### 1b. Create a "Traditional web" application 1. In the left sidebar, click **Applications**. 2. Click **+ Create application**. 3. Choose **Traditional web** as the framework type. 4. Enter a name (e.g., `TomoTree`) and click **Create application**. ### 1c. Note the credentials After creation you will see the application details page. Copy: - **App ID** — you will use this as `client_id` - **App secret** — you will use this as `client_secret` ### 1d. Add Redirect URIs In the **Redirect URIs** section, add: - For **local development**: `http://localhost:8501/oauth2callback` - For **production**: `https://your-domain.com/oauth2callback` Click **Save changes**. --- ## Step 2: Enable Sign-in Connectors (optional but recommended) Logto.io can aggregate external identity providers (Google, GitHub, Apple ID, etc.). 1. In the left sidebar, click **Connectors**. 2. Click **+ Add connector** and choose the providers you want (e.g., Google, GitHub). 3. Follow the on-screen instructions for each connector — they typically require you to create OAuth credentials in the provider's developer console and paste them into logto. Once enabled, users who sign in via logto will see all the configured providers on the logto sign-in page. TomoTree accepts only users whose e-mail address logto reports as verified (`email_verified`). Sign in once through every connector (e.g. GitHub, Facebook) and check the log line `OIDC login accepted: provider=logto email_verified=True`; see Troubleshooting if a connector is refused. --- ## Step 3: Configure Streamlit Secrets ### 3a. Create or edit `~/.streamlit/secrets.toml` On **Linux/macOS**: ```bash mkdir -p ~/.streamlit nano ~/.streamlit/secrets.toml ``` On **Windows (PowerShell)**: ```powershell mkdir -Path $env:USERPROFILE\.streamlit -Force notepad $env:USERPROFILE\.streamlit\secrets.toml ``` ### 3b. Add logto credentials #### Option A — logto as the only OIDC provider (simplest) ```toml [auth] redirect_uri = "http://localhost:8501/oauth2callback" cookie_secret = "Your cookie" [auth.logto] client_id = "" client_secret = "" server_metadata_url = "https://.logto.app/oidc/.well-known/openid-configuration" [auth.logto.client_kwargs] prompt = "login" ``` Replace: - `YOUR_LOGTO_APP_ID` / `YOUR_LOGTO_APP_SECRET` — values from Step 1c - `` — your logto cloud tenant ID (visible in the console URL) - `redirect_uri` — must match the URI added in Step 1d - `cookie_secret` — any random string #### Option B — logto alongside Google OAuth (multi-provider) If you want to offer *both* Google OAuth and logto.io simultaneously: ```toml [auth] redirect_uri = "http://localhost:8501/oauth2callback" cookie_secret = "..." [auth.google] client_id = "" client_secret = "" server_metadata_url = "https://accounts.google.com/.well-known/openid-configuration" [auth.logto] client_id = "" client_secret = "" server_metadata_url = "https://.logto.app/oidc/.well-known/openid-configuration" [auth.logto.client_kwargs] prompt = "login" ``` In this mode TomoTree calls `st.login("google")` for Google and `st.login("logto")` for logto. ### 3c. Protect the file ```bash # Linux/macOS chmod 600 ~/.streamlit/secrets.toml ``` --- ## Step 4: Update TomoTree Configuration ### 4a. Copy the configuration template (if you haven't already) ```bash cp config/config.yaml.dist config/config.yaml cp config/login.yaml.dist config/login.yaml ``` ### 4b. Enable logto.io in `config/config.yaml` Add `logto` to `oidc_providers` (the name must match the section `[auth.logto]` in `secrets.toml`): ```yaml oidc_providers: logto: label: Logto.io # optional, text on the login button (default: the name) icon: "🪪" # optional (default: 🔑) ``` ### 4c. Define role mappings (optional) Users are identified by their **email address** as returned by logto. You can assign application roles based on email: ```yaml oidc_providers: logto: label: Logto.io roles: admin@example.com: [admin, developer, user] reviewer@example.com: [developer, user] viewer@example.com: [user] # Any email not listed gets the default "user" role (comparison is case-insensitive) ``` ### 4d. Keep only the methods you want active Only the providers listed in `oidc_providers` appear as login buttons, in the order given there (the first one is highlighted); password login (`login_file`) is in a collapsed panel below them. Remove a provider from the list to hide it; users logged in through a removed provider are logged out. ```yaml oidc_providers: logto: label: Logto.io google: # remove to hide the Google button label: Google ``` --- ## Step 5: Run TomoTree ```bash streamlit run app.py # or make www ``` Open `http://localhost:8501` in your browser. You should see the button **Login with Logto.io** on the login screen. Clicking **Login with Logto.io** redirects you to logto's hosted sign-in page where users can choose their preferred identity provider. --- ## Troubleshooting ### Logto.io is not offered on the login screen **Solution:** List `logto` in `oidc_providers` in `config/config.yaml` and restart. `make check-config` warns about the removed keys `authenticated_by_logto` and `logto_roles` and points to `oidc_providers`. ### Redirect URI mismatch **Solution:** Make sure the redirect URI in `secrets.toml` matches the one registered in the logto application settings (Step 1d). For production, use the public URL of your Streamlit deployment: `https://your-domain.com/oauth2callback` ### `KeyError: 'logto'` or similar Streamlit error **Solution:** This usually means `secrets.toml` does not have an `[auth.logto]` section (TomoTree calls `st.login("logto")`, which needs it). See Step 3b above. ### Login works but user has no roles **Solution:** Users not listed in `roles` of the `logto` provider automatically get the `user` role. To grant higher privileges, add the user's email to `roles` of `logto` in `oidc_providers` in `config.yaml` and restart. ### Login is refused: e-mail address not verified TomoTree identifies an OIDC user by the e-mail address, so it accepts a login only if the provider sends the claim `email_verified = true`. Otherwise anyone who registers someone else's address at the provider would get that user's data and roles. A refused login is logged as `OIDC login refused: provider=... reason=email_not_verified email_verified=...`; every accepted login logs `email_verified` too. **Solution:** Let the user verify the address at the provider (or the connected social account), or require e-mail verification in the provider's settings. Set `trust_email: true` for the provider in `oidc_providers` only if the provider verifies every address itself but does not send the claim; the installation check then shows a warning. ### Logout ends with an error page of the provider **Solution:** Add `http://localhost:8501/oauth2callback` (the `redirect_uri`, or your production address) to the post-logout redirect URIs of the application in the logto console: Streamlit sends it as `post_logout_redirect_uri` on logout. More OIDC problems and console messages: [installation guide, Troubleshooting OIDC login](installation.md#troubleshooting-oidc-login). --- ## Security Best Practices 1. **Never commit credentials** — keep `~/.streamlit/secrets.toml` out of version control. 2. **Keep `secrets.toml` out of the image in production** — mount it at runtime (see below); Streamlit does not read the `[auth]` configuration from environment variables. 3. **Restrict redirect URIs** — only list your actual domains in logto's application settings. 4. **Use HTTPS in production** — Streamlit's OAuth requires HTTPS for public deployments. 5. **Rotate secrets periodically** — regenerate the App secret in logto and update `secrets.toml` accordingly. --- ## Docker Deployment With `docker/compose.yml` put your `secrets.toml` (Option A or B from Step 3b) into the `.streamlit/` directory of the data directory (`TOMOTREE_DIR`); it is mounted to `/app/.streamlit/`. See [docker/README.md](../docker/README.md). --- ## Further Reading - [Logto documentation](https://docs.logto.io) - [Logto cloud console](https://cloud.logto.io) - [Streamlit OAuth/OIDC documentation](https://docs.streamlit.io/deploy/authentication) - [TomoTree Google OAuth guide](google_oauth_setup.md) - [TomoTree installation guide](installation.md)