DEV Community: Ismail ZAHIR

The Hidden Cost of “Just Add a Setting”

Ismail ZAHIR — Wed, 09 Sep 2026 12:09:57 +0000

“Can we just add a setting for this?”

It sounds harmless.

Suppose an office should be able to choose its default appointment duration. The first implementation is obvious:

@Entity
public class Office {

    private int appointmentDuration;
}

Set it to 30, expose it through the API, add an input in the frontend, and move on.

But now consider two offices that both currently use 30 minutes.

For the first office, 30 is explicitly configured. For the second, there is no configured value at all; it simply inherits the platform default of 30.

Those offices behave identically today.

They may behave differently tomorrow.

If the platform default changes to 20 minutes, the first office should probably stay at 30 while the second should inherit 20.

That distinction — explicit value versus effective value — is where a seemingly simple setting starts becoming a modeling problem.

It leads directly to another subtle question:

What should “Reset to default” actually do?

It should usually remove the override, not write the current default into it. Writing 30 and inheriting 30 happen to produce the same result today, but they represent different intent.

That is the kind of detail most generic settings-table designs miss.

This article follows one setting, APPOINTMENT_DURATION, from a field on an entity to a scoped, resolved, validated, audited, and cached configuration model — and looks at the design decisions that appear along the way.

A simple field is often the right answer

Putting configuration directly on an entity is not inherently bad.

@Entity
public class Office {

    private boolean onlineBookingEnabled;

    private int appointmentDuration;

    private String timezone;
}

For stable properties with obvious ownership, this design is excellent. It gives you strong typing, database constraints, simple queries, straightforward refactoring, and very little infrastructure.

The problem starts when those values stop being ordinary properties and acquire behavior: platform defaults, tenant overrides, office overrides, runtime modification, authorization rules, dynamic frontend rendering, validation metadata, audit requirements, or lifecycle rules.

At that point, configuration has concepts of its own, and those concepts need somewhere to live.

Definition and value are different concepts

Once settings become dynamic, I find it useful to separate two ideas.

A setting definition identifies a setting and records the persisted metadata the application needs to manage its lifecycle and presentation.

A setting value records an explicit override for a particular owner.

For example:

@Entity
public class SettingDefinition {

    @Column(unique = true, nullable = false)
    private String code;

    private String label;

    private String description;

    @Enumerated(EnumType.STRING)
    private SettingDataType dataType;

    @Enumerated(EnumType.STRING)
    private SettingStatus status;
}

With:

public enum SettingDataType {
    STRING,
    BOOLEAN,
    INTEGER,
    DECIMAL,
    ENUM,
    JSON
}

And:

public enum SettingStatus {
    ACTIVE,
    DEPRECATED,
    DISABLED
}

That entity is deliberately not the complete behavioral specification of the setting.

In the model I prefer, code owns behavioral metadata such as defaults, validation constraints, and permitted override scopes. The database owns persistent identity, lifecycle status, and presentation metadata such as labels or localizable descriptions.

So the canonical code-level specification might be:

public static final SettingSpec<Integer> APPOINTMENT_DURATION =
    SettingSpec.integer("APPOINTMENT_DURATION")
        .defaultValue(30)
        .minimum(15)
        .maximum(120)
        .allowOverrideAt(
            SettingScope.TENANT,
            SettingScope.OFFICE
        )
        .build();

This gives the application one authoritative place for the rules that affect execution.

The persisted definition still matters. It gives values and audit records a stable database identity, supports lifecycle management, and can carry presentation metadata without turning database rows into executable business rules.

At startup, the application can validate that the persisted definition is compatible with the code specification. If code says INTEGER while the database says STRING, deployment should fail before the application starts serving requests.

That separation avoids an awkward situation where the same rule exists independently in Java and in a mutable database row.

Ownership is not one field

A common generic model puts this on the definition:

private SettingOwnerType ownerType;

That is coherent only if a setting belongs to exactly one level.

If APPOINTMENT_DURATION can exist only at office level, ownerType = OFFICE is fine.

But it does not describe a hierarchy such as:

user
  ↓
office
  ↓
organization
  ↓
tenant
  ↓
platform default

If the same setting can be overridden at several levels, its specification needs to express where overrides are permitted, not pretend it has one owner.

For example:

public enum SettingScope {
    TENANT,
    ORGANIZATION,
    OFFICE,
    USER
}

Our appointment-duration setting permits:

TENANT
OFFICE

The platform default comes from the canonical specification. A tenant may override it. An office may override the tenant. A user may not.

Another setting might allow only tenant overrides. A security-sensitive setting might allow no business-level overrides at all.

That distinction becomes important once authorization enters the picture.

Resolution needs a context, not a growing method signature

Once hierarchy exists, the resolver needs to know which tenant, organization, office, or user is involved.

I would avoid this:

resolve(
    String code,
    UUID tenantId,
    UUID officeId
);

It bakes today's hierarchy into the public API. Add organizations later and every consumer changes.

A better boundary is a context object:

public record SettingContext(
    UUID tenantId,
    UUID organizationId,
    UUID officeId,
    UUID userId
) {}

The internal resolver can then operate on that context:

public interface SettingResolver {

    <T> ResolvedSetting<T> resolve(
        SettingSpec<T> spec,
        SettingContext context
    );
}

Business code should normally depend on a small Settings facade rather than directly on the resolver:

public interface Settings {

    int getInteger(
        SettingSpec<Integer> spec,
        SettingContext context
    );

    boolean getBoolean(
        SettingSpec<Boolean> spec,
        SettingContext context
    );
}

The layering is intentional:

Business services
      ↓
Settings facade
      ↓
SettingResolver
      ↓
Persistence / cache / hierarchy

The facade gives consumers a convenient typed API. The resolver owns precedence, source tracking, caching, and persistence details.

Business services should never reimplement inheritance themselves.

Explicit value and effective value are different data

Suppose the platform default is 30 and an office has no override.

Returning this:

{
  "value": 30
}

throws away important information.

The frontend cannot know whether 30 was explicitly configured or inherited.

A better resolved model is:

public record ResolvedSetting<T>(
    String code,
    T explicitValue,
    T effectiveValue,
    SettingSource source,
    boolean overridden
) {}

An office with no override might resolve to:

{
  "code": "APPOINTMENT_DURATION",
  "explicitValue": null,
  "effectiveValue": 30,
  "source": "PLATFORM_DEFAULT",
  "overridden": false
}

If its tenant defines 20:

{
  "code": "APPOINTMENT_DURATION",
  "explicitValue": null,
  "effectiveValue": 20,
  "source": "TENANT",
  "overridden": false
}

And after the office chooses 45:

{
  "code": "APPOINTMENT_DURATION",
  "explicitValue": 45,
  "effectiveValue": 45,
  "source": "OFFICE",
  "overridden": true
}

This is not just frontend convenience. It exposes the actual semantics of the configuration model.

Reset is a first-class domain operation

Suppose the platform default is currently 30 and an office clicks Reset to default.

A naive implementation might do this:

settingValue.setValue("30");

That does not reset anything.

It creates an explicit office override equal to today's default.

If the platform changes the default to 20 next month, that office stays on 30 because its value is now pinned.

If reset means “inherit again,” the operation must remove the explicit override.

But that does not mean the UI or business service should call the repository directly.

Reset has the same concerns as any other configuration mutation:

authorization;
auditing;
cache invalidation;
lifecycle rules;
events or downstream side effects.

So it deserves an application operation of its own:

@Transactional
public void removeOverride(
    SettingSpec<?> spec,
    SettingContext context
) {
    authorization.checkCanOverride(
        spec,
        context
    );

    SettingValue existing =
        valueRepository.findOverride(
            spec.code(),
            context
        ).orElse(null);

    if (existing == null) {
        return;
    }

    valueRepository.delete(existing);

    auditService.recordOverrideRemoved(
        spec,
        context,
        existing.value()
    );

    cacheVersions.bump(context);

    eventPublisher.publish(
        new SettingChangedEvent(
            spec.code(),
            context
        )
    );
}

After that operation, normal resolution takes over:

office override: none
tenant override: none
platform default: 30

If the platform later changes to 20, the office automatically sees 20.

This is why absence is not merely missing data.

Absence can represent inheritance.

And reset is not just “delete instead of write.”

It is a first-class domain operation that restores inheritance.

Persisting polymorphic owners has real trade-offs

The domain model may be conceptually simple:

definition + scope + owner + value

but the relational model still needs to represent that safely.

The generic approach is attractive:

setting_values
-------------------------
definition_id
owner_type
owner_id
value

with:

UNIQUE(definition_id, owner_type, owner_id)

It is flexible, but owner_id is polymorphic. The database cannot naturally enforce that an OFFICE value references offices.id while a TENANT value references tenants.id.

There are three common approaches.

A generic discriminator table keeps the schema compact and extensible but moves referential integrity into application logic.

Separate tables per scope, such as tenant_setting_values and office_setting_values, are more repetitive but give each owner a real foreign key and straightforward uniqueness constraints.

A third option uses nullable foreign keys:

definition_id
tenant_id
organization_id
office_id
user_id
value

with a check constraint requiring exactly one owner column. That preserves relational integrity but becomes more cumbersome as scopes expand.

There is no universally correct answer. If ownership levels are few and stable, I value database-enforced referential integrity highly. If scopes really are extensible, a discriminator may be worth the weaker schema guarantees.

The important point is that a bare UUID ownerId is not free abstraction. It exchanges schema rigidity for weaker relational guarantees.

Not every setting should be overridable

APPOINTMENT_DURATION is a reasonable office-level setting.

AUDIT_LOGGING_ENABLED may not be.

The configuration model therefore needs to distinguish between visibility and editability.

Our canonical specs could look conceptually like this:

APPOINTMENT_DURATION
allowed overrides: TENANT, OFFICE

SECURITY_POLICY_ENABLED
allowed overrides: none

The system must answer two separate questions:

What is the effective value?

and:

Is this actor allowed to create or remove an override at this scope?

The first belongs to resolution.

The second belongs to authorization.

A setting being visible does not imply it should be editable.

Validation belongs near the specification

Without a shared model, validation tends to spread through service code:

if ("APPOINTMENT_DURATION".equals(code)) {
    int duration = Integer.parseInt(value);

    if (duration < 15 || duration > 120) {
        throw new InvalidSettingValueException();
    }
}

Then another setting adds another branch.

Then another.

The canonical specification gives structural validation a proper home:

SettingSpec.integer("APPOINTMENT_DURATION")
    .defaultValue(30)
    .minimum(15)
    .maximum(120)
    .build();

Simple constraints such as type, minimum, maximum, allowed enum values, or string patterns can be enforced generically.

A setting also does not necessarily need a default. If the absence of a value is itself meaningful, the specification can explicitly model that instead of inventing a synthetic default just to satisfy the framework.

But not every rule belongs in the specification.

If appointment duration must be compatible with a scheduling algorithm, office opening hours, or another setting, that is business logic. A settings framework should centralize structural validation without turning into a homemade rules engine.

Where do definitions come from?

This is one of the most important questions in the entire design.

Who creates APPOINTMENT_DURATION in the first place?

Database-first

One option is to seed definitions through Liquibase, Flyway, or another migration system:

INSERT INTO setting_definitions (
    code,
    data_type,
    status
)
VALUES (
    'APPOINTMENT_DURATION',
    'INTEGER',
    'ACTIVE'
);

This gives you explicit, reviewable deployment changes. Renames, additions, and lifecycle transitions are visible in migrations.

The downside is that application code has weaker compile-time knowledge of the available settings unless you create a second representation.

Code-first

Another approach is to declare the full catalog in source code:

public static final SettingSpec<Integer> APPOINTMENT_DURATION =
    SettingSpec.integer("APPOINTMENT_DURATION")
        .defaultValue(30)
        .minimum(15)
        .maximum(120)
        .allowOverrideAt(TENANT, OFFICE)
        .build();

This is strongly typed, easy to discover, and easy to test.

But now you have to decide how database state follows code. Should startup silently insert missing definitions? Delete unknown ones? Modify metadata automatically?

That can make application startup unexpectedly destructive.

Hybrid: code owns behavior, migrations own lifecycle

For product-defined settings, I prefer a hybrid.

Code owns the behavioral contract:

data type;
default value;
validation constraints;
allowed scopes.

Database migrations own persistence and lifecycle:

creation of the persisted definition;
stable database identity;
lifecycle state;
labels or localization references;
explicit renames and migrations.

Startup then performs reconciliation as validation rather than mutation.

For example:

Code expects:
APPOINTMENT_DURATION / INTEGER

Database contains:
APPOINTMENT_DURATION / STRING

→ deployment fails

The same principle applies to scope or other compatibility-critical metadata.

If code permits TENANT and OFFICE, but persisted metadata implies something incompatible, that should be detected deliberately rather than allowed to drift.

This avoids having two competing sources of truth: runtime behavior comes from code, while persistence evolution remains an explicit deployment concern.

The catalog joins the two halves

Once definitions are split between code and persistence, the application needs one place that can enumerate them.

That is the role of a SettingCatalog.

Conceptually:

public interface SettingCatalog {

    Collection<SettingSpec<?>> all();

    Optional<SettingSpec<?>> findByCode(
        String code
    );
}

The catalog contains or discovers the registered code-level specifications:

APPOINTMENT_DURATION
ONLINE_BOOKING_ENABLED
REMINDER_DELAY
...

When the application needs a settings page, startup validation, or bulk resolution, it joins those specs with their persisted SettingDefinition rows.

That joined view answers questions such as:

Is this spec ACTIVE, DEPRECATED, or DISABLED?
What label should the UI display?
Does the persisted type still match the canonical spec?
Which registered settings should appear in this context?

For example, the settings page can start from:

SettingCatalog
      +
Persisted SettingDefinition metadata
      +
Resolved values
      +
Authorization
      ↓
SettingView

A DISABLED definition can therefore remain in the database for historical values and audit records without appearing in the normal configuration UI.

The catalog is also what makes bulk APIs such as resolveAll(...) practical: the application has a single enumerable registry of known specs rather than scattered constants with no discovery mechanism.

Setting codes are persistent identifiers

Suppose version one introduces:

SHOW_PATIENT_PHONE

Later, the feature becomes more nuanced and you replace it with:

PATIENT_CONTACT_VISIBILITY

That is not a normal rename.

The original code may already be referenced by stored values, audit records, frontend contracts, support documentation, tests, migration scripts, and external integrations.

Treating setting codes as API-like identifiers changes how lifecycle should work.

A safer migration might be:

1. introduce the new definition
2. migrate existing values
3. mark the old definition DEPRECATED
4. migrate consumers
5. eventually mark it DISABLED

Deleting the old row immediately is often the wrong operation.

Settings evolve much more like public contracts than ordinary labels.

Audit the decision, not just the current value

Configuration bugs often appear as behavior changes rather than exceptions.

A support ticket says:

Appointments were 30 minutes yesterday. Why are they 45 today?

Looking at the current setting only tells you that the value is 45. It does not tell you why the system changed.

For behaviorally important settings, an audit trail should be able to answer:

setting: APPOINTMENT_DURATION
owner: office-123
old value: inherited 30
new value: 45
changed by: user-456
changed at: 2026-09-09T10:42

A reset should be equally visible:

setting: APPOINTMENT_DURATION
owner: office-123
old value: explicit 45
new value: inherited 20
operation: OVERRIDE_REMOVED
changed by: user-456

For some settings, the historical trail is more valuable than the current row. This is especially true when configuration affects security, pricing, workflow, notifications, or user-visible behavior.

That is why a setting update or reset can become a real application operation rather than a simple repository mutation.

Updating a setting may have side effects

A service might eventually coordinate several concerns:

@Transactional
public <T> void setOverride(
    SettingSpec<T> spec,
    SettingContext context,
    T value
) {
    authorization.checkCanOverride(
        spec,
        context
    );

    validator.validate(
        spec,
        value
    );

    valueRepository.upsert(
        spec.code(),
        context,
        value
    );

    auditService.recordChange(
        spec,
        context,
        value
    );

    cacheVersions.bump(context);

    eventPublisher.publish(
        new SettingChangedEvent(
            spec.code(),
            context
        )
    );
}

The generic type matters.

SettingSpec<Integer> should accept an Integer, not an arbitrary Object. If the specification is meant to provide type safety, the mutation API should preserve it all the way through the write path.

The matching reset operation follows the same lifecycle but removes the explicit value instead of storing a new one.

Not every setting needs events or cache invalidation. But the architecture should have a natural place for those concerns once they appear.

Changing DATE_FORMAT may affect only presentation. Changing ONLINE_BOOKING_ENABLED may alter behavior immediately. Changing APPOINTMENT_DURATION may affect future scheduling.

“Settings” are not necessarily passive data.

Bulk resolution matters

The typed facade is convenient for business logic:

int duration = settings.getInteger(
    APPOINTMENT_DURATION,
    context
);

But it would be a poor implementation strategy for rendering an entire settings page.

Imagine 200 definitions across tenant, organization, office, and user scopes. Resolving each one independently can easily create an N+1 query problem.

The resolver therefore needs a bulk path too:

Map<String, ResolvedSetting<?>> resolveAll(
    Collection<SettingSpec<?>> specs,
    SettingContext context
);

The caller can obtain those specs from the catalog, filtered by the persisted lifecycle metadata relevant to that operation.

Internally, the resolver can load each relevant scope in batches:

1 query → persisted definitions
1 query → tenant overrides
1 query → organization overrides
1 query → office overrides
1 query → user overrides

and resolve precedence in memory.

This is an important distinction between a good consumer API and a good persistence strategy. The former may look like individual getters while the latter should remain batch-aware.

Configuration metadata can drive the frontend

Once definitions and resolved values are available, the backend can assemble a dedicated response DTO.

The constraint portion is intentionally type-dependent:

public record SettingView<T>(
    String code,
    String label,
    String description,
    SettingDataType type,
    T explicitValue,
    T effectiveValue,
    SettingSource source,
    boolean editable,
    Map<String, Object> constraints
) {}

For an integer setting, constraints might contain:

{
  "minimum": 15,
  "maximum": 120
}

For a string:

{
  "pattern": "^[A-Z0-9_-]+$",
  "maxLength": 50
}

For an enum:

{
  "allowedValues": [
    "EMAIL",
    "SMS",
    "NONE"
  ]
}

So an APPOINTMENT_DURATION response could look like:

{
  "code": "APPOINTMENT_DURATION",
  "label": "Appointment duration",
  "description": "Default duration for appointments",
  "type": "INTEGER",
  "explicitValue": null,
  "effectiveValue": 30,
  "source": "TENANT",
  "editable": true,
  "constraints": {
    "minimum": 15,
    "maximum": 120
  }
}

This DTO is intentionally different from ResolvedSetting<T>.

ResolvedSetting<T> represents resolution semantics.

SettingView<T> joins:

canonical specification metadata;
persisted definition metadata;
resolved values;
authorization state;
presentation-specific constraints.

The frontend can now render the correct control, apply basic validation, indicate inheritance, and decide whether a reset action should be available.

Dynamic UI is useful, but it also means the setting catalog has become part of the backend/frontend contract.

Make testing cheap

A configuration abstraction becomes painful if every unit test has to create database rows.

Business code should depend on the small Settings facade:

public interface Settings {

    int getInteger(
        SettingSpec<Integer> spec,
        SettingContext context
    );

    boolean getBoolean(
        SettingSpec<Boolean> spec,
        SettingContext context
    );
}

A test can then replace it with a simple in-memory implementation:

Settings settings = new InMemorySettings()
    .with(
        APPOINTMENT_DURATION,
        45
    );

The scheduling service should not care whether production obtained 45 from PostgreSQL, Redis, an office override, or a tenant fallback.

Resolver behavior can be tested separately with focused integration tests covering precedence, reset semantics, disabled definitions, invalid values, and unauthorized overrides.

A settings framework should reduce coupling, not make configuration a prerequisite for every test fixture.

Caching inherited settings is harder than caching rows

Settings are typically read much more often than they are changed, so caching is attractive.

Hierarchy complicates invalidation.

Suppose office A inherits APPOINTMENT_DURATION = 30 from tenant T. The resolved result is cached. Tenant T then changes its value to 20.

Nobody changed office A, but its cache entry is now stale.

One practical strategy is to maintain configuration generations per owner:

platform version: 12
tenant T version: 7
office A version: 3

A cache key for the resolved value can include the relevant generation vector:

APPOINTMENT_DURATION
tenant=T:v7
office=A:v3

When the tenant changes, its generation becomes v8. Old entries no longer match without having to enumerate every descendant office immediately.

There are other valid cache strategies, but they all need to understand the same inheritance model as the resolver.

If caching is designed independently from ownership, stale configuration will eventually become a correctness bug.

Settings are not feature flags

A settings system can look similar to a feature-flag system, but the product semantics are usually different.

A feature flag is primarily about rollout and targeting:

Enable the new booking flow for 10% of users.
Enable feature X only in staging.
Enable the redesigned page for internal accounts.

Flags are often engineer-owned and intentionally temporary.

A business setting represents persistent configuration:

This office uses 45-minute appointments.
This tenant sends reminders 24 hours before a visit.
This organization allows online booking.

Settings are usually ownership-driven and long-lived.

The underlying infrastructure can overlap, but treating permanent business configuration as disposable feature flags — or temporary rollout flags as permanent settings — creates lifecycle problems later.

Not all configuration belongs in the settings system

A generic settings subsystem should not become the dumping ground for every configurable value.

Deployment configuration includes database URLs, service addresses, OAuth credentials, and infrastructure secrets. These generally belong in deployment tooling and secret-management systems.

Technical application configuration includes cache TTLs, scheduler intervals, HTTP limits, or thread-pool sizing. These often belong in application configuration or environment variables.

Business configuration includes appointment duration, booking policy, office preferences, and reminder behavior. These are the strongest candidates for runtime settings because a business actor owns the decision.

There is also sensitive business configuration. A tenant-specific SMS sender name may fit naturally into the settings model, while the tenant's SMS provider API key should not be exposed or persisted like an ordinary string. A settings system may store an encrypted value or, preferably where appropriate, a reference to a secret-management system.

Ownership and sensitivity are separate dimensions. “The tenant controls it” does not mean “store it as plaintext in setting_values.”

The final `APPOINTMENT_DURATION` model

Our original field was:

private int appointmentDuration;

The final design looks very different.

Code declares the behavioral contract:

public static final SettingSpec<Integer> APPOINTMENT_DURATION =
    SettingSpec.integer("APPOINTMENT_DURATION")
        .defaultValue(30)
        .minimum(15)
        .maximum(120)
        .allowOverrideAt(
            SettingScope.TENANT,
            SettingScope.OFFICE
        )
        .build();

A SettingCatalog registers that spec and makes it enumerable.

A migration creates the persisted definition and lifecycle metadata.

Startup reconciliation verifies that the persisted definition is compatible with the spec.

An office may store an explicit override:

definition: APPOINTMENT_DURATION
scope: OFFICE
owner: office-123
value: 45

Business code asks the facade for the effective value:

int duration = settings.getInteger(
    APPOINTMENT_DURATION,
    context
);

Internally, the resolver might produce:

explicitValue = 45
effectiveValue = 45
source = OFFICE

If the office resets its configuration and the tenant has 20:

explicitValue = null
effectiveValue = 20
source = TENANT

If neither scope defines an override:

explicitValue = null
effectiveValue = 30
source = PLATFORM_DEFAULT

The write path validates the candidate value, checks whether the requested scope is permitted, verifies authorization, persists the override, records the change, updates cache generations, and emits domain events where needed.

The reset path goes through the same lifecycle but removes the override, restoring inheritance instead of persisting the current effective value.

The read path resolves hierarchy without exposing that hierarchy to business services.

The bulk read path performs the same resolution without generating hundreds of database calls.

The catalog joins code-owned specifications with database-owned lifecycle and presentation metadata.

That is no longer “a key and a value in a table.”

It is a configuration domain.

When should you build this?

Probably later than you think.

If your application has a few stable properties, keep explicit fields. They are easier to understand and harder to misuse.

A dedicated settings subsystem starts making sense when several concerns appear together: runtime modification, ownership hierarchy, inheritance, overrides, explicit versus effective values, authorization differences, dynamic interfaces, frequent definition changes, validation metadata, auditing, or lifecycle requirements.

The warning sign is not that you have many settings.

It is that every new setting requires another special rule, and those rules are spreading across unrelated services.

When that happens, configuration has developed behavior of its own.

It needs a boundary.

Conclusion

The hard part of a setting is rarely storing true, 30, or "Africa/Casablanca".

The hard part is defining what that value means when it is absent, inherited, overridden, reset, validated, secured, cached, changed, or retired.

That is the hidden cost behind:

“Just add a setting.”

Once those rules exist, the setting is no longer just configuration.

It is part of your domain.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Stop Creating an Endpoint for Every Button

Ismail ZAHIR — Mon, 07 Sep 2026 13:30:23 +0000

There is a pattern that feels completely natural when building an API.

The frontend gets an Approve button, so the backend gets an endpoint:

POST /appointments/42/approve

Then more requirements arrive:

POST /appointments/42/reject
POST /appointments/42/cancel
POST /appointments/42/archive

Each endpoint makes sense individually. The intent is explicit, authorization can be attached to individual operations, and OpenAPI documents exactly what the client can call.

But as the workflow grows, so does the controller:

@PostMapping("/{id}/approve")
@PostMapping("/{id}/reject")
@PostMapping("/{id}/cancel")
@PostMapping("/{id}/archive")
@PostMapping("/{id}/mark-missed")

When several of these methods eventually do little more than validate a transition and assign a different status, I start asking a different question:

Am I exposing real domain operations, or am I turning every UI action into an HTTP endpoint?

That distinction matters more than whether a URL contains a verb.

Start with the domain, not the button

Imagine an appointment with these states:

public enum AppointmentStatus {
    PENDING,
    APPROVED,
    REJECTED,
    CANCELED,
    MISSED,
    ARCHIVED
}

The frontend might expose Approve, Reject, and Cancel buttons, but those buttons are only one way of interacting with the workflow.

MISSED, for example, might not come from a button at all. A scheduled process could detect appointments whose time has passed and transition them automatically. Another client might expose the workflow through a menu, while an integration might have no UI at all.

The domain still contains the same states and transition rules.

That was the useful shift for me:

The UI triggers domain behavior, but it shouldn't define the domain model.

When status really is the resource being changed

If several operations fundamentally mean "move this resource into another valid state," exposing the transition directly can make sense:

PATCH /appointments/42/status

{
  "status": "APPROVED"
}

There are plenty of workflows where this model is natural:

DRAFT → ACTIVE
ACTIVE → INACTIVE

OPEN → CLOSED
CLOSED → ARCHIVED

The transition has no special payload and no independent business meaning beyond moving the resource through its lifecycle.

Appointments can contain transitions like this too. The endpoint describes the requested state rather than mirroring whichever button happened to trigger it.

But accepting a target status should not turn the application into unrestricted CRUD:

.                ┌──→ REJECTED
                 │
PENDING ─────────┼──→ CANCELED
                 │
                 └──→ APPROVED
                         │
                         ├──→ CANCELED
                         ├──→ MISSED
                         └──→ ARCHIVED

CANCELED → APPROVED might be forbidden. APPROVED → MISSED might only become valid after the appointment time.

Once those rules exist, status is no longer just an enum field. It is part of a state machine.

For rules that depend only on aggregate state, the model can remain simple:

public void transitionTo(AppointmentStatus target) {
    if (!canTransitionTo(target)) {
        throw new InvalidStatusTransitionException(status, target);
    }

    this.status = target;
}

When a transition carries its own contextual invariant, a named domain method often becomes clearer:

public void markMissed(Instant now) {
    if (status != AppointmentStatus.APPROVED) {
        throw new InvalidStatusTransitionException(
            status,
            AppointmentStatus.MISSED
        );
    }

    if (scheduledAt.isAfter(now)) {
        throw new TransitionNotYetAllowedException(
            AppointmentStatus.MISSED,
            scheduledAt
        );
    }

    this.status = AppointmentStatus.MISSED;
}

The application layer can obtain now from an injected Clock, perform authorization, and orchestrate persistence while the aggregate protects the transition invariant.

That distinction between uniform transitions and operations with their own inputs or invariants will matter again in a moment.

Don't replace many endpoints with one god endpoint

Once endpoint proliferation becomes visible, the opposite extreme is tempting:

POST /appointments/42/action

{
  "action": "APPROVE"
}

Soon it becomes:

{
  "action": "SEND_REMINDER"
}

or:

{
  "action": "RESCHEDULE",
  "date": "2026-09-10T10:30:00"
}

Now /action is an RPC dispatcher with an increasingly polymorphic request schema.

Approve, cancel, reschedule, send a reminder, export, and generate a document do not become the same operation because they share an endpoint.

Consolidation only helps when the operations actually share semantics.

The strongest counterexample: different transitions need different data

This is where a generic status endpoint starts becoming less attractive.

Approval might require nothing more than:

{
  "status": "APPROVED"
}

But rejection might require a reason:

{
  "status": "REJECTED",
  "reason": "Provider unavailable"
}

Cancellation might require a reason and information related to the cancellation policy.

Trying to force all of that through one request eventually produces something like:

{
  "status": "CANCELED",
  "reason": "...",
  "refundPolicy": "...",
  "comment": null
}

Now the schema contains fields that are optional syntactically but conditionally required semantically:

if status == REJECTED → reason required
if status == CANCELED → reason required

At that point, the generic endpoint may be hiding domain concepts rather than simplifying them.

This gives me a useful heuristic:

When a transition needs its own meaningful payload, it is often a domain command wearing a status change.

Cancellation might therefore deserve:

POST /appointments/42/cancel

with its own contract:

{
  "reason": "Schedule conflict"
}

Internally, that doesn't have to mean:

appointment.setStatus(CANCELED);

The domain can expose the operation explicitly:

appointment.cancel(reason);

while simpler lifecycle transitions can still use:

appointment.transitionTo(target);

That's the distinction I find useful: uniform lifecycle transitions can share a transition abstraction; operations with their own inputs or invariants can become named domain behavior.

And this is also why I wouldn't invent a RESCHEDULED status just to fit rescheduling through the same endpoint. Rescheduling changes the appointment's schedule. It is behavior, not necessarily another lifecycle state.

Some status changes are really outcomes

Consider:

POST /invoices/42/send

Sending an invoice might generate a document, create an immutable snapshot, contact an external mail provider, record a delivery attempt, and publish an event.

Reducing all of that to:

PATCH /invoices/42/status

{
  "status": "SENT"
}

misrepresents what the client is asking the system to do.

The request isn't "make this field equal SENT." It is send this invoice. SENT is an outcome of the operation.

The same reasoning applies to:

POST /orders/{id}/refund
POST /reports/{id}/generate
POST /users/{id}/reset-password

Trying to eliminate verbs simply for REST purity can make an API less expressive.

Valid doesn't mean authorized

There is another dimension that shouldn't be hidden inside the state machine.

Suppose this transition is valid:

APPROVED → MISSED

That doesn't mean every authenticated user is allowed to perform it.

A provider might be allowed to mark an appointment as missed. The patient probably shouldn't be able to mark their own appointment as missed. A scheduled system process might also be authorized to perform the same transition.

So I treat these as separate questions:

Is APPROVED → MISSED a valid domain transition?

                 ≠

Is this actor allowed to perform it?

The aggregate can protect its lifecycle invariants, while the application or authorization layer determines whether the current actor is permitted to request the operation.

A transition can therefore be valid but unauthorized.

This also closes one apparent advantage of action endpoints from the introduction. Having /approve and /cancel gives you convenient places to attach different authorization rules, but the URL shape itself doesn't solve authorization. A generic transition endpoint can still authorize based on the actor, the current resource, and the requested transition.

That distinction becomes particularly important when the API tells clients which operations are currently available.

How does the frontend know what's allowed?

Explicit action endpoints have an advantage: discoverability.

If OpenAPI exposes:

POST /approve
POST /reject
POST /cancel

the operations are visible at design time.

With:

PATCH /status

the schema might tell the client which status values exist without telling it which transitions are valid from the current state for the current caller.

The naive solution is to reproduce the workflow in Angular:

if (appointment.status === 'PENDING') {
  // show approve/reject/cancel
}

But now the frontend contains another copy of business rules that already exist on the backend.

For simple workflows, the API can expose permitted transitions:

{
  "id": "42",
  "status": "PENDING",
  "allowedTransitions": [
    "APPROVED",
    "REJECTED"
  ]
}

Notice that CANCELED is absent here even though it is structurally valid from PENDING. That could be intentional: this representation is for the current caller, not merely a dump of every transition in the state machine.

For richer workflows, operation descriptors can span both state transitions and commands:

{
  "id": "42",
  "status": "PENDING",
  "actions": [
    {
      "rel": "approve",
      "method": "PATCH",
      "href": "/appointments/42/status",
      "body": {
        "status": "APPROVED"
      }
    },
    {
      "rel": "cancel",
      "method": "POST",
      "href": "/appointments/42/cancel"
    }
  ]
}

The exact representation isn't the important part. The principle is: the backend should remain authoritative about what the current caller can do.

The frontend can use that information to render controls without reproducing the entire state machine. And none of this replaces server-side authorization; clients can construct arbitrary requests, so the server still validates every operation.

At this point, the modeling question is mostly settled. The remaining question is whether the chosen design behaves correctly when requests fail, overlap, or get retried.

Failure semantics matter too

A generic endpoint doesn't require generic errors.

These are three different failures:

CANCELED → APPROVED
The transition itself is not allowed.

PENDING → APPROVED by this actor
The transition is valid, but the actor isn't authorized.

PENDING → APPROVED against an old resource version
The request was valid, but the resource changed first.

They should remain distinguishable to the client.

An authorization failure naturally maps to 403 Forbidden. An invalid domain transition can be represented as a domain conflict such as 409 Conflict, or 422 Unprocessable Content if that convention better matches the API. A failed If-Match precondition has the more specific 412 Precondition Failed.

The exact status-code policy should be consistent across the API. What matters here is that consolidating several state changes behind one endpoint doesn't mean collapsing their failure semantics into a generic "status update failed" response.

State transitions have a concurrency problem

Consider:

Appointment appointment = repository.findById(id);
appointment.transitionTo(target);
repository.save(appointment);

Now two requests arrive almost simultaneously. One coordinator approves the appointment while another cancels it.

Both load:

status = PENDING

Both transitions are individually valid, so both pass validation. Without concurrency control, the last write can silently overwrite the first.

For JPA applications, optimistic locking is one common protection:

@Version
private long version;

At the HTTP layer, an ETag combined with If-Match can express the same expectation while keeping the precondition in HTTP metadata.

For state-machine APIs, another option is to make the expected state explicit in the request:

{
  "from": "PENDING",
  "status": "APPROVED"
}

Conceptually, that is a domain-level compare-and-swap:

Change this to APPROVED, but only if it is still PENDING.

The trade-off is partly about layering. If-Match keeps the precondition at the transport level, but usually works with a version or opaque ETag. A from field expresses the expected domain state directly, but puts that precondition into the request body.

They also detect different things: an ETag or version can detect any relevant resource modification, while from only expresses an expectation about the current workflow state.

If a conflict is detected, blindly retrying inside the service is dangerous. The resource should be re-read and the operation reconsidered against its new state.

Validating a transition isn't enough if the state you validated is no longer current when you commit it.

Commands have the mirror-image problem: retries

State transitions force us to think about concurrent updates. Commands with external side effects force us to think about duplicate execution.

Consider:

POST /invoices/42/send

The server successfully sends the email, but the client times out before receiving the response and retries. Without protection, the customer may receive the invoice twice.

Depending on the operation, idempotency might involve an idempotency key, a persisted command identifier, or checking whether the operation has already completed.

So the two sides of the design have related correctness concerns:

State transition → Is the state I am changing still current?

Domain command  → Have I already executed this request?

Choosing the right HTTP shape doesn't solve either problem. It makes the semantics clearer so they can be handled deliberately.

Remove the UI and ask again

When I'm unsure about an endpoint, I find it useful to mentally remove the frontend.

Operations such as generate report, refund order, and send invoice clearly still exist without a button.

Now consider Archive. Is archiving a meaningful business operation with its own inputs, invariants, and side effects? Or is ARCHIVED simply another lifecycle state?

There is no universal answer, and that's the point.

The API shouldn't acquire /archive merely because somebody added an Archive button. The operation should exist because the domain gives "archive" that meaning.

MISSED makes the distinction particularly clear. If a scheduled job can move an appointment into that state, the workflow exists independently of any button that might also expose it.

The rule I use now

When a frontend requirement arrives, I try not to start with:

What endpoint does this button need?

I start with:

What happened in the domain?

If the answer is simply:

This resource moved from one valid lifecycle state to another.

then a state-oriented API such as:

PATCH /appointments/{id}/status

may be the clearest representation.

If the answer is:

The system performed a business operation with its own inputs, invariants, or side effects.

then an explicit command may be the better abstraction.

That doesn't mean verbs in URLs are bad. It doesn't mean every status deserves PATCH. And it doesn't mean the HTTP contract has to mirror the internal domain API method for method.

The rule I ended up with is simpler:

Don't create an endpoint because a button exists. Create it because the domain operation exists.

Buttons change. Clients change. Some transitions eventually happen without a user at all.

The domain is the more stable boundary.

That's the boundary I want the API to represent.

Originally published on ZyVOP

💡 For more articles like this, subscribe to the ZyVOP newsletter!

My Pull Request Failed — Because GitHub Actions Was Protecting the Repository

Ismail ZAHIR — Fri, 04 Sep 2026 13:47:07 +0000

Sometimes the most useful security lessons don't start with a security audit.

They start with a failed CI job.

Recently, while contributing to an open-source project, I opened a pull request and expected the usual sequence:

checkout → install → build → test

Instead, the workflow stopped at actions/checkout.

The error was surprisingly explicit:

Refusing to check out fork pull request code from a pull_request_target workflow.

At first, this looked like a CI configuration problem.

Maybe the checkout action needed another option. Maybe something had changed in a newer version.

There was even an escape hatch:

allow-unsafe-pr-checkout: true

Adding it would have been easy.

But the name alone should make you stop before doing that.

Why was checking out my pull request considered unsafe?

That question led me into an important GitHub Actions security boundary that is easy to miss:

on:
  pull_request:

and:

on:
  pull_request_target:

look similar.

They are not.

And choosing the wrong one can turn a normal CI workflow into a path for executing untrusted code with repository privileges.

The workflow looked perfectly normal

The project had a quality-check workflow for pull requests.

Simplified, its intent was something like this:

name: Quality Check

on:
  pull_request_target:
    branches:
      - main
    paths:
      - "src/**"
      - "tests/**"
      - "package.json"
      - "pnpm-lock.yaml"

jobs:
  quality:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      # install dependencies
      # build
      # lint
      # test

Nothing here immediately looks dangerous.

It's a pull request.

We want to test the pull request.

So we check out its code and execute the project's quality checks.

But there's a more important question than:

What commands does this workflow execute?

The question is:

Whose code are we executing, and what privileges does it have while running?

That changes the entire security model.

Two events with very different trust models

GitHub provides both:

pull_request

and:

pull_request_target

They both respond to pull request activity, but they exist for different purposes.

Understanding that difference requires thinking about trusted and untrusted code.

`pull_request`: run CI against the proposed change

For a normal CI workflow, we might write:

name: Quality Check

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  quality:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - run: npm ci
      - run: npm test

This is the natural environment for:

build
lint
test
type-check
static analysis

because the workflow is supposed to process the code proposed by the contributor.

For pull requests coming from forks, GitHub applies restrictions to protect the target repository.

The important mental model is:

        Contributor's PR
               │
               ▼
        pull_request
               │
               ▼
      Restricted context
               │
               ▼
        Checkout PR code
               │
               ▼
      Build / lint / test

The code is untrusted.

And the environment is designed accordingly.

`pull_request_target` solves a different problem

Now consider:

on:
  pull_request_target:

The word target is important.

A pull_request_target workflow executes using the context of the base repository.

Its workflow definition comes from the trusted base branch rather than from the contributor's pull request.

That makes it useful for operations that need to interact with the repository while responding to an external pull request.

For example:

apply labels
comment on a PR
triage contributions
manage PR metadata
perform privileged repository automation

Conceptually:

        Contributor's PR
               │
               ▼
    pull_request_target
               │
               ▼
      Trusted base context
               │
               ▼
      Manage the pull request

Notice what's missing.

We aren't executing the contributor's application code.

That's intentional.

The problem starts when those worlds are mixed

Imagine this workflow:

name: PR Check

on:
  pull_request_target:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - run: npm ci
      - run: npm test

We've now changed the architecture.

The workflow runs in a trusted context.

Then we explicitly fetch code controlled by the pull request author.

Then we execute it.

The trust boundary becomes:

┌───────────────────────────────┐
│       UNTRUSTED SOURCE        │
│                               │
│   Pull request from a fork    │
└──────────────┬────────────────┘
               │
               │ checkout PR code
               ▼
┌───────────────────────────────┐
│        TRUSTED CONTEXT        │
│                               │
│      pull_request_target      │
│                               │
│  GITHUB_TOKEN                 │
│  repository secrets           │
│  cache scope                  │
│  runner access                │
└──────────────┬────────────────┘
               │
               │ npm ci
               │ npm test
               ▼
        Untrusted code runs
        inside trusted context

That's the dangerous combination.

Repository code is executable input

This is the part that's easy to underestimate.

You might look at:

- run: npm ci

and think:

I'm only installing dependencies.

But dependency installation can execute lifecycle scripts.

Or:

- run: npm test

and think:

I'm only running tests.

But who controls the tests?

The pull request does.

The same applies to:

npm run build
pnpm install
make
./scripts/check.sh

A contributor may be able to modify:

package.json
build scripts
test files
Makefiles
configuration
dependencies
shell scripts

So when a CI job checks out a pull request, the repository itself needs to be treated as potentially executable input.

That gives us the dangerous equation:

UNTRUSTED CODE
      +
PRIVILEGED WORKFLOW
      =
SECURITY BOUNDARY VIOLATION

This is known as a "pwn request"

GitHub Security Lab describes this class of vulnerability as a pwn request.

The problem isn't that pull_request_target itself is insecure.

That's an important distinction.

The dangerous pattern is:

pull_request_target
        +
checkout untrusted PR
        +
execute that PR

pull_request_target has legitimate uses.

The vulnerability appears when the trusted and untrusted execution models are combined incorrectly.

And now `actions/checkout` actively protects against it

This is what made my failed CI job particularly interesting.

Recent versions of actions/checkout include protection against this exact pattern.

When a workflow running under a privileged event such as:

pull_request_target

tries to check out code from an external fork, actions/checkout can refuse the operation.

That's why I saw the error.

The action even provides an explicit opt-out:

- uses: actions/checkout@v5
  with:
    allow-unsafe-pr-checkout: true

But look carefully at that property name:

allow-unsafe-pr-checkout

Not:

allow-fork-checkout

Not:

enable-pr-checkout

GitHub is deliberately making the security implication visible.

The option exists for cases where someone has carefully evaluated the trust boundary and genuinely needs the behavior.

It should not be the default fix for a failing CI pipeline.

My first question became: why does this workflow need `pull_request_target`?

The workflow wasn't publishing a package.

It wasn't deploying anything.

It wasn't modifying repository contents.

It wasn't performing privileged PR management.

It was running quality checks.

In other words:

checkout
   ↓
install
   ↓
build
   ↓
lint
   ↓
test

That's exactly what pull_request is designed for.

So instead of bypassing the protection:

allow-unsafe-pr-checkout: true

the fix was to change the trust model.

Before

The relevant part looked conceptually like this:

name: Quality Check

on:
  push:
    branches:
      - main

  pull_request_target:
    branches:
      - main
    paths:
      - "src/**"
      - "tests/**"
      - "package.json"
      - "pnpm-lock.yaml"

jobs:
  quality:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      # install
      # lint
      # test

For a workflow whose purpose is to execute the proposed changes, pull_request_target introduces a privileged context that isn't required.

After

The change is almost boring:

name: Quality Check

on:
  push:
    branches:
      - main

  pull_request:
    branches:
      - main
    paths:
      - "src/**"
      - "tests/**"
      - "package.json"
      - "pnpm-lock.yaml"

permissions:
  contents: read

jobs:
  quality:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      # install
      # lint
      # test

The important change is just:

- pull_request_target:
+ pull_request:

And I would also make the permissions required by the CI job explicit:

permissions:
  contents: read

The YAML change is tiny.

The architectural change isn't.

Before and after: the actual security model

The security model before

                    Fork PR
                       │
                       ▼
              pull_request_target
                       │
             trusted base context
                       │
                       ▼
                checkout PR
                       │
                       ▼
                execute code
                       │
                       ▼
              ⚠ trust boundary
                 has been crossed

The security model after

                    Fork PR
                       │
                       ▼
                 pull_request
                       │
               restricted context
                       │
                       ▼
                checkout PR
                       │
                       ▼
              build / lint / test
                       │
                       ▼
                 CI result

Now the execution model matches the purpose of the workflow.

The lesson isn't "`pull_request_target` is bad"

That would be the wrong conclusion.

A better rule is:

Choose the event based on the trust level required by the job.

Consider two workflows.

Workflow A

It needs to:

checkout contributor code
install dependencies
compile
run tests
run linting

That's untrusted-code execution.

Use a low-privilege context such as:

pull_request

Workflow B

It needs to:

label the PR
comment on it
perform triage
update repository metadata

It may need a trusted repository context.

That's where:

pull_request_target

can make sense.

But don't then casually checkout and execute the contributor's code.

A mental model I now use

When reviewing a GitHub Actions workflow, I ask two questions.

Question 1: Does this job execute contributor-controlled code?

That includes obvious commands:

- run: ./script-from-the-repository.sh

but also less obvious ones:

- run: npm ci
- run: npm test
- run: npm run build

If yes, I treat the job as executing untrusted code.

Then I ask:

Question 2: Does this job have privileged access?

For example:

repository write permissions
secrets
publishing credentials
deployment credentials
privileged caches
internal infrastructure
self-hosted runners

If the answer to both questions is yes, the workflow deserves immediate attention.

Does the job execute PR code?
             │
      ┌──────┴──────┐
      NO           YES
      │             │
      ▼             ▼
  Lower risk   Does it hold privileges?
                     │
              ┌──────┴──────┐
              NO           YES
              │             │
              ▼             ▼
          Lower risk    ⚠ REVIEW THIS

The goal is simple:

Don't combine untrusted code execution with unnecessary privileges.

Separate CI from privileged automation

Suppose a project genuinely needs both.

It wants to:

build and test external contributions;
perform privileged actions after those checks.

Don't automatically put everything into one privileged workflow.

Separate responsibilities.

Workflow 1: untrusted CI

name: PR CI

on:
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - run: npm ci
      - run: npm test

Its responsibility is:

Determine whether the proposed code works.

Nothing more.

Workflow 2: trusted automation

A separate trusted workflow can perform operations that genuinely require additional permissions.

For example:

name: PR Metadata

on:
  pull_request_target:

permissions:
  contents: read
  pull-requests: write

jobs:
  metadata:
    runs-on: ubuntu-latest

    steps:
      # Work with PR metadata.
      # Do not execute contributor-controlled code.

Its responsibility is:

Manage the pull request.

Not:

Execute the pull request.

That distinction dramatically simplifies the security model.

For more complex cases where privileged work must happen after untrusted CI, GitHub also documents patterns using separate workflows such as workflow_run. But artifacts crossing from an untrusted workflow into a privileged one still need to be treated as untrusted data.

`permissions` is part of the architecture too

Changing the event is only part of hardening a workflow.

GitHub Actions provides a GITHUB_TOKEN, and its permissions should follow the principle of least privilege.

A CI workflow often needs little more than:

permissions:
  contents: read

A PR-management workflow might legitimately need:

permissions:
  contents: read
  pull-requests: write

A release workflow might need:

permissions:
  contents: write

The important question is not:

What permissions might this workflow eventually need?

It's:

What is the minimum permission this job needs to perform its responsibility?

A linter doesn't need to create releases.

A test suite doesn't need deployment credentials.

A build shouldn't receive package-publishing credentials just because another job publishes packages.

Permissions should follow responsibilities.

Secrets aren't the only thing worth protecting

It's tempting to think:

We don't use any secrets, so executing the PR here is fine.

That's incomplete.

The security boundary can include more than explicit secrets.

Depending on the workflow, there may also be:

GITHUB_TOKEN permissions
repository access
cache state
artifacts
package credentials
deployment environments
runner infrastructure

And self-hosted runners deserve particular attention.

If arbitrary external code runs on infrastructure connected to private systems, the threat model is very different from an isolated disposable GitHub-hosted runner.

So the right question isn't just:

Can this pull request read MY_SECRET?

It's:

What can the environment access or modify while contributor-controlled code is running?

CI configuration is security architecture

One thing changed for me after investigating this issue.

I no longer see this:

on:
  pull_request_target:

as merely a CI trigger.

And I don't see this:

permissions:
  contents: write

as merely configuration.

Or this:

ref: ${{ github.event.pull_request.head.sha }}

as merely checkout behavior.

Together, these settings answer fundamental security questions:

Who controls the code?

Which version of the workflow runs?

Which credentials are available?

What can the job modify?

Which infrastructure can it access?

That's a security model.

Just written in YAML.

Why the failed pipeline was useful

The easiest response to my original failure would have been:

allow-unsafe-pr-checkout: true

The CI probably would have moved past the checkout step.

But the security warning wasn't the problem.

The workflow architecture was.

The better question was:

Why is a quality-check workflow asking to execute untrusted fork code inside a privileged context?

Once phrased that way, the solution became obvious.

It didn't need that context.

So I changed:

pull_request_target

to:

pull_request

and let the CI execute the proposed code in the security context intended for it.

Final takeaway

The one-line fix wasn't the interesting part.

This was:

- pull_request_target:
+ pull_request:

The interesting part was understanding why that line matters.

My rule now is simple:

Never execute untrusted pull request code with privileges it doesn't need.

Use pull_request when the job exists to build, lint, analyze, or test contributor code.

Use pull_request_target when you genuinely need the trusted base-repository context for PR automation — and keep contributor-controlled code out of that execution path.

Define explicit permissions.

Separate untrusted CI from privileged automation.

And when a security mechanism blocks something in your pipeline, don't immediately search for the flag that disables it.

First ask why the protection exists.

In my case, a failed checkout wasn't GitHub Actions getting in the way.

It was GitHub Actions pointing at a security boundary I hadn't paid enough attention to.

And that made the failed CI job more useful than a successful one would have been.

References

GitHub Docs — Secure use reference, including guidance for mitigating untrusted code checkout in privileged workflows.
GitHub Docs — Securely using pull_request_target, covering its trust model, fork checkout risks, hardening, and the allow-unsafe-pr-checkout protection.
GitHub Security Lab — Keeping your GitHub Actions and workflows secure: Preventing pwn requests, with examples of how privileged PR workflows can become vulnerable.
actions/checkout — current documentation for the built-in protection against unsafe fork PR checkout.

Originally published on ZyVOP

💡 For more articles like this, subscribe to the ZyVOP newsletter!

I Built an Angular Authentication Layer for the Signals Era

Ismail ZAHIR — Mon, 31 Aug 2026 18:03:08 +0000

Authentication is one of those concerns that quickly spreads across an Angular application.

A component needs to know whether the user is authenticated. A route needs authorization rules. HTTP requests need access tokens. The application needs to react when a session expires. Tests need to simulate authenticated and unauthenticated users.

And once an identity provider such as Keycloak is introduced, it becomes very easy for provider-specific concepts to leak into the rest of the application.

I wanted a different approach.

So I built ngx-auth-client, an Angular authentication library designed around Angular signals, a provider-agnostic authentication layer, functional route guards, in-memory token handling, and testability.

The goal wasn't to create another wrapper around an identity provider.

The goal was to create an authentication layer that belongs to the Angular application rather than to a particular authentication provider.

The application should depend on authentication capabilities, not on the identity provider implementing them.

If you want to follow along with the implementation, you can install the library with:

npm install @ismailza/ngx-auth-client keycloak-js

Then import the pieces you need:

import {
  provideAuth,
  authGuard,
  authTokenInterceptor
} from '@ismailza/ngx-auth-client';

import { withKeycloak } from '@ismailza/ngx-auth-client/keycloak';
import { withFakeAuth } from '@ismailza/ngx-auth-client/testing';

There is an important detail in that installation command.

keycloak-js is an optional peer dependency. The core package has no identity-provider dependency. Only the /keycloak entry point requires it.

That distinction is not just a packaging detail. It is part of the architecture.

This is the story of the decisions behind the project.

Why build another authentication library?

Angular applications already have many ways to implement authentication.

You can integrate an identity provider directly, use an SDK, write your own authentication service, or build a small abstraction around an existing provider.

I've used the direct integration approach before.

It works.

Until authentication starts appearing everywhere.

You might end up with code such as:

if (keycloak.authenticated) {
  // ...
}

or:

const token = await keycloak.updateToken();

or:

keycloak.login();

The problem isn't that these APIs are bad.

The problem is that the application starts knowing which authentication provider it is using.

Your components, route guards, interceptors, and services become coupled to Keycloak.

I wanted to move that dependency to the edge of the architecture.

Instead of:

Angular Application
        ↓
     Keycloak

I wanted:

Angular Application
        ↓
 Authentication Layer
        ↓
 Authentication Provider

That distinction became the foundation of ngx-auth-client.

Authentication state should be Angular state

One of the first decisions I made was to make authentication state reactive using Angular signals.

Instead of exposing authentication state through imperative getters, the library exposes it as reactive state:

auth.authenticated()
auth.claims()
auth.roles()
auth.profile()

A component can consume that state directly:

@Component({
  template: `
    @if (auth.authenticated()) {
      <p>Welcome back!</p>
    } @else {
      <p>Please sign in.</p>
    }
  `
})
export class HomeComponent {
  protected readonly auth = inject(AuthService);
}

The important part isn't the syntax.

It's that authentication becomes normal reactive application state.

When authentication changes, Angular can react naturally. A component doesn't need to subscribe to provider-specific authentication events just to keep its UI synchronized.

One service for application code

AuthService is the single thing application code needs to inject.

It adds several application-facing capabilities on top of the underlying provider port:

initialization state with ready(), initError(), and whenReady()
capability detection such as canRegister()
role predicates such as hasRole(), hasAnyRole(), and hasAllRoles()

The underlying provider contract remains deliberately small.

Setting everything up is a single provider call:

export const appConfig: ApplicationConfig = {
  providers: [
    provideAuth(
      withKeycloak({
        url,
        realm,
        clientId
      })
    ),

    provideHttpClient(
      withInterceptors([authTokenInterceptor])
    ),

    provideRouter(routes)
  ]
};

Bootstrap doesn't have to wait for authentication

One subtle design decision is how initialization works.

The application doesn't block bootstrap while the authentication session is restored.

The adapter starts initialization as soon as the injector is created. whenReady() resolves when initialization settles, and the route guard waits for that before making an authorization decision.

That means unprotected application UI can render immediately while protected routes still wait for authentication state to become reliable.

This avoids a common race condition:

Application starts
       ↓
Authentication restoration starts
       ↓
Protected route evaluates too early
       ↓
User appears unauthenticated
       ↓
Incorrect redirect

The guard instead follows:

Application starts
       ↓
Authentication restoration starts
       ↓
Protected route waits for readiness
       ↓
Authentication decision

A small profile detail

profile() is null until loadProfile() is called.

Adapters load the profile lazily, so:

auth.profile()?.email

won't display anything until the profile has actually been loaded.

This is intentional. Authentication state and profile loading are different concerns.

Designing around `AuthProvider`

Once I decided that the application shouldn't depend directly on Keycloak, I needed an abstraction.

That's AuthProvider.

The architecture looks like this:

                   Angular Application
                           |
                           v
                      AuthService
                           |
                           v
                      AuthProvider
                       /        \\
                      v          v
              Keycloak       Other Provider
               Adapter          Adapter

The application interacts with the authentication layer.

The authentication layer interacts with an AuthProvider.

The provider handles the identity-provider-specific implementation.

The port is deliberately small:

interface AuthProvider {
  readonly authenticated: Signal<boolean>;
  readonly claims: Signal<Claims | null>;
  readonly roles: Signal<readonly string[]>;

  init(): Promise<void>;
  getToken(): Promise<string>;
  login(options?: LoginOptions): Promise<void>;
  logout(options?: LogoutOptions): Promise<void>;
}

Being able to show the entire contract on one screen is part of the argument.

This is the entire surface that the core, the guard, and the interceptor are allowed to depend on.

There is one rule that shaped the split:

State is signals, operations are promises.

The distinction is state versus action.

For example, authentication status is state:

authenticated()

Token refresh is an operation:

getToken()

A token refresh shouldn't become another piece of application state that every consumer needs to understand.

Keycloak is an adapter, not the architecture

I intentionally didn't make Keycloak the center of the library.

It's a provider adapter exposed through its own entry point:

ngx-auth-client
│
├── Core
│   ├── AuthService
│   ├── AuthProvider
│   ├── authGuard
│   └── authTokenInterceptor
│
├── Keycloak
│   └── KeycloakAuthProvider
│
└── Testing
    └── FakeAuthProvider

This is essentially the Ports and Adapters pattern.

AuthProvider is the port.

The provider implementations are adapters.

Identity providers are infrastructure. The application should depend on authentication concepts, not infrastructure-specific APIs.

If tomorrow the application needs another identity provider, the goal is to implement another adapter rather than rewrite authentication logic throughout the application.

The boundary isn't only TypeScript

This is the part I care about most.

A provider abstraction isn't very useful if the package itself still forces every consumer to install the provider SDK.

That's why the package structure matters.

The core package has no identity-provider dependency.

keycloak-js is an optional peer dependency and is only required by:

@ismailza/ngx-auth-client/keycloak

If an application never imports the Keycloak entry point, Keycloak isn't part of its dependency graph.

So the separation exists at two levels:

Architecture
    ↓
AuthProvider abstraction
    ↓
Provider adapters

and:

Package
    ↓
Core entry point
    ↓
Optional provider entry points

That's the difference between claiming a separation and actually shipping one.

Capabilities instead of one giant interface

There's a familiar failure mode in authentication abstractions.

It's tempting to create one huge interface containing every possible capability:

interface AuthProvider {
  login(): Promise<void>;
  logout(): Promise<void>;
  refresh(): Promise<void>;
  getToken(): Promise<string>;
  changePassword(): Promise<void>;
  linkAccount(): Promise<void>;
  // ...
}

But not every identity provider supports every operation.

Folding every provider's features into one interface forces adapters to implement methods they cannot support.

That's how multi-provider abstractions eventually become a lowest common denominator — followed by a getNativeClient() escape hatch.

I wanted to avoid that.

The core provider stays small, and additional functionality is represented as optional capabilities:

interface SupportsRegistration {
  register(options?: RegisterOptions): Promise<void>;
}

interface SupportsAccountManagement {
  accountManagement(): Promise<void>;
}

interface SupportsPasswordUpdate {
  updatePassword(options?: PasswordUpdateOptions): Promise<void>;
}

interface SupportsProfile {
  readonly profile: Signal<UserProfile | null>;
  loadProfile(): Promise<UserProfile>;
}

The core detects these capabilities through type guards.

AuthService then exposes the result as signals:

auth.canRegister()
auth.canManageAccount()
auth.canUpdatePassword()
auth.canLoadProfile()

That has a practical benefit.

The application can hide UI that the configured provider cannot actually deliver:

@if (auth.canRegister()) {
  <button (click)="auth.register()">
    Create an account
  </button>
}

And if application code calls an unsupported capability anyway, the library throws an UnsupportedCapabilityError that identifies the capability and the corresponding can* check.

Not a silent no-op.

Not a confusing:

undefined is not a function

The Keycloak adapter currently implements all four capabilities because Keycloak supports them.

It isn't stubbing methods just to satisfy a contract.

Don't force every authentication provider to implement capabilities it doesn't support.

Role normalization is what makes the port credible

Here's where "provider-agnostic" stops being a claim and becomes something you can point at.

Identity providers disagree about where roles live.

For example:

Keycloak can expose roles through realm_access and resource_access
Auth0 commonly uses a namespaced custom claim
Cognito can use cognito:groups
Microsoft Entra ID can expose application roles through roles

If that provider-specific structure reaches your Angular components, the abstraction has already failed.

So the rule is:

Role normalization belongs in the adapter.

The core only sees:

readonly roles: Signal<readonly string[]>;

Everything above the port speaks in roles.

Everything below it speaks the provider's vocabulary.

Keycloak role extraction

For Keycloak, the adapter can be configured to extract realm and resource roles:

withKeycloak({
  url,
  realm,
  clientId,
  roles: {
    realm: true,
    resource: ['my-app']
  }
});

resource: true takes roles from every client.

An explicit array takes roles only from the clients you name.

That distinction matters when several clients contain roles with the same name. Explicitly selecting the resource clients makes the authorization boundary easier to reason about.

Custom role mapping

If roles live somewhere non-standard, extraction can be overridden:

withKeycloak({
  url,
  realm,
  clientId,
  mapRoles: (claims) =>
    (claims['groups'] as string[] | undefined) ?? []
});

Now the rest of the application doesn't care where those roles came from.

That is the value of the adapter.

Route authorization: functional guards, `anyOf` and `allOf`

Authentication answers:

Who are you?

Authorization answers:

What are you allowed to access?

Knowing that a user is authenticated tells us nothing about whether they can access an administration page.

That's what the route guard handles.

Angular's functional APIs provide a clean way to express authorization through route metadata:

{
  path: 'admin',
  canActivate: [authGuard],
  data: {
    auth: {
      anyOf: ['admin', 'owner']
    }
  }
}

anyOf means:

admin OR owner

allOf requires every listed role:

{
  path: 'billing',
  canActivate: [authGuard],
  data: {
    auth: {
      allOf: ['admin', 'finance']
    }
  }
}

Which means:

admin AND finance

This keeps authorization requirements close to the route instead of scattering authorization logic throughout components.

What the guard actually does

The route configuration is the visible part.

The behavior underneath it is just as important.

1. It waits for authentication readiness

The guard awaits whenReady() before deciding whether the route can be activated.

This avoids a common hard-refresh race:

Page reload
   ↓
Session restoration starts
   ↓
Guard runs immediately
   ↓
authenticated = false
   ↓
Incorrect login redirect

Instead:

Page reload
   ↓
Session restoration starts
   ↓
Guard waits
   ↓
Session restoration settles
   ↓
Authorization decision

2. Unauthenticated users are redirected to login

When a user isn't authenticated, the guard redirects to the login flow with a return URL.

The goal is simple:

User requests /admin
       ↓
Not authenticated
       ↓
Login
       ↓
Return to /admin

3. Authenticated but unauthorized users are forbidden

A user can be authenticated and still lack the required permissions.

Those users are sent to the configured forbiddenRoute, which defaults to:

/forbidden

You can also set it to null if you want the guard to refuse activation without performing navigation.

4. Non-browser environments fail closed

On a non-browser platform, the guard returns false without attempting a login redirect.

Because the tokens are held in memory, there is no browser session available for the server to evaluate.

Rendering protected content into an SSR response could also create caching problems if that response is later served to another user.

Failing closed is therefore the safer behavior.

Requirements accumulate through the route tree

There's another detail that matters.

The guard doesn't look only at the leaf route.

It walks the route tree and accumulates authorization requirements.

For example:

{
  path: 'admin',
  canActivate: [authGuard],
  data: {
    auth: {
      anyOf: ['admin', 'owner']
    }
  },
  children: [
    {
      path: 'billing',
      data: {
        auth: {
          allOf: ['finance']
        }
      },
      loadComponent: () => import('./billing.component')
    }
  ]
}

The billing route inherits the parent requirement and adds its own.

Conceptually:

admin OR owner
        AND
      finance

There is an important subtlety here.

Each anyOf group remains separate.

Suppose we have:

Parent:
anyOf(admin, owner)

Child:
anyOf(finance, billing)

These are two independent requirements.

They should not be flattened into:

anyOf(admin, owner, finance, billing)

Otherwise a user with only admin would satisfy the combined requirement.

Keeping the groups separate preserves the intended authorization semantics.

It's a small implementation detail with a large security consequence.

The token interceptor should fail closed

Route protection is only half the story.

Once a user is authenticated, the application needs to attach an access token to API requests.

A naive interceptor might attach the token to every outgoing request.

I don't think that's a good default.

An Angular application can communicate with many destinations:

your backend API
third-party APIs
analytics services
CDNs
external resources

You don't want an access token accidentally attached to an unrelated destination.

So ngx-auth-client uses an allowlist.

Request
   |
   v
Does the URL match the allowlist?
   |
   +---- No ----> Send unchanged
   |
   +---- Yes ---> Attach bearer token

The default pattern is:

/^\\/api(\\/.*)?$/

That means same-origin relative /api/* requests.

You can configure a more specific URL pattern or restrict injection by HTTP method:

provideAuth(
  withKeycloak({
    url,
    realm,
    clientId
  }),
  {
    bearer: {
      urlPattern: /^https:\\/\\/api\\.example\\.com\\//,
      methods: ['GET', 'POST']
    }
  }
);

You can also disable bearer injection completely with:

bearer: false

when another layer is responsible for authorization headers.

The interceptor waits for readiness

A request fired during the initial authentication restore shouldn't race the session.

The interceptor waits for authentication readiness before deciding whether a token can be attached.

Otherwise you can get the classic:

Application starts
       ↓
API request fires
       ↓
Authentication is still restoring
       ↓
Request goes out without token
       ↓
401

The interceptor avoids that race.

Unauthenticated requests remain unauthenticated

If there is no authenticated session, the request proceeds without a bearer token.

The API can then return 401 Unauthorized.

The client doesn't need to turn every unauthenticated request into a client-side exception.

Regular expressions can have state

One small implementation detail caused me to think more carefully about the interceptor.

JavaScript regular expressions with the g or y flags maintain lastIndex.

That means repeatedly calling:

pattern.test(url)

can produce alternating results.

A pattern can effectively behave like:

match
no match
match
no match
...

That's an especially nasty failure mode for an authentication interceptor because the symptom is:

"Why is my Authorization header missing from every other request?"

So the library strips g and y flags from configured patterns before matching.

The underlying principle is:

Only attach credentials where they are explicitly expected.

Why keep tokens in memory?

ngx-auth-client doesn't persist access tokens in localStorage or sessionStorage.

More precisely, the library itself doesn't store the token in browser-persistent storage. With the Keycloak adapter, keycloak-js holds the token in memory.

At first, this raises an obvious question:

What happens after a page reload?

The session can still be restored because the Keycloak adapter uses:

onLoad: 'check-sso'

The browser doesn't need to persist the access token itself. Keycloak's SSO session can be checked again when the application initializes.

The reason for avoiding persistent token storage is straightforward.

Browser-accessible persistent storage can increase the impact of a successful XSS attack because malicious JavaScript may be able to read stored credentials.

Keeping tokens in memory doesn't make an application immune to XSS.

No authentication architecture can compensate for an insecure application.

But it does reduce the places where credentials are persistently stored.

That's a trade-off I prefer for this kind of client-side authentication layer.

Don't persist credentials unless persistence is actually required.

PKCE — and making the default survive real configuration

For browser-based applications, authorization-code flow with PKCE is the modern OAuth approach.

The Keycloak adapter defaults to:

pkceMethod: 'S256'

I want to be precise about this.

ngx-auth-client doesn't implement the OAuth authorization-code exchange itself. keycloak-js handles that.

The library chooses the default and makes sure the default survives the way real applications build configuration.

The `undefined` configuration problem

Configuration objects are often assembled dynamically:

const config = {
  pkceMethod: environment.pkceMethod
};

If environment.pkceMethod is undefined, a later object spread can accidentally overwrite the default:

{
  pkceMethod: 'S256',
  ...config
}

The resulting value becomes:

pkceMethod: undefined

The secure default has effectively disappeared.

So the adapter removes undefined values before merging configuration.

It's a small implementation detail, but it's an important lesson:

Security defaults aren't only about choosing the right value. They're also about making sure the value survives real configuration.

Token refresh should be invisible to the application

I didn't want token-refresh logic spread throughout the application.

A component shouldn't need to contain:

if (tokenIsAboutToExpire) {
  await refreshToken();
}

That's infrastructure logic.

The application should simply ask for an access token.

The authentication layer handles the lifecycle.

Conceptually:

Application
    |
    | getToken()
    v
AuthProvider
    |
    | Token still valid?
    |       |
    |       +---- Yes ---> return token
    |
    |       +---- No ----> refresh
    |
    v
Return valid token

getToken() only needs to interact with the network when the token is close to expiry.

With the Keycloak adapter, the default minimum token validity is 30 seconds.

Otherwise, the existing token can be returned immediately.

What happens when refresh fails?

This is where the signal-based architecture becomes useful again.

If the session genuinely expires and refresh fails, the adapter clears authentication state through the provider's authentication events.

The result is a state change:

authenticated()
    true
      ↓
    false

The rest of the application doesn't need to catch a Keycloak-specific error just to update its UI.

The application is already reacting to authentication state.

That's what I mean by making token lifecycle management invisible: the infrastructure handles the lifecycle while the application sees the resulting state.

Testing without Keycloak

Authentication tests become painful when they depend on a real identity provider.

You don't want every unit test to require:

Angular Test
     ↓
Keycloak
     ↓
Realm
     ↓
Client
     ↓
User
     ↓
Token

That's too much infrastructure for a unit test.

So the library provides a fake authentication provider:

TestBed.configureTestingModule({
  providers: [
    provideAuth(
      withFakeAuth({
        authenticated: true,
        roles: ['admin'],
        claims: {
          sub: 'user-1',
          name: 'Test User'
        }
      })
    )
  ]
});

The important part is that the fake provider implements the same provider port as the production adapter.

The component doesn't know whether authentication came from Keycloak or the fake.

That's exactly what we want from an abstraction.

The fake provider is more than a stub

It can also record calls:

loginCalls
logoutCalls
registerCalls
...

That means tests can assert not only that a guard denied access, but also that the expected login flow was triggered with the correct information.

It can also simulate failures such as:

failInit
failToken

This makes it possible to test failure paths without depending on a real identity provider.

And the fake provider can change state during a test:

const fake = TestBed.inject(FakeAuthProvider);

fake.setRoles(['viewer']);

That makes it possible to test how the application reacts to changing authentication state.

There is also a useful architectural side effect here.

The fake provider is a test of the abstraction itself.

If a fake implementation is difficult to build without knowing Keycloak internals, the port probably isn't truly provider-agnostic.

Writing the fake helped validate that boundary.

Signals are particularly important for zoneless Angular

I've described signals as a design choice.

For zoneless Angular applications, the distinction becomes more important.

Consider:

@if (keycloak.authenticated) {
  ...
}

versus:

@if (auth.authenticated()) {
  ...
}

The first approach exposes a mutable property from the identity-provider client.

The second exposes a signal that Angular understands as reactive state.

When the identity provider reports an authentication event, the adapter converts that event into a signal update:

Identity provider event
        ↓
Adapter
        ↓
Signal update
        ↓
Angular reactivity
        ↓
UI / Guards / Application logic

For example, the Keycloak adapter can react to events such as:

authentication success
token refresh success
logout
token expiration

The adapter is the single place where those provider-specific events become Angular state.

Nothing downstream needs to understand how Keycloak reports them.

That's the layer I wanted to write once and reuse.

Compatibility is part of the library

Building an Angular library isn't only about making the code work on your machine.

If you're publishing a package, you also need to think about the environments consuming it.

ngx-auth-client supports Angular 17 through 22 from a single release.

That raises an important question:

How do you know that the package you publish actually works?

Validating the repository source isn't enough.

I want to validate the artifact users install:

Source
  ↓
Build
  ↓
npm pack
  ↓
Package artifact
  ↓
Install in each supported Angular version
  ↓
Build + type-check + test

A repository can be perfectly healthy while the published package has problems with:

package exports
generated declarations
build output
dependencies
peer dependencies
packaging configuration

For an open-source library, the package is the product.

The compatibility matrix comes from the package

The supported Angular versions are derived from peerDependencies rather than maintained as a completely separate list.

That reduces the risk of having documentation or CI claim support for versions that the package doesn't actually declare.

Supporting Angular 17–22 creates real constraints

Supporting six Angular majors from a single release isn't free.

One important decision was to build the Keycloak integration directly on keycloak-js instead of keycloak-angular.

Why?

Because a wrapper that tracks a specific Angular major would make a broad compatibility range much harder to maintain.

Owning the Angular integration gives the library more control over its supported range.

There is also an example of what compatibility work actually looks like in the implementation.

provideAuth() uses ENVIRONMENT_INITIALIZER, which is deprecated in newer Angular versions.

Its replacement, provideEnvironmentInitializer, isn't available in the oldest Angular versions supported by the library.

So for a library targeting Angular 17-22, the practical choice is to use the API that remains available across the entire supported range.

It's not always about using the newest API.

Sometimes compatibility means deliberately choosing the API that works across the versions you promise to support.

Documentation is part of the product

A library isn't finished when the implementation works.

Developers need to understand:

what problem it solves
how to install it
how to configure it
how authentication works
how to configure guards
how to configure the interceptor
how to use the Keycloak adapter
how to test it

That's why I created a dedicated documentation website for ngx-auth-client.

The repository contains the implementation.

The documentation site provides the structured entry point for developers who want to evaluate and use the library.

You can explore both here:

GitHub: https://github.com/ismailza/ngx-auth-client
Documentation: https://ismailza.github.io/ngx-auth-client

What I learned building it

Building ngx-auth-client reinforced a few principles for me.

1. An abstraction should remove coupling, not hide complexity

If all I've done is wrap Keycloak APIs with different names, I haven't created a useful abstraction.

I've created a translation layer.

The real test is whether the application can stop knowing Keycloak exists.

2. Reactive state should be exposed as reactive state

Angular provides signals as a first-class reactive primitive.

Authentication state is a natural candidate for them.

Instead of making every application consumer translate provider-specific events into Angular state, the adapter should do that once.

3. Provider differences belong at the boundary

Roles are a good example.

The application wants:

roles()

It doesn't want to know about:

realm_access
resource_access
cognito:groups

That transformation belongs in the adapter.

The same principle can be applied to other provider-specific concepts.

4. Security defaults need to survive real usage

It's easy to say:

"PKCE is enabled by default."

It's harder to make sure an application's configuration cannot accidentally erase that default with undefined.

The same applies to token injection.

An allowlist is safer than assuming every outgoing request is trusted.

5. Testability is an architectural consequence

The fake provider wasn't added simply because testing is convenient.

It became possible because the provider boundary is real.

The application can be tested against the same abstraction used in production.

That's one of the best signals that an abstraction is actually useful.

What's next?

ngx-auth-client is still evolving.

There are several areas I want to continue exploring:

additional provider adapters
richer authorization capabilities
better testing utilities
API evolution without unnecessary breaking changes
compatibility as new Angular versions are released

But additional providers are probably the most interesting test.

It's easy to claim that an architecture is provider-agnostic when there is only one provider.

The real test is implementing a second one without changing the application-facing API.

That's something I want the project to prove over time.

Final thoughts

I didn't build ngx-auth-client because Angular authentication was impossible without another library.

I built it because I wanted authentication to have a cleaner architectural boundary in my applications.

The main idea is simple:

Your Angular application should consume authentication capabilities, not depend directly on an identity provider.

Signals make authentication state feel like native Angular state.

AuthProvider keeps the application independent from the identity provider.

Role normalization keeps provider-specific claim structures out of application code.

Functional guards make authorization declarative.

An allowlisted interceptor limits where credentials are sent.

In-memory token handling avoids unnecessary persistent credential storage.

And a fake provider makes authentication-dependent code easier to test.

The result isn't simply a Keycloak wrapper.

It's an attempt to build an Angular-native authentication layer that can evolve independently from the identity provider underneath it.

If you're interested in the implementation, the project is open source:

GitHub: https://github.com/ismailza/ngx-auth-client

Documentation: https://ismailza.github.io/ngx-auth-client

And if you're building Angular libraries yourself, I'd be interested in how you approach authentication, compatibility, and provider abstraction.

Originally published on ZyVOP

💡 For more articles like this, subscribe to the ZyVOP newsletter!

Building a Reusable Keycloak Theme Architecture

Ismail ZAHIR — Sat, 15 Aug 2026 22:14:39 +0000

The last article in this series ended with a promise: make Keycloak stop looking like Keycloak. I kept it. The login pages got a custom template and stylesheet, and the roughly seventeen emails Keycloak sends got the same treatment.

It worked. I wasn't satisfied.

The login theme carried its own styles. The email theme carried its own resources. If I wanted a second branded version of the same authentication experience — another product, another client, another environment — I would have been copying files and hoping I remembered to update both.

That turned a styling exercise into an engineering question:

How do you build Keycloak themes once, reuse the common parts, and still let every application customize what it actually needs?

This article is the answer I arrived at, and it is part of my Engineering in Practice series, where I document the decisions and the reasoning behind real projects rather than the finished result alone.

The implementation lives in keycloak-modern-auth, the companion repository that evolves alongside these articles.

From customization to architecture

In the earlier work, the goal was simple: customize Keycloak. Replace the default login screen with a custom design, then do the same for the emails.

That's perfectly adequate when you have one application and one visual identity. But real systems grow.

You end up with multiple applications, multiple brands, several environments, or a few products sharing one identity provider — and each of them wants its own login experience and its own email branding.

At that point, duplicating templates and CSS across themes stops being convenient and starts being a liability:

theme-a/
├── login/
│   ├── template.ftl
│   └── resources/css/login.css
└── email/
    ├── html/template.ftl
    └── messages/

theme-b/
├── login/
│   ├── template.ftl        ← same file, second copy
│   └── resources/css/login.css
└── email/
    ├── html/template.ftl
    └── messages/

At two themes this looks harmless.

Then someone asks to change the border radius, or the input height, or the focus ring — and you have to remember every theme that contains a copy, and update them consistently.

Duplication that started as convenience has become an architectural problem.

The idea: a reusable base theme

Instead of treating every Keycloak theme as an isolated implementation, I wanted a common layer underneath them:

               Base theme
                    │
         ┌──────────┴──────────┐
         │                     │
   Application A         Application B
         │                     │
     overrides             overrides

The base theme holds the authentication design. Derived themes hold only what makes them different.

This gives two properties that matter:

Reuse, because the shared templates and stylesheets exist in exactly one place.
Customization, because a derived theme can still override the parts that genuinely need to change.

It's the same instinct as inheritance in code: put the common behaviour in the base, specialize where necessary.

The interesting part is that Keycloak already gives you the mechanism — you just have to use it deliberately.

How Keycloak actually resolves themes

A theme declares its parent in theme.properties:

parent=modern.base

That single line is doing more than it looks like, because Keycloak resolves the four kinds of theme content by four different rules — and knowing which is which is most of the battle.

Properties merge vertically.

A child's theme.properties is layered over its parent's. Anything the child doesn't set, it inherits. This is the mechanism that makes token overriding work at all.

Templates resolve child-first, and whole-file.

If the child ships template.ftl, its version is used entirely; if it doesn't, the parent's is used entirely. There is no partial override, no block merging.

You inherit a template or you replace it — which is a good reason to keep base templates generic enough that nobody needs to replace them.

Resources resolve per file.

Drop a file at the same relative path and it shadows the parent's. This is how a child theme swaps img/logo.svg without touching a single line of CSS.

import= reaches sideways.

Inheritance runs vertically, from child to parent, within one theme type.

But a login theme and an email theme are different types, and both need the same brand colour. import= connects them, so shared values can live in a common theme that both types pull from:

modern.base/login  ←import←  modern.base/common
       ↑ parent                      ↑ parent
    acme/login     ←import←       acme/common

That diagram is the whole architecture.

Vertical arrows are inheritance; horizontal arrows are sharing across types.

In the repository, modern.base is the foundation and acme is a worked example of a child brand — one properties file and a logo.

This is also why I extend Keycloak's theme system rather than editing the built-in themes: the built-ins move underneath you on every upgrade, and you own the diff forever.

What belongs in the base theme

Getting the mechanism right is the easy half.

The harder question is what should actually live in the base — because a base theme that accumulates every possible customization is just a large theme with extra steps.

I settled on a simple rule:

The base owns structure, the child owns identity.

The base theme holds:

design tokens
typography scale
page layout
form and input styling
buttons
alerts and messages
shared assets

It answers the question:

How does the authentication interface work and look by default?

The derived theme holds:

logo
brand colours
favicon
product-specific assets
any genuinely necessary override

It answers a much narrower question:

How does this particular product want to be recognized?

That boundary is what keeps the abstraction honest.

If a child theme starts reaching for the structural layer, that's a signal the base is missing something — not a signal to fork the template.

Design tokens, and the loop that generates them

The piece that makes the split practical is design tokens.

Without them, values scatter through the stylesheet:

.kc-button-primary {
  background: #4f46e5;
}

.kc-input {
  border-color: #d1d5db;
}

Change the brand colour and you are grepping.

With tokens, the values are declared once and consumed everywhere:

:root {
  --kc-color-primary: #4f46e5;
  --kc-color-primary-hover: #4338ca;
  --kc-color-surface: #ffffff;
  --kc-color-text: #111827;
  --kc-color-border: #d1d5db;
  --kc-radius-md: 8px;
  --kc-space-md: 16px;
}

.kc-button-primary {
  background: var(--kc-color-primary);
  border-radius: var(--kc-radius-md);
}

The part I like, though, isn't the CSS.

It's where the values come from.

Rather than hand-writing that :root block, the base template walks the theme's properties and emits a custom property for every key that starts with kcToken, converting camelCase to kebab-case along the way.

So this:

kcTokenColorPrimary=#0d9488

becomes this, at render time:

:root {
  --kc-color-primary: #0d9488;
}

The loop is generic.

It enumerates properties; it doesn't know their names.

That detail carries more weight than it first appears: a child theme that invents:

kcTokenBannerHeight=4rem

gets:

--kc-banner-height

for free, with no change to the template and no change to the base.

The extension point is the properties file, not the code.

The base currently declares 58 tokens plus 24 dark-mode overrides, grouped roughly by colour scheme, surfaces, brand, status colours, typography, shape, spacing and layout.

Dark mode reuses the same variable names inside a prefers-color-scheme block, and only colours are overridden — spacing, radii and typography are shared, because a login form shouldn't change shape when the sun goes down.

Why this matters across brands

Now put inheritance and tokens together.

Two products, one authentication architecture.

The base defines the full token set.

Brand A overrides one line:

kcTokenColorPrimary=#2563eb

Brand B overrides one line:

kcTokenColorPrimary=#7c3aed

The components don't change.

The templates don't change.

The authentication flow certainly doesn't change.

In practice a child theme is a parent=, an import=, a handful of colours, a logo file, and a message bundle entry for the name shown in the admin console:

                Base theme
                    │
            Shared components
                    │
              Design tokens
                    │
         ┌──────────┴──────────┐
         │                     │
      Brand A               Brand B
         │                     │
      Blue UI              Purple UI

This is exactly the reuse I was looking for, and it is worth being precise about why it works:

The tokens are the only public surface between the base and its children. Everything else is implementation detail.

The email theme, where none of this is allowed

Emails are rendered by mail clients, and mail clients are a different century.

No external stylesheets — clients drop <link> entirely.

No CSS custom properties — Gmail strips var(), so the entire mechanism above simply evaporates.

Outlook's Word engine only reliably understands pixels.

Flexbox and grid are out; fixed-width tables are in.

So the same architecture had to arrive by a different route.

In the email theme, tokens are resolved at render time in FreeMarker and interpolated straight into style attributes, with a literal fallback if the property is missing:

<#local colorPrimary = properties.kcTokenColorPrimary!'#4f46e5'>

The design system is identical — same properties, same names, same child overrides.

Only the delivery differs:

the browser resolves variables at paint time
FreeMarker resolves them at send time

That let all seventeen emails share a single template shell, with the body copy arriving as pre-formatted strings from the message bundles, and all 36 shipped language translations preserved.

A child theme rebrands every email it sends by changing the same colour it changed for the login page — because both types import the same common theme.

Keeping overrides intentional

Inheritance is useful.

Unlimited overriding is not.

If every derived theme overrides everything, you have arrived back at duplicated themes with extra indirection.

So the customization boundary has to stay clear, and I find it easier to state as two questions:

The base theme answers: how does authentication look and behave by default?
The derived theme answers: how does this product want to brand it?

Layout, forms, buttons, typography and spacing are the base's responsibility — a child may override them, but doing so should feel like a decision, not a default.

Primary colour, logo, favicon and product-specific assets are the child's responsibility, and always were.

Everything in between deserves a conversation before it gets copied.

Applying this to the repository

keycloak-modern-auth isn't a sample project built to illustrate a finished idea.

It's the actual thing, evolving:

v0.1   Keycloak setup: Reproducible Keycloak + PostgreSQL stack
  ↓
v0.2   Custom login theme
  ↓
v0.3   Custom email theme
  ↓
next   Derived themes, configuration as code

I keep evolving one repository instead of creating a fresh one per experiment, and that's deliberate.

Separate repositories make each example easy to read while hiding the thing I actually care about:

Engineering decisions are incremental. The first implementation is rarely the final architecture.

The honest progression looks more like this:

"It works."
      ↓
"But there's duplication."
      ↓
"Extract the common parts."
      ↓
"Make the design configurable."
      ↓
"Now a brand is twenty lines and a logo."

That's much closer to how a real project moves.

The repository stops being sample code and becomes a record of the architectural evolution — including the steps that were replaced.

The trade-off

A base theme isn't automatically better.

It's another abstraction, and abstractions charge rent.

You now have two artifacts where you had one, and anyone touching the themes has to understand the inheritance relationship before they can safely change anything.

Debugging gets less direct, too: when a style comes from the derived theme it's obvious, and when it comes from the parent — or from a property merged three levels up — you need to know where to look.

Whole-file template resolution has a sharp edge as well, since a child that overrides template.ftl to change one line silently stops inheriting every future improvement to the base.

This is the classic bargain:

You accept some additional complexity in exchange for less duplication and more consistency.

For a single small Keycloak installation, that trade isn't obviously worth it.

For multiple applications or brands, it stops being close.

What I learned

The interesting part of this exercise wasn't writing CSS.

It was noticing the moment customization turned into architecture.

At the start, the question was:

How do I customize Keycloak?

Later it became:

How do I make this customization reusable?

Those are different questions with different answers.

The first produces a working theme.

The second produces a system for producing themes.

The distinction I try to hold onto is this:

Don't introduce an abstraction because it looks elegant. Introduce it when a repeated problem justifies it.

Here, the repeated theme structure and the need for consistent branding across products supplied the justification.

Keycloak's inheritance provided the mechanism, and design tokens provided a clean way to make the visual system both reusable and customizable.

What's next

The base theme is one step, not a destination.

The directions I want to explore next are mostly about everything around the theme rather than the theme itself:

more reusable authentication components
better token organization
multiple derived brands
automated validation so a broken theme fails before it reaches an environment
packaging themes into the image rather than bind-mounting them

Underneath all of that sits a problem I keep running into:

How do you keep Keycloak configuration synchronized across development, staging, qualification and production?

Themes are the visible layer, but realms, clients, roles, mappers and flows are the part that actually drifts.

That's where theme customization stops being a frontend concern and turns into an infrastructure one — and it's what I want to write about next.

Final thoughts

What started as a Keycloak customization is slowly turning into a small authentication platform.

The lesson isn't that every Keycloak project needs a sophisticated base theme.

It's that architecture should follow the problems you actually hit.

Start simple.

Notice the duplication.

Learn the extension points the platform already gives you.

Extract only the parts that are genuinely reusable.

Then introduce the abstraction.

The implementation continues to evolve in keycloak-modern-auth, alongside this series.

This is engineering in practice: not designing the perfect architecture upfront, but improving it as the real problems come into focus.

OAuth 2.0, OpenID Connect, and Keycloak: Understanding Modern Authentication

Ismail ZAHIR — Fri, 07 Aug 2026 14:05:16 +0000

OAuth 2.0, OpenID Connect, JWT, access tokens, refresh tokens, Keycloak. These get mentioned in the same breath so often that they blur into a single vague thing called "authentication." They're not one thing. Each solves a distinct problem, and the boundaries between them are sharper than most introductions suggest.

That blurring has practical consequences. It's why teams send ID tokens to APIs, enforce permissions in the frontend, or reach for a flow that was deprecated years ago — not from carelessness, but because nobody drew the lines clearly in the first place.

So let's draw them. We'll take each piece in turn, then follow a real login through an Angular app, a Keycloak realm, and a Spring Boot API to see where each one actually does its work.

Authentication is not authorization

These two get used interchangeably in conversation, and it causes real bugs.

Authentication answers "who are you?" You type a password, a fingerprint gets scanned, a magic link gets clicked. At the end of it, the system knows your identity.

Authorization answers "what are you allowed to do?" An admin can manage users. A doctor can open a patient record. A patient can only see their own appointments.

The ordering matters: you can't decide what someone is allowed to do until you know who they are. Every system does authentication first, authorization second, even when the code makes it look like one step.

Why OAuth 2.0 exists

Say your application needs to read files from a user's Google Drive.

The naive approach is to ask for their Google password and log in on their behalf. Hopefully the problem is obvious — you now store a credential that unlocks their email, their photos, their entire account, and you've given yourself unlimited access when you only needed to read one folder.

OAuth 2.0 exists to avoid exactly this. The user authenticates directly with Google. Google asks whether they want to grant your app access to Drive. If they agree, your app receives a token scoped to that specific permission. You never see the password, and the user can revoke your access at any time without changing it.

So OAuth 2.0 is an authorization framework: it lets an application act on a user's behalf without ever holding their credentials.

The four roles

OAuth defines four participants, and it's worth being able to name them because every OAuth error message assumes you can.

Resource Owner — the user. They own the data.
Client — the application asking for access. Your Angular SPA, a mobile app, a background service.
Authorization Server — authenticates the user, gets their consent, issues tokens. This is Keycloak.
Resource Server — the API holding the protected data. Your Spring Boot or ASP.NET Core backend, which validates the token before responding.

What OpenID Connect adds

Here's the part that trips people up: OAuth 2.0 is not an authentication protocol.

An access token tells an API "the bearer of this token is allowed to do X." It doesn't reliably tell your application who the user is. Plenty of teams worked around this by calling some vendor-specific "get me the user" endpoint after the OAuth dance, and every vendor did it differently.

OpenID Connect (OIDC) standardises that. It's a thin identity layer on top of OAuth 2.0, and its main contribution is the ID Token — a JWT describing the authenticated user, with predictable claim names:

sub — a stable unique identifier for the user
name, given_name, family_name
email, email_verified
preferred_username

OIDC also standardises the discovery document, the userinfo endpoint, and logout. Because of it, an OIDC client library works against Keycloak, Auth0, Okta, or Azure AD with nothing more than a URL change.

Short version: OAuth 2.0 delegates authorization. OpenID Connect adds authentication.

Where Keycloak fits

Keycloak is an open-source Identity and Access Management server that implements both specs. Instead of writing your own login page, password hashing, session handling, MFA, and social login, you delegate all of it and your apps just trust Keycloak.

One note before going further: Keycloak has changed a lot. The old Java adapters (keycloak-spring-boot-starter and friends) were deprecated years ago and have since been removed, so on Keycloak 26+ you secure a Spring Boot API with Spring Security's own OAuth 2.0 Resource Server support and nothing Keycloak-specific on the backend at all. If a tutorial tells you to add a Keycloak adapter dependency, it predates the Quarkus distribution and you can close the tab.

A few Keycloak-specific concepts you'll meet immediately:

Realms. A realm is an isolated tenant — its own users, roles, clients, and signing keys. Users in realm A don't exist in realm B. A common pattern is one realm for your staff and another for your customers, since they rarely share anything.

Clients, public and confidential. Every application that talks to Keycloak is registered as a client. A confidential client can keep a secret (a backend service). A public client can't — an Angular SPA ships its entire source to the browser, so anything you call a "secret" there is just a string anyone can read in DevTools. SPAs and mobile apps must be public clients, which is precisely why PKCE exists.

Realm roles vs client roles. Realm roles are global (admin, doctor). Client roles are scoped to one application (billing-app:invoice-manager). If two apps in your realm both need a role called manager meaning different things, that's your signal to use client roles.

The discovery endpoint. Every realm exposes its configuration at:

https://<host>/realms/<realm>/.well-known/openid-configuration

Open it in a browser. You get every endpoint URL, the supported flows, and the JWKS URI where your backend fetches public keys. Most client libraries need only this one URL. It's also the fastest way to confirm a realm name is spelled the way you think it is.

The Authorization Code Flow with PKCE

For browser and mobile apps, this is the flow to use. The Implicit Flow you may still see in older tutorials is deprecated — don't.

Let's walk through it with an Angular app in front of a Spring Boot API.

Step 1 — the app notices you're not logged in. No valid token in memory, so it prepares to redirect.

Step 2 — PKCE setup, then redirect. Before going anywhere, the app generates a random string called the code_verifier, hashes it with SHA-256, and base64url-encodes the result into a code_challenge. The verifier stays in the browser. Only the challenge goes to Keycloak, along with a state parameter (random, and checked on the way back — that's your CSRF protection) and the redirect URI.

Step 3 — you log in. Keycloak renders its login page, checks your credentials, runs MFA if configured, and redirects back to your app with a short-lived authorization code in the URL. Worth emphasising: this is not a token. On its own it's useless.

Step 4 — the exchange. The app POSTs the code back to Keycloak's token endpoint, this time including the original code_verifier. Keycloak hashes it and compares against the challenge from step 2. Match, and you get an access token, an ID token, and a refresh token.

This is the whole point of PKCE. Authorization codes travel through the browser's address bar, and on mobile through OS-level URL handlers — both interceptable. Without PKCE, an attacker who steals the code can redeem it themselves. With PKCE they'd also need the verifier, which never left the original app. It's a proof that whoever redeems the code is whoever started the flow.

Step 5 — calling the API. The app attaches the access token to requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...

Step 6 — the API validates. Spring Boot checks the token's signature, issuer, audience, and expiry, then serves the data — or returns 401.

Here's the whole exchange in one picture:

The Authorization Code Flow with PKCE, end to end

The three tokens

Access token. Presented to APIs. Contains the subject, roles, scopes, and an expiry. Keycloak defaults to a 5-minute lifespan, and that's a reasonable default — a leaked token stops being useful quickly.

A word on scopes, since they're easy to confuse with roles. A scope is what the application asked permission to do; a role is what the user is allowed to do. When your Angular app requests openid profile email, it's saying "I want an ID token, plus the user's profile and email claims" — and the user's consent screen reflects that. In Keycloak these are configured as client scopes, which control both the claims that land in the token and the roles included in it. The distinction matters because a token can carry a powerful role and still be scoped too narrowly for what your API wants to do with it — the API should check both.

ID token. For the client application only, to answer "who is logged in?" Use it to display a name and avatar. Do not send it to your API as a credential; it isn't scoped for that and a correctly configured API will reject it anyway.

Refresh token. Longer-lived, used to get a new access token without sending the user back through login. Turn on refresh token rotation — each refresh invalidates the previous token. If a rotated token gets replayed, Keycloak sees a token that's already been used and can kill the whole session. For public clients this isn't optional in my view; it's the only real protection a token you can't keep secret has.

What's actually inside an access token

All of this stays abstract until you decode one. A Keycloak access token is a JWT: three base64url segments separated by dots, header.payload.signature. Paste one into jwt.io and you get something like this.

The header names the algorithm and, importantly, the key:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "sBv3qHhL2XmR7pKdN9fYcW1uEjTgA4Zo"
}

And the payload:

{
  "exp": 1754563200,
  "iat": 1754562900,
  "jti": "3f1c7a92-8d4e-4b16-9c05-7ae2f0b8d331",
  "iss": "https://auth.example.com/realms/healthcare",
  "aud": ["billing-api", "account"],
  "sub": "9b2d41f7-6c8a-4e3b-bf19-2d05c7e4a8f1",
  "typ": "Bearer",
  "azp": "web-app",
  "sid": "c4a8e102-5f37-49bd-8e6a-1b93d70cf254",
  "scope": "openid profile email",
  "realm_access": {
    "roles": ["doctor", "offline_access"]
  },
  "resource_access": {
    "billing-api": {
      "roles": ["invoice-manager"]
    }
  },
  "preferred_username": "ismail",
  "email": "ismail@example.com",
  "email_verified": true
}

Everything discussed so far is visible here. iss is the realm. aud lists who this token is for. sub is the stable user ID — note that it's a UUID, not the username, which is why you should key your own database on sub and never on preferred_username or email (both can change). realm_access.roles and resource_access are the realm and client roles from earlier, arriving in exactly the shape Keycloak defines. azp is the client that requested the token.

One thing worth internalising: this payload is base64-encoded, not encrypted. Anyone holding the token can read every claim in it. That's fine for roles and usernames. It is not fine for anything you'd call confidential, so resist the temptation to stuff internal identifiers or business data into custom claims.

Where do you store tokens?

Every tutorial says "store them securely" and moves on. That phrase hides the single most argued-about decision in frontend auth, so let's be honest about the options.

localStorage is the easy path and survives page refreshes. It's also readable by any JavaScript on the page, which means one XSS bug — yours or a compromised npm dependency's — hands over every token you hold.

In-memory only removes the XSS smash-and-grab, since there's nothing persisted to steal. The cost is that a refresh logs the user out, unless you use silent renewal via a hidden iframe, which third-party cookie restrictions are steadily breaking.

Backend-for-Frontend (BFF) keeps tokens on a small server-side layer and gives the browser only an httpOnly cookie. The browser never touches a token. This is the most secure option and it's where the industry is heading — but it's real infrastructure, and it brings CSRF back into scope.

There's no universally correct answer. Pick deliberately based on what your app protects, and know what you're trading away. Medical records and a marketing dashboard don't warrant the same call.

Validating tokens on the backend

"Validate the token" also deserves unpacking, because getting it partly right is a genuine vulnerability. Your API must check:

Signature — verified against Keycloak's public keys from the JWKS endpoint. Libraries fetch and cache these automatically; make sure yours actually does.
iss — the issuer matches your realm URL exactly.
aud — the audience includes your API. This is the one people skip. Without it, a token issued for a different client in the same realm will sail straight through your validation, because the signature is perfectly valid. It just wasn't meant for you.
exp — not expired.

Any decent OIDC library does all four once configured. The failure mode is almost always a missing or wrong aud, so check that first when something feels off.

Key rotation, and why you shouldn't hardcode a public key

Keycloak rotates its realm signing keys — on a schedule, or whenever you rotate them manually after an incident. This is exactly what the kid in the token header is for: it identifies which key signed this particular token, so old tokens stay verifiable while new ones are signed with the new key.

Your API should therefore fetch keys from the JWKS endpoint and cache them, refetching when it sees a kid it doesn't recognise. Spring Security does this out of the box when you point it at the issuer URI. What you must not do is copy a PEM public key out of the admin console and paste it into application.yml — I've seen it, it works fine for months, and then every request in production returns 401 the morning after a key rotation with no obvious cause. Configure the issuer, let the library handle the rest.

Four things people get wrong

"OAuth 2.0 is authentication." It isn't. It's an authorization framework. Authentication comes from OpenID Connect layered on top.

"JWT and OAuth are the same thing." OAuth defines how authorization is delegated. JWT is one possible format for the tokens involved. OAuth works fine with opaque tokens, and plenty of providers use them.

"The frontend decides permissions." The frontend hides buttons the user can't use. That's UX, not security — anyone can open DevTools and call your API directly. The backend enforces authorization, always, no exceptions.

"Long-lived access tokens improve the user experience." They improve it right up until one leaks and stays valid for a week. Short access tokens plus rotating refresh tokens plus automatic renewal gives you the same seamless experience without the exposure window.

Practical checklist

Authorization Code Flow with PKCE for browser and mobile apps. Never Implicit.
Access token lifespan in minutes, not hours.
Refresh token rotation on for public clients.
Validate signature, iss, aud, and exp on every API request.
Realm roles for cross-application concepts, client roles for app-specific ones.
HTTPS everywhere in production — a bearer token over plain HTTP is a password over plain HTTP.
Don't build your own auth server. Really.

Wrapping up

Most of the confusion around this stack disappears once each piece has one clear job:

OAuth 2.0 delegates authorization. OpenID Connect adds authentication and a standard identity format. Keycloak implements both and manages the users. Access tokens authorize API calls, ID tokens identify the user to the app, and refresh tokens keep the session alive without repeated logins.

Once that clicks, Keycloak's configuration screens stop being a maze and start being a map of the protocol.

Next in this series: making Keycloak stop looking like Keycloak. We'll build a custom login theme from scratch — FreeMarker templates, CSS custom properties for multi-brand support, and full RTL for Arabic, which is where things get genuinely interesting.

— Ismail

Why I Validate Angular Compatibility Using the Published npm Package (Not the Source Code)

Ismail ZAHIR — Fri, 31 Jul 2026 00:52:23 +0000

I just published a new article on a lesson I learned while maintaining my open-source Angular library.

I used to validate compatibility against my workspace and dist/, but eventually realized that wasn't what developers actually install from npm.

That led me to redesign the CI pipeline to validate the published package across multiple Angular versions instead.

The article covers:

Why testing dist/ isn't enough
Angular partial compilation and the linker
Why type-checking alone can miss compatibility issues
Validating the packaged artifact with npm pack
Building a compatibility matrix for Angular 17–22

If you maintain an Angular library (or any npm package), I'd love to hear how you approach compatibility testing.

📖 Why I Validate Angular Compatibility Using the Published npm Package (Not the Source Code)

Medium link

I Stopped Copy-Pasting the Same Angular ApiService. Here’s What I Built Instead

Ismail ZAHIR — Sun, 26 Jul 2026 12:16:23 +0000

Every Angular project I've worked on had an api.service.ts.

Different repository.

Different company.

Same file.

It always started as a thin wrapper around HttpClient, then gradually accumulated more responsibility: versioning, authentication, retry logic, loading indicators, error handling.

By the fourth project, I wasn't writing it anymore.

I was copying it.

And not carefully. I'd paste the file in, then spend the next hour re-fixing the same three bugs I'd already fixed in the last project — because I'd never written them down anywhere, just patched them in place and moved on.

That was the moment I realized it wasn't repeated code anymore.

A pattern repeated four times isn't a pattern anymore. It's a missing dependency.

So I extracted it, made the hard-coded parts configurable, and published it as @ismailza/ngx-api-client.

This article isn't really about the library. It's about the four decisions that turned a file I was slightly embarrassed to copy-paste into something I'd defend in a code review.

The actual gap

HttpClient is a good HTTP client. That's genuinely all it claims to be, and people keep being disappointed that it isn't more.

HttpClient gives you a request. It does not give you a policy.

Every application still has to answer:

Where does the base URL come from, and how does the API version get into it?
What turns a failed response into something a component can actually render?
Which requests are safe to retry, and how long do you wait before you do?
How does a global progress bar find out that anything is in flight?

Most applications answer those questions inside an ApiService that grows organically over time until nobody wants to touch it anymore. I wanted those decisions to live in one place — and to see, at a glance, how a request actually moves through the system:

" width="800" height="518">

A request leaves the component, passes through ApiService, then through an ordered chain — your auth interceptor, retry with jitter, your backend, error normalization, an optional success step — before looping back. Loading state and error handling hang off that chain as pluggable pieces, not built-in opinions.

The first mistake I kept repeating was hard-coding the version

`${baseUrl}/api/v1${endpoint}`

It works...

...until your backend decides to version using:

headers
query parameters
media types
dates
or no URL versioning at all

Instead of treating versioning as string concatenation, I modeled it as a configurable strategy.

provideApi({
  baseUrl: 'https://api.example.com',
  prefix: 'api',
  version: 2,
  versioning: 'url'
});

The same configuration can instead produce:

/api/v2/orders
/api/orders?v=2
X-API-Version: 2
Accept: application/vnd.api.v2+json

without changing application code.

Two rules became surprisingly important:

A header or query parameter the caller set explicitly is never overwritten by the versioning strategy. If you pass Api-Version yourself, you meant it. A library that silently clobbers explicit caller input is a library you cannot debug.

Versions should accept strings as well as numbers. This only became obvious after integrating with a backend that versioned by date:

provideApi({
  baseUrl: 'https://api.example.com',
  version: '2024-01-01',
  versioning: { strategy: 'header', headerName: 'Api-Version' },
});

If I had typed it as number — which is what my copy-pasted version implicitly assumed — the whole abstraction would have been useless for the exact API that motivated making it configurable.

Then I realized my biggest problem wasn't requests — it was failures

HTTP failures rarely look the same.

Sometimes you get a proper RFC 9457 Problem Details response. Well-behaved, easy.

Sometimes nginx sends back plain text, because it answered before your app ever saw the request.

Sometimes the network disappears completely and the status is simply 0.

Components shouldn't need three different code paths for those three situations. Everything gets normalized into one shape:

interface ApiError {
  type: string; // RFC 9457 problem type URI
  title?: string; // 'Bad Request'
  status: number; // 0 for a network failure
  detail: string; // safe to show the user
  instance?: string; // path that produced it
  code?: string; // machine-readable, e.g. 'VALIDATION_ERROR'
  timestamp: string;
  traceId?: string; // from the body, else the X-Trace-Id header
  errors?: { field: string; message: string }[];
}

Once a component receives this, it no longer cares where the failure originated.

Two things worth stating out loud:

Branch on code, never on detail. detail is prose meant for a human. It gets reworded, translated, and A/B tested. The day somebody changes "Invalid credentials" to "Incorrect email or password," every if (error.detail === "Invalid credentials") in your codebase silently stops working.

if (error.code === "INVALID_CREDENTIALS")

code is the contract. detail is for humans.

traceId falls back to the X-Trace-Id header. Nine times out of ten the useful correlation ID is in the response headers and the error body is empty. If your error model discards headers, every production bug report starts with "can you reproduce it?"

I almost shipped a toast notification. I'm glad I didn't

That was the easiest feature to add, and the hardest to leave out on purpose.

The moment a library renders anything, it has an opinion about your design system, your i18n setup, and your accessibility strategy — three things it cannot possibly know. So the library only exposes an error handler that applications replace:

@Injectable()
export class ToastApiErrorHandler extends ApiErrorHandler {
  private readonly toast = inject(MyToastService);
  private readonly router = inject(Router);

  override handle(error: ApiError): void {
    this.toast.error(error.detail, { title: error.title });

    if (error.status === 403) {
      this.router.navigate(['/forbidden']);
    }
  }
}

The HTTP layer reports problems. The application decides how users experience them.

The practical payoff: peer dependencies are @angular/core, @angular/common, and rxjs. Nothing else. A library sitting in your HTTP layer has no business pulling a UI kit into your bundle.

One honest caveat I put in the README rather than hiding: the default handler passes the whole ApiError to Angular's own ErrorHandler, which logs it. If your API puts sensitive data in detail or instance, register your own handler instead of relying on the default. Defaults should be safe, and where they can't be, they should say so.

One decision surprised every reviewer — I don't register my own interceptors

provideHttpClient(
  withInterceptors([
    retryInterceptor,
    apiErrorInterceptor,
    apiSuccessInterceptor
  ])
);

This is the one I had to defend hardest in review. At first glance it looks like boilerplate the library should absorb. It isn't, because order matters and only you know what else is in the chain:

An auth interceptor has to come first, so a retried request picks up a fresh token instead of replaying the expired one.
retryInterceptor has to come before apiErrorInterceptor, so your error handler only ever sees failures that survived every retry. Get this backwards and users see three toasts for one eventually-successful request.

If the library silently injected interceptors at a position it chose, that position would be wrong in some app, and debugging it would mean reading my source. Making the ordering explicit costs one line and buys the ability to reason about the chain.

Retry is harder than it looks

retry(3)

That's five characters and it isn't enough. A few rules that all turned out to matter:

Don't retry POST requests by default. It isn't idempotent — replaying it can create two orders. Callers opt in per request when they know their endpoint is safe.
Respect the server's Retry-After header. On a 429, the server has told you exactly when to come back; your backoff curve is a guess, the header isn't.
Retry only transient failures: 408, 429, 500, 502, 503, 504. Retrying a 400 is just asking the server to reject you four times.
Use exponential backoff — and always add jitter.

const exponentialDelay = config.initialDelay * Math.pow(config.multiplier, retryIndex - 1);
const jitter = exponentialDelay * Math.random() * 0.3;
return timer(exponentialDelay + jitter);

Without jitter, every client that hit your struggling backend at the same moment retries at the same moment, and again two seconds later, and again four seconds after that. You've built a synchronized load test against a server that's already failing. A little randomness breaks the lockstep.

Two smaller decisions I'm glad I made

Per-request configuration travels through HttpContext, not service state.

this.api.get<LegacyOrder>('/orders', { version: 1 });

this.api.post('/analytics/event', payload, {
  retry: false,
  skipErrorHandler: true,
  showLoader: false,
});

One request can disable retries, skip global error handling, or bypass loading indicators without touching any concurrent request. A mutable flag on the service that the next interceptor reads would be a race condition waiting for two calls to happen at once.

Loading state is a counter, not a boolean.

@Injectable({ providedIn: 'root' })
export class ApiLoadingService {
  private readonly activeRequests = signal(0);
  readonly loading = computed(() => this.activeRequests() > 0);
}

A boolean flickers: three requests start, the fastest one finishes, and the progress bar disappears while two are still running. A counter with a computed() signal doesn't. It's a five-line class, and it's the single most-copied snippet from every version of this file I ever wrote.

What I would tell myself before starting

Don't extract after the first implementation. Extract after the fourth. Three implementations taught me which parts actually varied — the version transport, the error presentation — and which parts never did. Abstracting after one project would have produced configuration options nobody needed, and hard-coded the things that mattered.

Write the README before the code you're unsure about. Every section I struggled to explain was a section where the API was wrong. The interceptor-ordering paragraph took three rewrites, and the third is what convinced me not to auto-register them.

Be honest about compatibility. Mine says: developed and tested against Angular 21; the declared floor of >=17 reflects the APIs used — signals and functional interceptors — rather than a range the CI matrix currently covers. Less impressive than claiming full 17–21 support. Also true, which matters more.

Closing thoughts

Open source isn't about writing perfect software. It's about taking something you've solved the same way four times, pulling out the pattern, and inviting other people to tell you where it's wrong.

I'm not sure this library is done evolving. But the ideas behind it — versioning as a strategy instead of string concatenation, one error shape no matter what the backend sends back, keeping presentation out of the HTTP layer, and making interceptor order something you choose rather than something the library hides from you — are decisions I'd make again.

I'm curious how other Angular teams handle this. Do you build your own API layer, or lean directly on HttpClient? Which of these decisions would you have made differently?

This is my first technical article, and I'd genuinely love feedback. If you think one of these design decisions is wrong — or you've solved the problem differently — I'd enjoy hearing your perspective.

The library is on npm as @ismailza/ngx-api-client, and the source is on GitHub if you'd like to explore the implementation.

— Ismail

DEV Community: Ismail ZAHIR

The Hidden Cost of “Just Add a Setting”

A simple field is often the right answer

Definition and value are different concepts

Ownership is not one field

Resolution needs a context, not a growing method signature

Explicit value and effective value are different data

Reset is a first-class domain operation

Persisting polymorphic owners has real trade-offs

Not every setting should be overridable

Validation belongs near the specification

Where do definitions come from?

Database-first

Code-first

Hybrid: code owns behavior, migrations own lifecycle

The catalog joins the two halves

Setting codes are persistent identifiers

Audit the decision, not just the current value

Updating a setting may have side effects

Bulk resolution matters

Configuration metadata can drive the frontend

Make testing cheap

Caching inherited settings is harder than caching rows

Settings are not feature flags

Not all configuration belongs in the settings system

The final APPOINTMENT_DURATION model

When should you build this?

Conclusion

Stop Creating an Endpoint for Every Button

Start with the domain, not the button

When status really is the resource being changed

Don't replace many endpoints with one god endpoint

The strongest counterexample: different transitions need different data

Some status changes are really outcomes

Valid doesn't mean authorized

How does the frontend know what's allowed?

Failure semantics matter too

State transitions have a concurrency problem

Commands have the mirror-image problem: retries

Remove the UI and ask again

The rule I use now

My Pull Request Failed — Because GitHub Actions Was Protecting the Repository

The workflow looked perfectly normal

Two events with very different trust models

pull_request: run CI against the proposed change

pull_request_target solves a different problem

The problem starts when those worlds are mixed

Repository code is executable input

This is known as a "pwn request"

And now actions/checkout actively protects against it

My first question became: why does this workflow need pull_request_target?

Before

After

Before and after: the actual security model

The security model before

The security model after

The lesson isn't "pull_request_target is bad"

Workflow A

Workflow B

A mental model I now use

Question 1: Does this job execute contributor-controlled code?

Question 2: Does this job have privileged access?

Separate CI from privileged automation

Workflow 1: untrusted CI

Workflow 2: trusted automation

permissions is part of the architecture too

Secrets aren't the only thing worth protecting

CI configuration is security architecture

Why the failed pipeline was useful

Final takeaway

References

I Built an Angular Authentication Layer for the Signals Era

Why build another authentication library?

Authentication state should be Angular state

One service for application code

Bootstrap doesn't have to wait for authentication

A small profile detail

Designing around AuthProvider

Keycloak is an adapter, not the architecture

The boundary isn't only TypeScript

The final `APPOINTMENT_DURATION` model

`pull_request`: run CI against the proposed change

`pull_request_target` solves a different problem

And now `actions/checkout` actively protects against it

My first question became: why does this workflow need `pull_request_target`?

The lesson isn't "`pull_request_target` is bad"

`permissions` is part of the architecture too

Designing around `AuthProvider`

Route authorization: functional guards, `anyOf` and `allOf`

The `undefined` configuration problem