Guides on Palmyra

Security Configuration Recipes

Mon, 01 Jan 0001 00:00:00 +0000

Security Configuration Recipes#

Palmyra doesn’t own your Spring Security setup — the user-management extension gives you an AuthenticationProvider, but the filter chain is yours to compose. These are the four recipes every app ends up writing.

The single-page-app default: POST /auth/login establishes an HTTP session, a JSESSIONID cookie authenticates subsequent requests, CSRF protects mutations, 401 on session expiry.

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {
    private final LocalDBAuthenticationProvider localDbProvider;

    @Bean
    public SecurityContextRepository securityContextRepository() {
        return new DelegatingSecurityContextRepository(
                new RequestAttributeSecurityContextRepository(),
                new HttpSessionSecurityContextRepository());
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http,
                                           SecurityContextRepository repo) throws Exception {
        CsrfTokenRequestAttributeHandler csrfHandler = new CsrfTokenRequestAttributeHandler();
        csrfHandler.setCsrfRequestAttributeName(null);   // eager resolution — see §3

        return http
                .authenticationProvider(localDbProvider)
                .securityContext(c -> c.securityContextRepository(repo))
                .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED))
                .csrf(c -> c
                        .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                        .csrfTokenRequestHandler(csrfHandler)
                        .ignoringRequestMatchers("/auth/login", "/auth/logout"))
                .authorizeHttpRequests(a -> a
                        .requestMatchers("/auth/login", "/auth/logout", "/public/**").permitAll()
                        .anyRequest().authenticated())
                .exceptionHandling(e -> e.authenticationEntryPoint(
                        new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED)))
                .build();
    }
}

Pair it with an idle timeout in application.yml:

Programmatic Access

Mon, 01 Jan 0001 00:00:00 +0000

Programmatic Access — API keys for non-browser clients#

palmyra-dbpwd-mgmt covers username/password for people. Python scripts, batch jobs, and headless agents need a different credential: an API key that can be provisioned per client, revoked independently, and audited. This guide shows how to add that as a second AuthenticationProvider alongside your user chain so both land on the same ACL model.

The design in one diagram#

┌──────────────────────┐
│  Client — browser    │ ─── POST /auth/login (user/pass) ─► session cookie
│                      │ ─── subsequent calls with JSESSIONID
└──────────────────────┘                    │
                                            │  both resolve to
┌──────────────────────┐                    │  xpm_user.login_name
│  Client — script     │                    │  → same @Permission evaluator
│  (Python/Java/curl)  │ ── X-Api-Key: ... ─┤
└──────────────────────┘                    │
                                            ▼
                                    handler with @Permission("X", ...)
                                    → PalmyraPermissionEvaluator
                                    → xpm_acl_group_permission row

One principal model, two ways to authenticate.

Dev Bootstrap & Seed Data

Mon, 01 Jan 0001 00:00:00 +0000

Dev Bootstrap & Seed Data#

Palmyra reads the DB schema at startup — so every new dev environment needs the same tables, constraints, and seed rows before the first request goes through. This guide covers the three problems every project hits:

DDL that belongs in version control but isn’t managed by Hibernate.
Seed rows for lookup tables and an admin user.
Order-of-operations with Hibernate’s ddl-auto.

1. `ddl-auto` — what to set, and why#

Profile	Setting	Reasoning
Dev against a stable schema	`ddl-auto: none`	Palmyra reads metadata at startup; ddl-auto re-diffing churns the schema and has fought with our `DevBootstrap`-managed columns in practice
Dev, actively evolving the schema	`ddl-auto: update`	Fast iteration; JPA entity changes show up in the DB. Accept the churn
Test (testcontainers / H2)	`ddl-auto: create-drop`	Throw-away
Prod	`ddl-auto: validate`	Fail fast on schema drift

Our working recommendation: start with update in dev, flip to none once your schema stabilises — at that point DevBootstrap owns the DDL deltas and Hibernate stops interfering.

Dynamic Navigation

Mon, 01 Jan 0001 00:00:00 +0000

Most admin apps want a side nav that’s (a) driven by data, not hard-coded, and (b) filtered per-user by ACL grants. palmyra-dbacl-mgmt gives you the backend half (two tables + one endpoint); @palmyralabs/template-tribble gives you the frontend half (DynamicMenu). This guide stitches them together.

Architecture#

 xpm_menu  ─── parent/child tree of nav entries (id, name, code, display_label, path, …)
     │
     │  M:N via xpm_acl_menu (menu_id × group_id × mask)
     │
 xpm_group ── xpm_acl_user ── xpm_user
                                  │
                                  │  current logged-in user
                                  ▼
          GET /acl/menu/listAll  →  rows the user's groups have mask > 0 on
                                  │
                                  ▼
          React: useTreestore + DynamicMenu (AsyncTreeMenu under the hood)

1. The tables#

Both ship as JPA entities inside palmyra-dbacl-mgmt — Hibernate creates them with ddl-auto: update:

Schema Discovery (internals)

Mon, 01 Jan 0001 00:00:00 +0000

Schema Discovery — how Palmyra reads your database#

The Mental Model page says “the database schema is the source of truth.” This page is the under-the-hood version — what Palmyra actually reads, when, and how that drives request-time behaviour. Useful when debugging why a field doesn’t resolve or why a join looks different from what you expect.

What gets read, and when#

At Spring context startup, Palmyra builds an in-memory Schema object backed by a SchemaProvider. The default SchemaProvider reads:

Performance & Observability

Mon, 01 Jan 0001 00:00:00 +0000

Performance & Observability#

Palmyra is raw JDBC — no Hibernate session, no lazy loading, no dirty-check sweep. The claim on the home page is “sub-50 ms typical”; this page covers what you have to do to keep it that way, and what to measure when you don’t.

1. Pagination defaults#

Every QueryHandler response is paginated. Defaults from application.yml:

palmyra:
  query:
    default-limit: 15
    max-limit:     500

Client overrides come via query params: ?limit=30&offset=60. Clients that don’t send limit get default-limit. Clients that send limit > max-limit get truncated to max-limit — no error, just capped. Set max-limit conservatively — it’s your guard against accidental full-table dumps.

Frontend Project Setup

Mon, 01 Jan 0001 00:00:00 +0000

Frontend project setup — deep walkthrough#

tutorial/frontend/01-setup.md covers the three-command start. This page is the fuller version — the files you actually need, how they fit together, and what to configure before you build your first grid.

1. Stack#

Concern	Choice
Build	Vite 7+ with `@vitejs/plugin-react`
Language	TypeScript 5.9+
Runtime	React 19 + react-dom 19
UI kit	`@mantine/core`, `@mantine/dates`, `@mantine/hooks` (v8) — or the MUI variants
Data layer	`@palmyralabs/palmyra-wire` — store factory (single source of network truth)
Forms	`@palmyralabs/rt-forms` + `@palmyralabs/rt-forms-mantine` (or `-mui`)
Grid / form templates	`@palmyralabs/template-tribble` — `SummaryGrid`, `DialogNewForm`, `DialogEditForm`, `DynamicMenu`
Router	`react-router-dom` v7
Notifications	`react-toastify`
HTTP	`axios` (for interceptors); palmyra-wire uses it under the hood
Utilities	`@palmyralabs/ts-utils`, `dayjs`

2. `package.json` — minimum deps#

{
  "name": "my-web",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev":   "vite",
    "build": "tsc -b && vite build",
    "lint":  "eslint ."
  },
  "dependencies": {
    "@mantine/core":                   "^8.3.1",
    "@mantine/dates":                  "^8.3.1",
    "@mantine/hooks":                  "^8.3.1",
    "@palmyralabs/palmyra-wire":       "^1.2.0",
    "@palmyralabs/rt-forms":           "github:palmyralabs/rt-forms",
    "@palmyralabs/rt-forms-mantine":   "github:palmyralabs/rt-forms-mantine",
    "@palmyralabs/template-tribble":   "github:palmyralabs/rt-template-tribble",
    "@palmyralabs/ts-utils":           "^0.3.0",
    "axios":                           "^1.12.2",
    "dayjs":                           "^1.11.18",
    "react":                           "^19.1.1",
    "react-dom":                       "^19.1.1",
    "react-icons":                     "^5.5.0",
    "react-router-dom":                "^7.9.1",
    "react-toastify":                  "^11.0.5"
  },
  "devDependencies": {
    "@types/react":        "^19.1.13",
    "@types/react-dom":    "^19.1.9",
    "@vitejs/plugin-react":"^5.0.3",
    "typescript":          "~5.9.2",
    "vite":                "^7.1.6",
    "vite-tsconfig-paths": "^5.1.4"
  }
}

3. `vite.config.ts`#

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  server: {
    port: 3000,
    open: '/app/login',
    proxy: {
      '/api': {
        target: 'http://localhost:6060',
        changeOrigin: false,
        secure: false,
      },
    },
  },
});

The proxy is critical — forwards /api/** to the Spring Boot service so withCredentials cookies stay same-origin from the browser’s perspective. Without this, CSRF / session won’t round-trip in dev.

Guides on Palmyra

Security Configuration Recipes

Security Configuration Recipes#

1. Session-based login for a SPA#

Programmatic Access

Programmatic Access — API keys for non-browser clients#

The design in one diagram#

Dev Bootstrap & Seed Data

Dev Bootstrap & Seed Data#

1. ddl-auto — what to set, and why#

Dynamic Navigation

Dynamic Navigation — data-driven sidebar#

Architecture#

1. The tables#

Schema Discovery (internals)

Schema Discovery — how Palmyra reads your database#

What gets read, and when#

Performance & Observability

Performance & Observability#

1. Pagination defaults#

Frontend Project Setup

Frontend project setup — deep walkthrough#

1. Stack#

2. package.json — minimum deps#

3. vite.config.ts#

1. `ddl-auto` — what to set, and why#

2. `package.json` — minimum deps#

3. `vite.config.ts`#