Java SDK — Overview

authorization-core (io.gitlab.ctu-iotlab:com.authorization.core) is a Java 17 library that integrates Permix into your JVM microservices. It provides:

• A @Resource annotation you place on any method or class
• An interceptor (Spring AOP / Quarkus CDI) that calls Permix before every annotated invocation
• A startup initializer that auto-registers all discovered resources on boot
• Framework auto-configuration for Spring Boot and Quarkus — zero boilerplate

Maven dependency#

<dependency>
  <groupId>io.gitlab.ctu-iotlab</groupId>
  <artifactId>com.authorization.core</artifactId>
  <version>0.1.5</version>
</dependency>

Published to Maven Central under the MIT License. Requires Java 17+.

The @Resource annotation#

@Inherited
@InterceptorBinding          // CDI binding
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Resource {
    String   name()         default "";  // unique key, e.g. "invoice:read"
    String   displayName()  default "";  // human-readable label
    String[] defaultRoles() default {};  // roles bootstrapped on first registration
}

@Resource can be placed on a method (recommended) or a class (applies to all methods). In Quarkus, the interceptor checks the method annotation first and falls back to the class annotation.

How it works at runtime#

Every time an annotated method is called, the interceptor:

1. Reads all inbound HTTP request headers via HeaderExtractor.
2. Strips restricted headers (connection, host, content-length, expect, upgrade, transfer-encoding) via HeaderSanitizer.
3. Forwards the sanitized headers plus calls POST /resources/access/check with {"name": "<resource-name>"}.
4. If the response is {"authorized": false} or the request fails → throws SecurityException → interceptor turns it into HTTP 403.
5. If enabled = false in config → the check is skipped entirely (method proceeds normally).

Inbound Request
      │
      ▼
HeaderExtractor ──► HeaderSanitizer ──► GenericRestClient
                                              │
                                   POST /resources/access/check
                                   {"name": "invoice:read"}
                                              │
                                   {"authorized": true/false}
                                              │
                              ┌───────────────┴───────────────┐
                           allowed                         denied
                              │                               │
                         proceed()                  SecurityException → 403

Startup resource registration#

On application startup, ResourceInitializer discovers every @Resource-annotated method in your codebase and registers them with Permix so that roles and policies can be managed centrally.

Registration flow:

1. SpringInitialize/QuarkusInitialize runs @PostConstruct.
2. ResourceCollectorAdapter.collect() scans all beans/CDI beans for @Resource methods.
3. Calls TokenProvider.getAdminToken() → performs client_credentials token exchange against {AUTH_SERVER_URL}/protocol/openid-connect/token.
4. Calls POST /resources/list with all discovered resources in one batch.

Registration payload sent per resource:

{
  "name":         "invoice:read",
  "displayName":  "Read Invoice",
  "serviceName":  "invoice-service",
  "defaultRoles": ["finance", "admin"]
}

Configuration reference#

All keys are read through ApplicationConfigProvider (Spring Environment or MicroProfile Config).

Environment variables (read via System.getenv):

Framework-specific OIDC URL keys (used by TokenProvider):

The token URL is constructed as {AUTH_SERVER_URL}/protocol/openid-connect/token.

Dev mode#

Dev mode is detected automatically from the active profile — no explicit property needed:

In dev mode:

• Startup registration is skipped — a log message is printed instead.
• Runtime checks still run (enforcement is controlled by ctu.iotlab.resource-config.enabled, not the profile).

To also disable runtime checks in development, set ctu.iotlab.resource-config.enabled=false.

Logging#

The SDK uses System.out.println with a structured log format (no SLF4J/Log4j dependency required):

2025-09-10 08:00:00,123 INFO [com.ctu.iotlab] (main) Resource sync process started. Activated profile dev.
2025-09-10 08:00:00,456 INFO [com.ctu.iotlab] (main) Scanned 12 resources.

On incomplete token config (missing tokenUrl, clientId, or clientSecret), a WARN line is printed listing the missing fields and registration is skipped gracefully.

Changelog#