Skip to content

Declarative security docs #10865

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+112 −313
Open

Declarative security docs #10865

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a079f49
Documentation of service registry services. Fixes to existing modules…
tomas-langer Nov 27, 2025
98129f1
Update to declarative documentation, added security.
tomas-langer Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions common/mapper/src/main/java/io/helidon/common/mapper/MappersImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2019, 2024 Oracle and/or its affiliates.
* Copyright (c) 2019, 2025 Oracle and/or its affiliates.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -33,7 +33,6 @@
* Implementation of {@link io.helidon.common.mapper.Mappers}.
*/
@SuppressWarnings("removal")
@Service.Singleton
final class MappersImpl implements MapperManager, Mappers {
private final Map<ClassCacheKey, Mapper<?, ?>> classCache = new ConcurrentHashMap<>();
private final Map<GenericCacheKey, Mapper<?, ?>> typeCache = new ConcurrentHashMap<>();
Expand Down
19 changes: 19 additions & 0 deletions docs/src/main/asciidoc/se/injection/declarative.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ The following features are currently implemented:
- <<Dec-FT, Fault Tolerance>>
- <<Dec-Scheduling, Scheduling>>
- <<Dec-Validation, Validation>>
- <<Dec-Security, Security>>

A Helidon Declarative application should be started using the generated application binding, to ensure no lookup and no reflection.
The call to `ServiceRegistryManager.start` ensures that all services with a defined `RunLevel` are started, including Helidon WebServer, Scheduled services etc.
Expand Down Expand Up @@ -371,3 +372,21 @@ For each constraint annotation, there MUST be a service that validates it.
----
include::{sourcedir}/se/inject/DeclarativeExample.java[tag=snippet_10, indent=0]
----

=== Security [[Dec-Security]]

Security provides protection of WebServer endpoints.

Identity propagation (when using a WebClient) depends on configuration of the client and configuration of security.
We currently do not have declarative way of modifying client behavior.
Copy link

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing article "a" before "declarative way". The sentence should read: "We currently do not have a declarative way of modifying client behavior."

Suggested change
We currently do not have declarative way of modifying client behavior.
We currently do not have a declarative way of modifying client behavior.

Copilot uses AI. Check for mistakes.

Supported annotations:

- `io.helidon.security.annotations.Authenticated` - mark an endpoint or a method as requiring authentication
- `io.helidon.security.annotations.Authorized` - mark an endpoint or a method as requiring authorization
- `io.helidon.security.annotations.Audited` - mark an endpoint or a method as requiring audit logging
- `io.helidon.security.abac.role.RoleValidator.PermitAll` - annotated method does not require any authentication or authorization (even if endpoint does)
- `jakarta.annotation.security.PermitAll` - same as `RoleValidator.PermitAll`
- `jakarta.annotation.security.DenyAll` - annotated method will not be callable with any kind of authentication or authorization
- link:{security-javadoc-base-url}/io/helidon/security/abac/role/RoleValidator.Roles.html[`io.helidon.security.abac.role.RoleValidator.Roles`] - provide a set of roles that can access a resource, implies authentication is required
- `jakarta.annotation.security.RolesAllowed` - same as above (`RoleValidator.Roles`)
125 changes: 92 additions & 33 deletions docs/src/main/asciidoc/service-registry/service_reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,54 +22,113 @@ ifndef::rootdir[:rootdir: {docdir}/..]

= Service Registry Reference

The following section lists all services and modules that provide them, grouped by module.
The following section lists all services and modules that provide them.

Note: this is a work in progress, not listing the full set of contracts yet!

- <<helidon-common-config, Common Config>>
- <<helidon-scheduling, Scheduling>>
- <<helidon-validation, Validation>>
== Service registry contracts

== Module `io.helidon.common.config` [[helidon-common-config]]

[cols="2,1,2,6,5"]
|===
|Contract |Weight |Name qualifier |Description

|`io.helidon.common.config.Config`
|Contract (package, class) |Weight | Module | Description |Qualifiers
.2+|`io.helidon.common.config`
`Config`
|`80`
|`io.helidon.common.config`
|Empty config instance
|N/A
|Common config instance (empty)
|===

== Module `io.helidon.scheduling` [[helidon-scheduling]]

|===
|Contract |Weight |Name qualifier |Description

|`io.helidon.scheduling.TaskManager`
|`90`
|`io.helidon.config`
|Configuration either from meta configuration (config profiles), or from service registry
|N/A
Comment on lines +35 to 44
Copy link

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table row structure is malformed. The .2+ rowspan directive on line 35 indicates that the io.helidon.common.config package name should span 2 rows, but the class name Config on line 36 should be in the same cell (pipe-separated). Currently, they are on separate lines without proper delimiters, breaking the table structure.

The correct format should be:

.2+|`io.helidon.common.config` +
`Config`
|`80`
|`io.helidon.common.config`
|Empty config instance
|N/A
|`90`
|`io.helidon.config`
|Configuration either from meta configuration (config profiles), or from service registry
|N/A

Or use separate entries without rowspan if these are meant to be different contracts.

Copilot uses AI. Check for mistakes.
|Management of scheduled tasks
|===

== Module `io.helidon.validation` [[helidon-validation]]

|===
|Contract |Weight |Name qualifier |Description

|`java.time.Clock`
|`io.helidon.config`
`Config`
|`90`
|`io.helidon.config`
|Configuration either from meta configuration (config profiles), or from service registry
|N/A
Comment on lines +45 to 50
Copy link

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table row appears to be a duplicate of the entry on lines 35-44. Both entries describe io.helidon.config.Config with weight 90 and the same description. If this is intentional to show multiple instances of the same contract, it should be clarified. Otherwise, this duplicate should be removed.

Suggested change
|`io.helidon.config`
`Config`
|`90`
|`io.helidon.config`
|Configuration either from meta configuration (config profiles), or from service registry
|N/A

Copilot uses AI. Check for mistakes.
|Clock used to check calendar related constraints, defaults to current time-zone

|`io.helidon.validation.TypeValidation`
|`io.helidon.scheduling`
`TaskManager`
|`90`
|`io.helidon.scheduling`
|Management of scheduled tasks
|N/A
|`java.time`
`Clock`
|`90`
|`io.helidon.validation`
|Clock used to check calendar related constraints, defaults to current time-zone
|N/A
|`io.helidon.validation`
`TypeValidation`
|`90`
|`io.helidon.validation`
|Methods to validate type annotated with `@Validation.Validated`

|`io.helidon.validation.spi.ConstraintValidatorProvider`
|N/A
|`io.helidon.validation.spi`
`ConstraintValidatorProvider`
|`70`
|Named by the constraint annotation type (for each built-in constraint)
|`io.helidon.validation`
|Constraint validator providers for each built-in constraint

|Named by the constraint annotation type (for each built-in constraint)
|`io.helidon.common.mapper`
`Mappers`
|`100`
|`io.helidon.common.mapper`
|Access to mappers, to map (convert) types
|N/A
|`io.helidon.common.mapper`
`MapperProvider`
|`0.1`
|`io.helidon.common.mapper`
|A provider of mappers
|N/A
|`io.helidon.common.mapper`
`DefaultResolver`
|`100`
|`io.helidon.common.mapper`
|Resolver of defaults annotation to a list of expected types
|N/A
|`*`
|N/A
|`io.helidon.config`
|Injection point of a configured object
|`@Configuration.Value`
Comment on lines +93 to +97
Copy link

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table row has inconsistent formatting. Line 93 shows * as the contract, which appears to be a wildcard, but the formatting doesn't match other rows. The package and class should be in a single cell (first column), but here they seem misaligned. Additionally, there's no Module specified (N/A in column 3), which is inconsistent with the table structure where most entries have a module.

Copilot uses AI. Check for mistakes.
|`io.helidon.config`
`MetaConfig`
|`100`
|`io.helidon.config`
|Config "meta-configuration"
|N/A
|`io.helidon.config`
`MetaConfig`
|`100`
|`io.helidon.config`
|Config source "meta-configuration"
|Named with a config type
Comment on lines +102 to +109
Copy link

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two consecutive entries for io.helidon.config.MetaConfig appear to be duplicates with the same weight (100) and module (io.helidon.config), but different descriptions. The first (lines 99-103) describes "Config meta-configuration" while the second (lines 104-109) describes "Config source meta-configuration" with a different qualifier. If these are intended to represent different service instances, this should be clarified more explicitly in the descriptions or class names.

Suggested change
|Config "meta-configuration"
|N/A
|`io.helidon.config`
`MetaConfig`
|`100`
|`io.helidon.config`
|Config source "meta-configuration"
|Named with a config type
|Config "meta-configuration" (global configuration instance)
|N/A
|`io.helidon.config`
`MetaConfig`
|`100`
|`io.helidon.config`
|Config source "meta-configuration" (per-source configuration instance)
|Qualified by config source type (e.g., `@Named("file")`)

Copilot uses AI. Check for mistakes.
|`io.helidon.webserver.http.spi`
`ErrorHandlerProvider`
|`100`
|N/A
|Error handler provider to add to WebServer
|N/A
|`io.helidon.webserver`
`WebServer`
|`100`
|`io.helidon.webserver`
|WebServer instance, only available in Helidon Declarative
|N/A
|`io.helidon.security`
`Security`
|`100`
|`io.helidon.security`
|Security
|N/A
|`io.helidon.health`
`HealthCheck`
|N/A
|N/A
|Health check instances to be added to WebServer health observer
|N/A
|===
Loading
Loading