---
title: Multi-Domain Architecture & Routing
category: Getting Started
order: 3
badge: Deep Dive
description: Architectural breakdown of multi-domain resolution, DomainContextService, cookie isolation, and CORS topology.
---

# Multi-Domain Architecture & Routing

Ternis Auth implements a sophisticated **Multi-Domain Federation Engine**. Rather than isolating environments into separate, disjoint deployments, Ternis Auth operates a unified state and authorization store that dynamically adapts its branding, endpoints, security policies, and tokens based on the incoming domain name.

---

## 1. Domain Clusters & Typology

Every domain in the cluster belongs to one of three primary functional types:

```
[ Incoming HTTP Request: Host header ]
                   │
                   ▼
       DomainContextService::resolve()
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
[ 'auth' ]    [ 'account' ]   [ 'user' ]
auth.ternis.net account.ternis.org user.t-cdn.de
auth.ternis.org account.ternis.net avatar.t-cdn.de
auth.ternis.dev                    user.t-api.de
auth.t-api.de
auth.thosted.de
```

### Domain Classification Matrix

| Domain Host | Type | TLD | Portal Brand | Key Responsibilities |
| :--- | :--- | :--- | :--- | :--- |
| **`auth.ternis.net`** | `auth` | `net` | Ternis Auth (Global) | Primary global OAuth 2.0 / OIDC issuer, consent flow, and token issuer. |
| **`auth.ternis.org`** | `auth` | `org` | Ternis Community SSO | Foundation SSO, community portal, and open-source platform identity. |
| **`auth.ternis.dev`** | `auth` | `dev` | Ternis Dev Sandbox | Third-party developer integration staging and experimental API features. |
| **`auth.t-api.de`** | `auth` | `de` | t-API Auth Gateway | Dedicated API edge for German and European cloud infrastructure. |
| **`auth.thosted.de`** | `auth` | `de` | tHosted SSO Hub | Cloud hosting and SaaS Single Sign-On gateway and authorized callback target. |
| **`user.t-cdn.de`** | `user` | `de` | t-CDN User Avatars | Cookieless, high-speed avatar image delivery by user UUID or username. |
| **`avatar.t-cdn.de`** | `user` | `de` | t-CDN Avatar Edge | Vector SVG and raster avatar delivery edge network. |
| **`user.t-api.de`** | `user` | `de` | t-API User Service | API fallback and avatar discovery endpoint. |
| **`account.ternis.org`** | `account`| `org` | Ternis Account Portal | User self-service center (security, credentials, OAuth applications). |
| **`account.ternis.net`** | `account`| `net` | Enterprise Accounts | Commercial subscriptions, enterprise memberships, and organization billing. |

---

## 2. Dynamic Domain Resolution (`DomainContextService`)

Ternis Auth uses a central service, [`App\Services\DomainContextService`](file:///Users/fabianternis/Code/GitHub/ternis-dev/ternisauth/app/Services/DomainContextService.php), bound as a singleton in the Laravel service container.

For every incoming HTTP request:
1. The hostname is extracted from the `Host` HTTP header or server variables.
2. The domain is checked against explicit configuration records in `config/ternis_domains.php`.
3. If no explicit entry matches, regex pattern matching classifies the domain:
   - `auth`: `/^(auth\.)/i`
   - `account`: `/^(account\.|acc\.|profile\.)/i`
   - `user`: `/^(user\.|users\.|avatar\.|avatars\.)/i`
4. The service assigns the active portal name, theme color (`indigo`, `purple`, `cyan`, `emerald`), environment, and target account domain.

### Dynamic Response Headers

Every HTTP response emits standard diagnostic headers disclosing the active domain context:

```http
HTTP/1.1 200 OK
X-Ternis-Domain-Host: auth.ternis.net
X-Ternis-Domain-Type: auth
X-Ternis-Issuer: https://auth.ternis.net
```

---

## 3. Allowed Redirect URI Validation

To prevent open redirect and token-stealing attacks, authorization requests (`/oauth/authorize`) strictly validate `redirect_uri` against both registered client patterns and ecosystem wildcard rules.

### Ecosystem Wildcard Patterns
Configured in `config/ternis_domains.php`, the following domains are inherently permitted for first-party and trusted platform callbacks:

- `*.ternis.net`
- `*.ternis.org`
- `*.ternis.dev`
- `*.t-api.de`
- `*.t-cdn.de`
- `*.thosted.de` (including `auth.thosted.de` and `app.thosted.de`)
- `localhost` and `127.0.0.1` (for local developer sandboxes)

### Validation Algorithm
When a client requests authorization:
1. Exact match against the client's registered `redirect_uris`.
2. Pattern match against wildcard ecosystem rules (e.g. `https://auth.thosted.de/callback`).
3. If validation fails, the server rejects the request with standard RFC 6749 error:
   `invalid_request: The redirect_uri provided is not registered or permitted.`

---

## 4. Cookieless Edge for Avatar CDN

Domains categorized as `user` (`user.t-cdn.de`, `avatar.t-cdn.de`) operate in a **cookieless media delivery mode**:

- **No Session Cookies**: Standard session and CSRF middleware are bypassed for media routes.
- **Cache-Control Headers**: Aggressive HTTP caching headers (`public, max-age=86400, stale-while-revalidate=604800, immutable`) are set for static assets.
- **CORS Headers**: `Access-Control-Allow-Origin: *` is sent on all avatar responses so frontend apps can load avatars inside `<canvas>` or cross-origin `<img>` elements without tainting.

---

## 5. Reverse Proxy & HTTPS Derivation

In production, Ternis Auth operates behind reverse proxies (Nginx, Cloudflare, Traefik). The application honors standard forward headers:

- `X-Forwarded-Host` / `X-Forwarded-Proto`
- `X-Forwarded-For`
- `CF-Connecting-IP`

This ensures that the OpenID Connect issuer URL dynamically generates proper `https://` URLs matching the exact host requested by the client.