Comprehensive guides and references for the OpenFrame platform
The Api Service Core Config And Security module provides the foundational configuration and security wiring for the OpenFrame API service. It is responsible for:
This module acts as the infrastructure layer for the API service. It does not implement business logic itself, but enables REST controllers, GraphQL fetchers, and domain services to operate securely and consistently.
Within the overall platform, the Api Service Core Config And Security module sits between the Gateway and the API business layers.
flowchart LR
Client["Frontend or External Client"] --> Gateway["Gateway Service"]
Gateway --> ApiCore["Api Service Core Config And Security"]
ApiCore --> RestControllers["API REST Controllers"]
ApiCore --> GraphQL["GraphQL Fetchers"]
RestControllers --> DomainServices["Domain Services"]
GraphQL --> DomainServices
DomainServices --> DataLayer["Mongo and Data Repositories"]
Gateway Service
Api Service Core Config And Security
Controllers and Fetchers
For details on REST endpoints, see the corresponding REST controller module documentation in your project structure.
The module is composed of the following configuration components:
flowchart TD
ApiAppConfig["ApiApplicationConfig"] --> PasswordEncoder["BCrypt PasswordEncoder"]
AuthConfig["AuthenticationConfig"] --> ArgResolver["AuthPrincipalArgumentResolver"]
DataInit["DataInitializer"] --> OAuthRepo["OAuthClientRepository"]
DateScalar["DateScalarConfig"] --> GraphQLRuntime["GraphQL Runtime"]
InstantScalar["InstantScalarConfig"] --> GraphQLRuntime
RestTemplateCfg["RestTemplateConfig"] --> RestTemplateBean["RestTemplate"]
SecConfig["SecurityConfig"] --> JwtCache["Caffeine JwtAuthenticationProvider Cache"]
SecConfig --> FilterChain["SecurityFilterChain"]
Each configuration class contributes a specific capability to the API runtime.
Purpose: Defines core application-level beans.
Key Bean:
PasswordEncoder → BCryptPasswordEncoderThis encoder is used across the API service for hashing and verifying credentials when needed by domain services.
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
This ensures:
Purpose: Enables injection of authenticated principals into controller methods.
Registers a custom AuthPrincipalArgumentResolver, allowing controller methods to declare authenticated user parameters such as:
public ResponseEntity<?> endpoint(@AuthenticationPrincipal AuthPrincipal principal)
This avoids manual extraction of authentication details from the security context and ensures consistent access to tenant and user information.
Purpose: Bootstraps a default OAuth client at application startup.
Implements a CommandLineRunner that:
oauth.client.default.idoauth.client.default.secretflowchart TD
Start["Application Startup"] --> ReadProps["Read OAuth Properties"]
ReadProps --> CheckClient["Find Client By ID"]
CheckClient -->|"Exists"| CompareSecret["Compare Secret"]
CompareSecret -->|"Different"| UpdateSecret["Update Secret"]
CompareSecret -->|"Same"| NoChange["No Action"]
CheckClient -->|"Not Found"| CreateClient["Create OAuth Client"]
Default configuration includes:
password, refresh_tokenread, writeThis ensures the API service always has a valid OAuth client configured in the data layer.
Purpose: Provides a custom GraphQL scalar for Date.
LocalDateyyyy-MM-ddIf invalid formats are provided, descriptive CoercingParseValueException or CoercingParseLiteralException are thrown.
This ensures:
Purpose: Provides a custom GraphQL scalar for Instant.
java.time.InstantTogether, DateScalarConfig and InstantScalarConfig standardize time handling across GraphQL queries and mutations.
Purpose: Defines a shared RestTemplate bean.
@Bean
public RestTemplate restTemplate() {
return new RestTemplate();
}
Used for:
Centralizing this bean ensures consistent configuration and future extensibility (timeouts, interceptors, tracing).
Purpose: Configures the API service as an OAuth2 Resource Server.
This configuration is intentionally minimal because the Gateway already handles:
The API service enables resource server support primarily for:
@AuthenticationPrincipalA Caffeine LoadingCache stores JwtAuthenticationProvider instances per issuer.
flowchart TD
Request["Incoming Request"] --> ExtractIssuer["Extract JWT Issuer"]
ExtractIssuer --> CacheLookup["Lookup JwtAuthenticationProvider"]
CacheLookup -->|"Miss"| CreateDecoder["JwtDecoders.fromIssuerLocation"]
CreateDecoder --> StoreCache["Store In Cache"]
CacheLookup --> Authenticate["Authenticate JWT"]
Configuration properties:
openframe.security.jwt.cache.expire-afteropenframe.security.jwt.cache.refresh-afteropenframe.security.jwt.cache.maximum-sizeThis enables:
flowchart LR
HttpSecurity["HttpSecurity"] --> DisableCsrf["Disable CSRF"]
DisableCsrf --> PermitAll["Permit All Requests"]
PermitAll --> ResourceServer["Enable OAuth2 Resource Server"]
ResourceServer --> IssuerResolver["JwtIssuerAuthenticationManagerResolver"]
Even though requests are permitted, authentication is still processed so that downstream components can rely on a populated SecurityContext.
sequenceDiagram
participant Client
participant Gateway
participant ApiService as "API Service"
Client->>Gateway: HTTP Request with JWT
Gateway->>Gateway: Validate JWT
Gateway->>ApiService: Forward Request with Authorization Header
ApiService->>ApiService: Resolve Issuer
ApiService->>ApiService: Authenticate via JwtAuthenticationProvider
ApiService->>ApiService: Populate SecurityContext
Key principle: Gateway enforces security, API consumes identity context.
The Api Service Core Config And Security module enables:
It integrates with:
The Api Service Core Config And Security module is the infrastructure backbone of the OpenFrame API service. It ensures:
While lightweight in terms of business logic, it is critical to the correctness, security, and stability of the API layer.