se.security.introduction.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2018, 2024 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.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= Security Introduction
:description: Helidon Security introduction
:keywords: helidon, security
:feature-name: Security
:rootdir: {docdir}/../..
include::{rootdir}/includes/se.adoc[]
== Contents
- <>
- <>
- <>
== Overview
Helidon Security provides authentication, authorization, and auditing for your Helidon application. It includes the following features:
. Authentication - support for authenticating incoming requests, creating a
security Subject with Principal and Grants. Principal represents current user/service.
Grant may represent a Role, Scope etc.
Responsibility to create Principals and Grants lies with AuthenticationProvider
SPI. The following Principals are expected and supported by default:
.. UserPrincipal - the party is an end-user (e.g. a person) - there can be zero to
one user principals in a subject
.. ServicePrincipal - the party is a service (e.g. a computer program) - there can
be zero to one service principals in a subject
. Authorization - support for authorizing incoming requests. Out-of-the-box the
security module supports ABAC and RBAC (Attribute based access control and Role based
access control). RBAC is handled through RolesAllowed annotation (for integrations that
support injection).
. Outbound security - support for propagating identity or (in general) securing
outbound requests. Modification of a request to include outbound security is
responsibility of OutboundSecurityProvider SPI
. Audit - security module audits most important events through its own API
(e.g. Authentication events, Authorization events, outbound security events).
A default AuditProvider is provided as well, logging to Java util logging (JUL)
logger called "AUDIT" (may be overridden through configuration). AuditProvider
SPI may be implemented to support other auditing options.
Each feature is implemented with the help of "xref:providers.adoc[Security Providers]".
Security module is quite HTTP centric (as most common use cases are related to
HTTP REST), though it is not HTTP specific (the security module may be used to
secure even other transports, such as JMS, Kafka messages etc. if an appropriate
integration module is developed, as all APIs can be mapped to a non-HTTP
protocol). Nevertheless, there may be security providers that only make sense with
HTTP (such as HTTP digest authentication).
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.security
helidon-security
----
== Usage
To integrate with a container, or to use Security standalone, we must
create an instance of security.
In general, Security supports three approaches
- a fluent-API builder pattern - you configure everything "by hand"
- a configuration based pattern - you configure everything in a configuration file
- hybrid - you load a builder from configuration and update it in a program
Once a security instance is built, it can be used to initialize an
xref:containers-integration.adoc[integration with a container], or to
use security from a program directly:
[source,java]
.Security direct usage
----
include::{sourcedir}/se/security/IntroductionSnippets.java[tag=snippet_1, indent=0]
----
<1> Create a security context
<2> Use the context to authenticate a request
=== Builder Pattern
[source,java]
.Security through a builder
----
include::{sourcedir}/se/security/IntroductionSnippets.java[tag=snippet_2, indent=0]
----
<1> Create a provider instance based on the provider documentation
=== Configuration Pattern
See xref:tools.adoc[Secure config] for details about encrypting passwords in
configuration files.
[source,java]
.Security from configuration
----
include::{sourcedir}/se/security/IntroductionSnippets.java[tag=snippet_3, indent=0]
----
<1> Uses `io.helidon.Config`
As mentioned above, security features are implemented through providers, which are configured under key
`security.providers`. Each element of the list is one security provider. The key of the provider must match
its config key (as documented in xref:providers.adoc[Security Providers] for each supported provider).
A key `enabled` can be used for each provider to provide fine control of which providers are enabled/disabled, for example
to support different setup in testing and in production environments.
[source,yaml]
.Security from configuration - application.yaml
----
# Uses config encryption filter to encrypt passwords
security:
providers:
- abac:
- http-basic-auth:
realm: "helidon"
users:
- login: "jack"
password: "${CLEAR=password}"
roles: ["user", "admin"]
- login: "jill"
password: "${CLEAR=password}"
roles: ["user"]
----
==== Overriding Configuration
When a configuration needs to be overridden, we may have problems with the list
type of the `providers` configuration. To simplify overrides using properties,
you can explicitly set up a type of provider using a `type` key.
Example:
[source,properties]
----
security.providers.1.type=header-atn
security.providers.1.header-atn.authenticate=false
----
Would explicitly override the second provider (`http-basic-auth` in example above) with
`header-atn` provider. Note that the `type` and the key of the provider must match.
=== Hybrid Pattern (Builder with Configuration)
[source,java]
.Security from configuration and builder
----
include::{sourcedir}/se/security/IntroductionSnippets.java[tag=snippet_4, indent=0]
----
<1> Uses io.helidon.Config
<2> Or reverse order
© 2015 - 2025 Weber Informatics LLC | Privacy Policy