Enterprise Setup & SSO Guide

1. Architecture & network topology

A TheiaCast deployment has three moving parts:

• Server — three containers: an nginx frontend (serves the admin web app and proxies the API), the ASP.NET Core backend (REST API + WebSocket hub), and PostgreSQL.
• Admin browsers — staff open the web app over HTTPS. This is also where the SSO redirect lands.
• Display devices — Raspberry Pi, another Linux mini-PC (Intel NUC, etc.), Windows, or Android/Fire TV. Each runs a full (non-headless) Chromium client in kiosk mode that makes an outbound connection to the backend and holds a WebSocket open.

2. Enterprise prerequisites

Before you start, line these up:

3. Server install (summary)

The full step-by-step is in the Installation Guide. In short: install Docker, drop in a docker-compose.yml and .env, then docker compose up -d.

Minimum docker-compose.yml

services:
  postgres:
    image: postgres:15-alpine
    container_name: theiacast-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: theiacast
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  backend:
    image: ghcr.io/jimmyeao/theiacast-backend:latest
    container_name: theiacast-backend
    environment:
      - ConnectionStrings__Default=Host=postgres;Port=5432;Database=theiacast;Username=postgres;Password=${POSTGRES_PASSWORD}
      - ASPNETCORE_ENVIRONMENT=Production
      - Jwt__Secret=${JWT_SECRET}
    ports:
      - "5001:8080"
    depends_on: [postgres]
    volumes:
      - theiacast_media:/app/wwwroot
      - theiacast_dataprotection_keys:/app/dataprotection-keys
      - ${SSL_CERT_PATH:-./ssl-certs}:/app/ssl-certs
    restart: unless-stopped

  frontend:
    image: ghcr.io/jimmyeao/theiacast-frontend:latest
    container_name: theiacast-frontend
    ports:
      - "${HTTP_PORT:-80}:80"
      - "${HTTPS_PORT:-443}:443"
    volumes:
      - ${SSL_CERT_PATH:-./ssl-certs}:/etc/nginx/ssl:ro
    depends_on: [backend]
    restart: unless-stopped

volumes:
  postgres_data:
  theiacast_media:
  theiacast_dataprotection_keys:

.env

POSTGRES_PASSWORD=change-me-to-a-long-random-string
JWT_SECRET=another-long-random-string-at-least-32-chars
# Optional custom ports / cert path
# HTTP_PORT=80
# HTTPS_PORT=443
# SSL_CERT_PATH=./ssl-certs

Bring it up and check:

docker compose up -d
docker compose ps
docker compose logs -f backend

4. Hostname, HTTPS & reverse proxy

Decide the one URL staff will always use, for example https://signage.example.com. Everything downstream — SSO redirect URIs, bookmarks, device server URLs — keys off it. If people sometimes reach the app by IP and sometimes by name, SSO will fail for the mismatched one because the redirect URI will not be an exact match.

Option A — terminate TLS in the bundled frontend

Mount your certificate and key where the frontend container expects them and restart it:

# Files expected inside the container at /etc/nginx/ssl/
#   cert.pem   (full chain)
#   key.pem    (private key)
mkdir -p ~/theiacast/ssl-certs
cp fullchain.pem ~/theiacast/ssl-certs/cert.pem
cp privkey.pem   ~/theiacast/ssl-certs/key.pem
chmod 600 ~/theiacast/ssl-certs/key.pem
docker compose restart frontend
docker compose logs frontend | grep TheiaCast:   # expect: certificate found, serving HTTPS on 443

Option B — put your own reverse proxy in front

Common in companies that already run nginx / Traefik / Caddy / an F5. Point it at the frontend container and make sure WebSocket upgrades are passed through — the admin UI keeps a live socket open.

# nginx example
server {
    listen 443 ssl;
    server_name signage.example.com;

    ssl_certificate     /etc/letsencrypt/live/signage.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/signage.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:80;           # the frontend container
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;    # WebSocket
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 3600s;                  # keep long-lived sockets alive
    }
}

server {
    listen 80;
    server_name signage.example.com;
    return 301 https://$host$request_uri;
}

5. Authentication model

TheiaCast has three independent ways a person can sign in, and you can enable any combination:

• Local login — username + password held by TheiaCast, optionally with TOTP MFA. On by default.
• Microsoft Entra ID — native integration built for Entra / Microsoft 365 tenants.
• Generic OpenID Connect — any standards-compliant OIDC provider (Okta, Keycloak, and others).
• SAML 2.0 — SP-initiated Web-SSO for SAML-only identity providers (ADFS, legacy on-prem IdPs).

Roles

Every user has one role. The three built-in roles are:

Custom roles can also be created (Admin → Users & Roles). Any existing role name — built-in or custom — can be chosen as the default that SSO assigns to new accounts.

MFA

TheiaCast’s own MFA is authenticator-app TOTP, enrolled per account under the user menu. It is independent of any identity provider. Accounts created through SSO start without TheiaCast MFA — the expectation is that MFA is enforced at the identity provider, which is where those users actually authenticate.

API keys

Automation uses API keys (Admin → API Keys), not user logins. Keys are unaffected by SSO. See the API documentation.

6. Single Sign-On — how it works

TheiaCast supports three SSO methods: Microsoft Entra ID, generic OIDC, and SAML 2.0. The flow below covers Entra/OIDC (authorization code + PKCE, an ID token exchanged in the browser). SAML is a different, browser-level POST flow with no code exchange — see SAML 2.0 SSO for its own step-by-step. The user-resolution logic below (match by identity, then email, then auto-provision) and the anti-lockout rule apply identically to all three.

The flow (Entra ID / generic OIDC)

1. A user clicks Sign in with Microsoft or Sign in with <your provider> on the TheiaCast login page.
2. The browser is redirected to the identity provider using the authorization code flow with PKCE. By default TheiaCast is a public client with no client secret; for a confidential provider (e.g. Google Workspace) a secret can be stored server-side — see Confidential providers.
3. After the user authenticates (and passes any MFA / conditional-access policy), the provider redirects back to https://<your-host>/login with a one-time code.
4. That code is exchanged for an ID token — in the browser for a public client, or via the TheiaCast backend when a server-side client secret is configured — and the ID token is validated by the backend.
5. The backend fetches the provider’s signing keys from its discovery document and validates the ID token: signature, issuer, audience (= your client ID), and expiry.
6. On success the backend resolves the user (below) and issues its own TheiaCast session token. From then on the TheiaCast session is independent of the provider session.

Requested scopes are always openid profile email. The redirect URI is always the app origin plus /login — there is nothing to configure for it in TheiaCast, but it must be registeredexactly at the provider.

How a token becomes a TheiaCast user

On each SSO login the backend does, in order:

1. Match by external identity. If a TheiaCast user is already linked to this provider + this subject (oid for Entra, sub for OIDC, NameID for SAML), sign them in.
2. Otherwise link by email. If a user already exists with the same email address, that account is linked to the external identity and used from then on. This is how you connect your existing local admin account to SSO — just make sure the email matches.
3. Otherwise auto-provision. A new user is created with the configured default role and a username taken from the token’s name (or the email prefix), with a provider suffix if that name is already taken.

The anti-lockout rule

At least one authentication method must always be enabled. You can only turn off local login once Microsoft Entra ID, generic OIDC, or SAML is enabled and fully configured (client ID plus tenant/issuer for Entra/OIDC; IdP entity ID, SSO URL and certificate for SAML). TheiaCast rejects the change otherwise, so you cannot accidentally lock everyone out.

Recommended rollout: keep local login on, get SSO working end-to-end for a real user, promote that user to Admin, then — if you want SSO-only — disable local login.

7. Microsoft Entra ID SSO

Use this path for Microsoft 365 / Entra ID tenants. It is a single-tenant integration: TheiaCast validates tokens against your tenant specifically.

Part A — Create the app registration

Part B — Configure TheiaCast

1. Sign in to TheiaCast as an Admin → Settings → Authentication.
2. Tick Enable Microsoft Entra ID login.
3. Application (Client) ID — paste from Step 2.
4. Directory (Tenant) ID — paste from Step 2.
5. Default role for new Microsoft users — leave at Viewer unless you have a reason not to.
6. Save. Keep local login enabled for now.

Restricting who can sign in

To restrict sign-in to approved people rather than everyone in the tenant, use two controls, either or both:

• Entra-side: in the Entra portal, Enterprise applications → your app → Properties → Assignment required = Yes, then assign users/groups under Users and groups. Unassigned users are blocked by Entra itself before any token reaches TheiaCast. (Assigning groups requires Entra ID P1+; individual users are free.)
• TheiaCast-side: Settings → Authentication → “Only allow SSO sign-in for existing accounts”. With this on, a valid SSO identity still gets in if their group claims match a group/role mapping below — group membership counts as pre-approval and the account is auto-provisioned with the mapped role. Identities matching neither an existing account nor a mapping are rejected. Applies to Entra, generic OIDC, and SAML alike, and covers providers with no assignment feature of their own.

Mapping groups to roles

Entra security-group membership can drive the TheiaCast role at every sign-in:

1. In the app registration (not the enterprise app): Token configuration → Add groups claim (a separate button next to “Add optional claim” — groups is not in the optional claims list). Choose Groups assigned to the application (recommended: the token then only carries relevant groups) or Security groups, and tick ID under token types. Equivalent manifest setting: "groupMembershipClaims": "ApplicationGroup". The ID token will now carry a groups claim containing the groups’ Object IDs (GUIDs — visible on each group’s Overview page in Entra).
2. In TheiaCast, Settings → Authentication → Group / role claim mapping: add a row per group, pasting its Object ID and choosing the TheiaCast role, e.g. sg_users_app_Theiacast_admins → Admin. Order matters — the first matching row wins, so put the most privileged group first.
3. Users with no matching group get the provider’s configured Default Role. Mapping applies on every login, so moving a user between Entra groups changes their role at next sign-in.

App-role values work too: if the registration defines app roles (manifest appRoles), the token’s roles claim values can be entered in the same table.

Part C — Test

1. Open the TheiaCast login page in a private window at https://signage.example.com.
2. Click Sign in with Microsoft, complete the Microsoft prompt, and confirm you land back in the dashboard.
3. As an existing Admin, open Users and confirm the new (or newly linked) account is present with the expected role.
4. Check Logs / the audit trail for a login.msal event.

Part D — (Optional) enforce SSO only

Once at least one Entra user is an Admin, return to Settings → Authentication, untick Enable local login, and Save. If you have not fully configured SSO the save is rejected — that is the anti-lockout guard doing its job. Keep one local Admin password in your password manager as a break-glass account even if you disable local login in the UI.

8. Generic OpenID Connect SSO

This path works with any provider that implements OpenID Connect discovery. The default flow is a public client using PKCE with no client secret. Providers that require a client secret at the token endpoint — Google Workspace is the common one — are also supported by storing that secret server-side; see Confidential providers below.

What TheiaCast requires of the provider

• A discovery document at <issuer>/.well-known/openid-configuration, reachable from the server.
• Support for the authorization code flow with PKCE. A public / SPA client type (no secret) is simplest; a confidential client with a secret also works — see Confidential providers.
• An ID token whose iss claim exactly equals the Issuer URL you enter in TheiaCast, after any single trailing slash is removed. Ordinal, case-sensitive match.
• An aud claim equal to the client ID you enter.
• A stable sub claim. email and name are used for account linking and the display name if present.
• The redirect URI https://<your-host>/login registered exactly.

Provider compatibility

Walkthrough — Okta

Walkthrough — Keycloak

Configure TheiaCast

1. Admin → Settings → Authentication → tick Enable generic OIDC / SSO login.
2. Provider name — the label on the login button, e.g. Okta or Company SSO.
3. Issuer URL — exactly as it appears in the discovery document’s issuer field.
4. Client ID — from the provider.
5. Client Secret — leave blank for a public / SPA client. Fill it in only for a confidential provider such as Google Workspace — see below.
6. Default role — Viewer recommended.
7. Save, then test from a private window exactly as in the Entra section.

Confidential providers (Google Workspace)

Some providers — notably Google Workspace — only issue a “Web application” OAuth client that requires a client secret at the token endpoint, even with PKCE, and offer no public SPA client type. For these, put the secret in the Client Secret field on Settings → Authentication. When it is set, the browser hands the authorization code to the TheiaCast backend, which performs the token exchange with the stored secret and returns only the ID token — the secret is never exposed to the browser.

Known limitations

• Auth0 issues ID tokens with iss = https://<tenant>.auth0.com/ — note the trailing slash. TheiaCast’s issuer check strips one trailing slash from your configured value and then compares exactly, so an Auth0 token’s iss can never match. Auth0 as a direct provider is not supported today. A client secret does not help here — the mismatch is in the issuer, not the token exchange.
• Any provider whose iss claim ends in a trailing slash has the same problem as Auth0, regardless of client type.
• Workaround for a trailing-slash issuer: front that identity with a broker that presents a compliant iss — Keycloak or Okta federating upstream — and point TheiaCast at the broker. For Microsoft shops, use the native Entra path.

9. SAML 2.0 SSO (ADFS, legacy IdPs)

SAML covers the providers OIDC can’t: ADFS, older on-prem directory integrations, and legacy enterprise IdP setups that only speak SAML. TheiaCast is a Service Provider — it cannot act as an identity provider for other applications.

The flow is browser-level — there is no code exchange:

1. The user clicks Sign in with &lbrace;provider&rbrace;; the browser hits GET /api/auth/saml/login.
2. TheiaCast builds a SAML AuthnRequest (HTTP-Redirect binding) and 302s the browser to the IdP’s SSO URL.
3. The IdP authenticates the user and POSTs the signed assertion back to the ACS endpoint https://<your-host>/api/auth/saml/acs (HTTP-POST binding).
4. The backend validates the signature against the configured IdP certificate (never a certificate carried inside the response itself), checks issuer, audience and timestamps, and requires InResponseTo to match a request it issued — IdP-initiated (unsolicited) sign-in is not supported, and assertion replay is rejected.
5. On success the browser lands back on /login with a normal TheiaCast session.

Walkthrough — AD FS

AD FS is the most common reason to reach for SAML at all — it doesn’t speak OIDC. The trust is configured on the AD FS side as a relying party trust, with claim rules controlling what the assertion carries.

1. AD FS Management console → Relying Party Trusts → Add Relying Party Trust → Claims aware.
2. Select Data Source: Import data about the relying party published online or on a local network, and give it TheiaCast’s own SP metadata URL: https://<your-host>/api/auth/saml/metadata. (If AD FS can’t reach TheiaCast directly, download that URL and use Import from a file instead.)
3. Access control policy: Permit everyone or a specific group.
4. Finish — this opens Edit Claim Issuance Policy. Add two rules: Send LDAP Attributes as Claims (E-Mail-Addresses → E-Mail Address), then Transform an Incoming Claim (E-Mail Address → Name ID, format Email). The second rule is what populates NameID — without it AD FS’s default assertion has no usable subject identifier.
5. AD FS signs responses and assertions by default with its own token-signing certificate — nothing to set on the AD FS side. On TheiaCast, use Fetch against AD FS’s federation metadata URL (https://<adfs-host>/FederationMetadata/2007-06/FederationMetadata.xml) to pull the entity ID, SSO URL and current signing cert in one step — the easiest way to stay in sync if that certificate is ever rotated, which is the single most common cause of a previously-working SAML login breaking.

Setup

In Settings → Authentication → Enable SAML 2.0 login: paste the IdP’s metadata URL and click Fetch to fill entity ID, SSO URL and signing certificate automatically — or enter all three by hand. Set the default role for auto-provisioned accounts. On the IdP, register a relying party / enterprise application with:

• Entity ID / Identifier: https://<host>/api/auth/saml
• Reply / ACS URL: https://<host>/api/auth/saml/acs
• SP metadata document: served at https://<host>/api/auth/saml/metadata

Both SP URLs can be overridden in settings if the deployment sits behind a reverse proxy with a different public address. The assertion must be signed (response- or assertion-level) and carry a NameID; email and displayNameattributes are recommended for account linking, same as OIDC.

10. Managing users once SSO is live

• Bootstrapping the first SSO admin. Either (a) make sure your existing local Admin account has the same email as your SSO identity, so the first SSO login links to it and inherits Admin; or (b) let the first SSO login auto-provision as Viewer, then have an existing Admin promote it in Admin → Users.
• Promoting / changing roles. With no group/role mapping configured, this is always done in Admin → Users and sticks until changed again. If a group/role mapping is configured (Entra shown; also works for generic OIDC and SAML), the role is instead re-derived from the provider’s group/role claims on every login — a manual change in Admin → Users only lasts until their next sign-in.
• Deactivating someone. Removing or disabling them at the identity provider stops new logins immediately. Delete or disable the TheiaCast user as well to end their current session and be tidy.
• Duplicate accounts. These appear when the email in the token doesn’t match an existing user (typo, changed address, missing email claim). Fix the email on the intended account first, delete the stray one, and have the person sign in again to re-link.
• Break-glass. Keep one local Admin whose password is in your password manager, even in SSO-only mode, so a provider outage can’t lock you out of your own signage.

11. Device / client rollout

SSO covers people. Display devices authenticate with a per-device token instead — they never sign in interactively. Full platform steps are in the Installation Guide; the essentials:

1. In TheiaCast: Devices → Add Device, give it a name and ID, and copy the generated device token.
2. On the device, run the installer and provide the server URL and that token.

Linux / Raspberry Pi (one line, as root):

curl -sSL https://gist.githubusercontent.com/jimmyeao/9a6922cdf1c69da92f1be9c7e3463052/raw/install-theiacast-client.sh | sudo bash

The installer detects the hardware and display setup, installs Chromium, writes /opt/theiacast-client/.env, and registers a systemd service that survives reboots and self-updates.

Windows:

Download the Windows client from the Download page, run the setup, enter the server URL and device token, and it installs as a Windows service.

Fleet tips

• Use device groups and tag rules so a device gets the right playlist automatically from its name or tags — you avoid assigning each one by hand.
• Devices ship telemetry (CPU, memory, disk, screenshots) on a schedule; the intervals are configurable in Settings.
• Turn on device-offline email alerts (Settings) so you hear about a dead screen before a visitor does.
• Client updates roll out from the server — see the Installation Guide’s Updating the Client section.

12. Troubleshooting

Where to look first

• Backend logs: docker compose logs -f backend — token validation failures are logged here with the reason.
• In-app: the Logs page and the audit trail. Successful SSO logins record login.msal, login.oidc, or login.saml; provisioning and account-linking are logged too.
• Browser dev tools on the /login page — the Network tab shows the redirect to the provider and the callback, and any provider error is in the callback URL’s query string.

SSO

Server

Devices

13. Appendix

Redirect URI cheat-sheet

Claim mapping

Authentication settings (stored server-side)

All set from Settings → Authentication; listed here for reference and for reading the database if you ever need to.

Ports & URLs

Need help?