This is an automated email from the ASF dual-hosted git repository.
ilgrosso pushed a commit to branch 4_1_X
in repository https://gitbox.apache.org/repos/asf/syncope.git
The following commit(s) were added to refs/heads/4_1_X by this push:
new e00f4fd905 [SYNCOPE-1996] Updating docs
e00f4fd905 is described below
commit e00f4fd905c8c1ae9e131eab6174f9585c5a04d2
Author: Francesco Chicchiriccò <[email protected]>
AuthorDate: Tue Sep 8 17:10:08 2026 +0200
[SYNCOPE-1996] Updating docs
---
.../common/validation/PlainSchemaValidator.java | 15 +++
core/starter/src/main/resources/core.properties | 2 -
.../asciidoc/getting-started/movingForward.adoc | 32 +++---
.../reference-guide/architecture/core.adoc | 1 +
.../reference-guide/concepts/extensions.adoc | 2 +-
.../configuration/configuration.adoc | 4 +-
.../configuration/configurationparameters.adoc | 11 --
.../configuration/{jws.adoc => security.adoc} | 83 ++++++++++++--
.../reference-guide/howto/setadmincredentials.adoc | 9 +-
src/main/asciidoc/reference-guide/usage/core.adoc | 124 ++++++++++-----------
10 files changed, 167 insertions(+), 116 deletions(-)
diff --git
a/core/persistence-common/src/main/java/org/apache/syncope/core/persistence/common/validation/PlainSchemaValidator.java
b/core/persistence-common/src/main/java/org/apache/syncope/core/persistence/common/validation/PlainSchemaValidator.java
index 0d5c5302c1..047f880d1e 100644
---
a/core/persistence-common/src/main/java/org/apache/syncope/core/persistence/common/validation/PlainSchemaValidator.java
+++
b/core/persistence-common/src/main/java/org/apache/syncope/core/persistence/common/validation/PlainSchemaValidator.java
@@ -19,6 +19,8 @@
package org.apache.syncope.core.persistence.common.validation;
import jakarta.validation.ConstraintValidatorContext;
+import java.util.Optional;
+import org.apache.syncope.common.lib.types.CipherAlgorithm;
import org.apache.syncope.common.lib.types.EntityViolationType;
import org.apache.syncope.core.persistence.api.entity.PlainSchema;
@@ -55,6 +57,19 @@ public class PlainSchemaValidator extends
AbstractValidator<PlainSchemaCheck, Pl
addPropertyNode("secretKey").addPropertyNode("cipherAlgorithm").addConstraintViolation();
return false;
}
+ if (schema.getCipherAlgorithm() == CipherAlgorithm.AES) {
+ if (Optional.ofNullable(schema.getSecretKey()).
+ map(key -> key.length() != 16 && key.length() !=
24 && key.length() != 32).
+ orElse(true)) {
+
+ context.disableDefaultConstraintViolation();
+ context.buildConstraintViolationWithTemplate(
+ getTemplate(EntityViolationType.InvalidSchema,
+ "SecretKey length requirements not met
for AES: must be either 16, 24 or 32")).
+
addPropertyNode("secretKey").addConstraintViolation();
+ return false;
+ }
+ }
}
default -> {
diff --git a/core/starter/src/main/resources/core.properties
b/core/starter/src/main/resources/core.properties
index c3638aa1d9..b65b6eb625 100644
--- a/core/starter/src/main/resources/core.properties
+++ b/core/starter/src/main/resources/core.properties
@@ -97,8 +97,6 @@ security.jwsKey=${jwsKey}
# * 16 chars => AES-128
# * 24 chars => AES-192
# * 32 chars => AES-256
-#
-# Shorter keys will be padded to the nearest longer option available; keys >
32 will be trucated
security.aesSecretKey=${secretKey}
security.groovyBlacklist=classpath:META-INF/groovy.blacklist
diff --git a/src/main/asciidoc/getting-started/movingForward.adoc
b/src/main/asciidoc/getting-started/movingForward.adoc
index 293517b593..ac67242f85 100644
--- a/src/main/asciidoc/getting-started/movingForward.adoc
+++ b/src/main/asciidoc/getting-started/movingForward.adoc
@@ -19,33 +19,27 @@
== Moving Forward
-Once you have obtained a working installation of Apache Syncope using one of
the methods reported above, you should consider
-reading the
+Once you have obtained a working installation of Apache Syncope using one of
the methods reported above, you should
+consider reading the
ifeval::["{backend}" == "html5"]
-https://syncope.apache.org/docs/4.1reference-guide.html[Apache Syncope
Reference Guide.]
+https://syncope.apache.org/docs/4.1/reference-guide.html[Apache Syncope
Reference Guide.]
endif::[]
ifeval::["{backend}" == "pdf"]
https://syncope.apache.org/docs/4.1/reference-guide.pdf[Apache Syncope
Reference Guide.]
endif::[]
to understand how to configure, extend, customize and deploy your new Apache
Syncope project.
-Before deploying your Apache Syncope installation into production, it is
essential to ensure that the default values for
-various security properties have been changed to values specific to your
deployment.
+Before deploying your Apache Syncope installation into production, it is
[.underline]#essential to ensure that the
+default values for various security properties have been changed to values
specific to your deployment#.
-The following values must be changed from the defaults in the
`core.properties` file:
+The following values **must be changed** from the defaults in the
`core.properties` file:
-* *adminPassword* - The cleartext password as encoded per the
`adminPasswordAlgorithm` value (`SSHA256` by default), the
-default value of which is "password".
-* *secretKey* - The secret key value used for AES ciphering; AES is used by
the use cases below:
- ** if the value for `adminPasswordAlgorithm` is `AES` or the configuration
parameter `password.cipher.algorithm` is
-changed to `AES`
- ** if set for Encrypted Plain Schema instances
- ** for Linked Accounts' password values
- ** to securely store Access Token's cached authorities
- ** within some of the predefined rules used by Password Policies
-* *anonymousKey* - The key value to use for anonymous requests.
-* *jwsKey* - The symmetric signing key used to sign access tokens. See section
4.4.1 "REST Authentication and
-Authorization" of the Reference Guide for more information.
+* `security.adminPassword`
+* `security.anonymousKey`
+* `security.aesSecretKey`
+* `security.jwsKey`
Note that if you installed Syncope using the maven archetype method, then you
will have already supplied custom values
-for `secretKey`, `anonymousKey` and `jwsKey`.
+for `security.aesSecretKey`, `security.anonymousKey` and `security.jwsKey`.
+
+See the
https://syncope.apache.org/docs/4.1/reference-guide.html#security[security
configuration section] for more details.
diff --git a/src/main/asciidoc/reference-guide/architecture/core.adoc
b/src/main/asciidoc/reference-guide/architecture/core.adoc
index e3a2b2090c..4cd9e6f126 100644
--- a/src/main/asciidoc/reference-guide/architecture/core.adoc
+++ b/src/main/asciidoc/reference-guide/architecture/core.adoc
@@ -93,6 +93,7 @@ with no code changes: PostgreSQL, MySQL, MariaDB and Oracle
are fully supported
<<domains>> allow to manage data belonging to different
https://en.wikipedia.org/wiki/Multitenancy[tenants^] into
separate database instances.
+[[security-layer]]
==== Security
Rather than being a separate layer, Security features are triggered throughout
incoming request processing.
diff --git a/src/main/asciidoc/reference-guide/concepts/extensions.adoc
b/src/main/asciidoc/reference-guide/concepts/extensions.adoc
index 4cb70766c2..8167d9b35d 100644
--- a/src/main/asciidoc/reference-guide/concepts/extensions.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/extensions.adoc
@@ -22,7 +22,7 @@ The _vanilla_ Apache Syncope deployment can be optional
enriched with useful fea
every single deployment with unneeded libraries and configurations.
With reference to <<architecture,architecture>>, an extension might add a
<<rest>> endpoint, manage the
-<<persistence,persistence>> of additional entities, extend the
<<security,security>> mechanisms, tweak the
+<<persistence,persistence>> of additional entities, extend the
<<security-layer,security>> mechanisms, tweak the
<<provisioning-layer,provisioning layer>>, add features to the
<<admin-console-component>> or
the <<enduser-component>>, or even bring all such things together.
diff --git a/src/main/asciidoc/reference-guide/configuration/configuration.adoc
b/src/main/asciidoc/reference-guide/configuration/configuration.adoc
index cdeab1759d..56a3d2f16f 100644
--- a/src/main/asciidoc/reference-guide/configuration/configuration.adoc
+++ b/src/main/asciidoc/reference-guide/configuration/configuration.adoc
@@ -48,6 +48,8 @@ include::deployment.adoc[]
include::storage.adoc[]
+include::security.adoc[]
+
include::highavailability.adoc[]
include::domainsmanagement.adoc[]
@@ -58,6 +60,4 @@ include::connectorbundles.adoc[]
include::email.adoc[]
-include::jws.adoc[]
-
include::configurationparameters.adoc[]
diff --git
a/src/main/asciidoc/reference-guide/configuration/configurationparameters.adoc
b/src/main/asciidoc/reference-guide/configuration/configurationparameters.adoc
index e5625a62bb..2a07e19fe6 100644
---
a/src/main/asciidoc/reference-guide/configuration/configurationparameters.adoc
+++
b/src/main/asciidoc/reference-guide/configuration/configurationparameters.adoc
@@ -24,17 +24,6 @@ Most run-time configuration options are available as
parameters and can be tuned
* `password.cipher.algorithm` - which cipher algorithm shall be used for
encrypting password values; supported
algorithms include `SHA-1`, `SHA-256`, `SHA-512`, `AES`, `S-MD5`, `S-SHA-1`,
`S-SHA-256`, `S-SHA-512` and `BCRYPT`;
salting options are available in the `core.properties` file;
-[WARNING]
-The value of the `security.aesSecretKey` property in the `core.properties`
file is used for AES-based encryption /
-decryption: besides password values, this is also used whenever reversible
encryption is needed, throughout the whole
-system. +
-The actual length of the `security.aesSecretKey` value is used to drive the
AES algorithm variant selection:
-16 characters implies `AES-128`, 24 selects `AES-192` and 32 configures
`AES-256`. +
-When the `security.aesSecretKey` value has length less than 16, between 17 and
23 or between 25 and 31, it is
-right-padded by random characters during startup, to reach the nearest option.
If the specified value is instead longer
-than 32 characters, it is truncated to 32. +
-It is *strongly* recommended to provide a value long exactly 16, 24 or 32
characters, in order to avoid unexpected
-behaviors at runtime, expecially with high-availability.
* `jwt.lifetime.minutes` - validity of
https://en.wikipedia.org/wiki/JSON_Web_Token[JSON Web Token^] values used for
<<rest-authentication-and-authorization,authentication>> (in minutes);
* `mfa.enabled` - when `true`, an OTP value generated by the enrolled app is
additionally requested as
diff --git a/src/main/asciidoc/reference-guide/configuration/jws.adoc
b/src/main/asciidoc/reference-guide/configuration/security.adoc
similarity index 59%
rename from src/main/asciidoc/reference-guide/configuration/jws.adoc
rename to src/main/asciidoc/reference-guide/configuration/security.adoc
index 704efe5b88..54fcd57fe1 100644
--- a/src/main/asciidoc/reference-guide/configuration/jws.adoc
+++ b/src/main/asciidoc/reference-guide/configuration/security.adoc
@@ -16,34 +16,93 @@
// specific language governing permissions and limitations
// under the License.
//
-=== Control JWT signature
-As explained <<rest-authentication-and-authorization,above>>, the REST
authentication process generates, in case of
-success, a unique signed JWT (JSON Web Token). +
-Such JWT values are signed by Apache Syncope according to the
https://tools.ietf.org/html/rfc7515[JWS^]
-(JSON Web Signature) specification.
+=== Security
+
+Most security aspects can be configured with the following properties:
+
+[cols="1,1,3",options="header"]
+|===
+|Property
+|Default
+|Description
+|`security.productionMode`
+|`true`
+|Enables or disables the <<production-mode>>.
+|`security.adminUser`
+|`admin`
+|Super-administrator username.
+|`security.adminPasswordAlgorithm`
+|`SSHA256`
+|Supported values are `SHA1`, `SHA256`, `SHA512`, `SMD5`, `SSHA1`, `SSHA512`
and `BCRYPT`.
+|`security.adminPassword`
+|Value from the Maven property `adminPassword`
+|Super-administrator password's hashed value for the selected
`security.adminPasswordAlgorithm`. +
+Check <<set-admin-credentials,how to generate this value>>.
+|`security.adminMfaSecret`
+|Empty
+|Super-administrator's MFA secret (if <<authentiation-credentials,enabled>>). +
+Check <<set-admin-credentials,how to generate this value>>.
+|`security.anonymousUser`
+|`anonymous`
+|Username for <<rest-authorization-summary,anonymous authentication>>.
+|`security.anonymousKey`
+|Value from the Maven property `anonymousKey`
+|Password for <<rest-authorization-summary,anonymous authentication>>.
+|`security.jwtIssuer`
+|`ApacheSyncope`
+|Value used to set the Issuer claim for the JWT values as generated by the
+<<rest-authentication-and-authorization,REST authentication process>>.
+|`security.jwsAlgorithm`
+|`HS512`
+|Algorithm used to sign the JWT values according to the
https://tools.ietf.org/html/rfc7515[JWS^] (JSON Web Signature)
+specification. See <<jws-signature>> for more details.
+|`security.jwsKey`
+|Value from the Maven property `jwsKey`
+|Key used to sign the JWT values according to the
https://tools.ietf.org/html/rfc7515[JWS^] (JSON Web Signature)
+specification. See <<jws-signature>> for more details.
+|`security.aesSecretKey`
+|Value from the Maven property `secretKey`
+|Key used for AES-based encryption / decryption: besides password values, this
is also used whenever reversible
+encryption is needed. +
+The actual value length is used to drive the AES algorithm variant selection:
+16 characters implies `AES-128`, 24 selects `AES-192` and 32 configures
`AES-256`.
+|===
+
+==== Production Mode
+
+Core will refuse to start in case the overall security requirements are not
met: for example, the default credentials
+are in use, invalid keys are configured and so on.
+
+The production mode can be temporarily disabled during the initial phases of
the IAM project, to help out administrators
+with fine-tuning the several security aspects.
+
+For example, when the `security.aesSecretKey` value has length less than 16,
between 17 and 23 or between 25 and 31,
+the configured value is right-padded by random characters during startup, to
reach the nearest option.
+If the specified value is instead longer than 32 characters, it is truncated
to 32. +
+Finally, the resulting value is sent to the debug logs for administrators to
take note and report to configuration.
+
+==== JWS Signature
[[jws-hmac]]
-==== Hash-based Message Authentication Code
+===== Hash-based Message Authentication Code
-This is the default configuration, where Core and clients posses a shared
secret, configured under `core.properties`
-as the `jwsKey` property value.
+This is the default configuration, where Core and clients posses a shared
secret.
-.Default JWS configuration
+.Example JWS HMAC configuration
====
[source,properties]
----
security.jwsAlgorithm=HS512 // <1>
-security.jwsKey=ZW7pRixehFuNUtnY5Se47IemgMryTzazPPJ9CGX5LTCmsOJpOgHAQEuPQeV9A28f
// <2>
+security.jwsKey=<value> // <2>
----
<1> Valid values are `HS256`, `HS384` and `HS512`
<2> Any alphanumeric value satisfying the
https://tools.ietf.org/html/rfc7518#section-3.2[length requirement^] can be
used
====
-
[[jws-rsa]]
-==== RSA Public-Key Cryptography
+===== RSA Public-Key Cryptography
This configuration requires to specify a key pair: the former key value, said
_private_, must be kept secret for internal
Core usage while the latter key value, said _public_, is to be shared with
clients.
diff --git a/src/main/asciidoc/reference-guide/howto/setadmincredentials.adoc
b/src/main/asciidoc/reference-guide/howto/setadmincredentials.adoc
index f4988a5c7c..a990db5575 100644
--- a/src/main/asciidoc/reference-guide/howto/setadmincredentials.adoc
+++ b/src/main/asciidoc/reference-guide/howto/setadmincredentials.adoc
@@ -21,13 +21,8 @@
[WARNING]
The procedures below affects only the `Master` <<domains,domain>>; for other
domains check <<domains-management,above>>.
-The credentials are defined in the `core.properties` file; text encoding must
be set to UTF-8:
-
-* `security.adminUser` - administrator username (default `admin`)
-* `security.adminPassword` - administrator password (default `password`)'s
hashed value
-* `security.adminPasswordAlgorithm` - algorithm to be used for hash evaluation
(default `SSHA256`, also supported are
-`SHA1`, `SHA256`, `SHA512`, `SMD5`, `SSHA1`, `SSHA512` and `BCRYPT`)
-* `security.adminMfaSecret` - administrator MFA secret (no default)
+The admin credentials (password and MFA secret) can be generated by the
following commands and then reported into
+<<security,configuration>>.
.Generate SHA1 password value on GNU / Linux
====
diff --git a/src/main/asciidoc/reference-guide/usage/core.adoc
b/src/main/asciidoc/reference-guide/usage/core.adoc
index 33105e7e69..34dc9fb92e 100644
--- a/src/main/asciidoc/reference-guide/usage/core.adoc
+++ b/src/main/asciidoc/reference-guide/usage/core.adoc
@@ -48,68 +48,6 @@ protocol://host:port/syncope/
....
====
-==== REST Rate Limiting
-Rate limiting can be applied to REST requests before authentication and
request processing.
-
-This feature is disabled by default and can be enabled with the following
properties:
-
-[cols="1,1,3",options="header"]
-|===
-|Property
-|Default
-|Description
-|`rest.rateLimit.enabled`
-|`false`
-|Enables or disables REST request rate limiting.
-|`rest.rateLimit.maxRequests`
-|`300`
-|Maximum number of requests allowed from the same client address within the
configured time window.
-|`rest.rateLimit.window`
-|`1m`
-|Time window used to count requests from the same client address.
-|`rest.rateLimit.lock`
-|`1m`
-|Amount of time for which the client address is blocked after exceeding the
configured request limit.
-|`rest.rateLimit.forwardedForHeader`
-|`X-Forwarded-For`
-|HTTP header used to resolve the original client address when the request
comes from a trusted proxy.
-|`rest.rateLimit.trustedProxies`
-|Empty
-|Set of proxy addresses whose `X-Forwarded-For` header value is
-trusted. The header is ignored for requests not coming from one of these
addresses.
-|`rest.rateLimit.excludedAddresses`
-|Empty
-|Set of client addresses excluded from rate limiting. This is where addresses
for trusted internal clients,
-such as Admin Console or Enduser instances calling the Core REST API, should
be configured when their
-traffic must not be rate limited.
-|===
-
-Addresses are matched exactly as reported by the servlet request remote
address. CIDR ranges and wildcard
-patterns are not supported.
-
-When Core is deployed behind a reverse proxy, configure the proxy address under
-`rest.rateLimit.trustedProxies` to allow for the original client from the
configured `rest.rateLimit.forwardedForHeader`
-to be identified. +
-Add addresses to `rest.rateLimit.excludedAddresses` only for callers that
should bypass rate limiting
-entirely, for example trusted Console instances or internal monitoring clients.
-
-Example:
-[source,properties]
-----
-rest.rateLimit.enabled=true
-rest.rateLimit.maxRequests=300
-rest.rateLimit.window=1m
-rest.rateLimit.lock=1m
-rest.rateLimit.trustedProxies=127.0.0.1
-rest.rateLimit.excludedAddresses=127.0.0.1,10.0.0.10
-----
-When the limit is exceeded, the following HTTP response is returned:
-[source]
-----
-HTTP/1.1 429 Too Many Requests
-Retry-After: <seconds>
-----
-
==== REST Authentication and Authorization
The <<core>> authentication and authorization is based on
https://spring.io/projects/spring-security[Spring Security^].
@@ -370,6 +308,68 @@ the <<entitlements,entitlements>> owned by the requesting
user.
When invoking the REST endpoint `/users/self` in `GET`, the
`X-Syncope-Delegations` response header will list all
delegating users for each <<delegation,Delegation>> for which the requesting
user is delegated.
+==== REST Rate Limiting
+Rate limiting can be applied to REST requests before authentication and
request processing.
+
+This feature is disabled by default and can be enabled with the following
properties:
+
+[cols="1,1,3",options="header"]
+|===
+|Property
+|Default
+|Description
+|`rest.rateLimit.enabled`
+|`false`
+|Enables or disables REST request rate limiting.
+|`rest.rateLimit.maxRequests`
+|`300`
+|Maximum number of requests allowed from the same client address within the
configured time window.
+|`rest.rateLimit.window`
+|`1m`
+|Time window used to count requests from the same client address.
+|`rest.rateLimit.lock`
+|`1m`
+|Amount of time for which the client address is blocked after exceeding the
configured request limit.
+|`rest.rateLimit.forwardedForHeader`
+|`X-Forwarded-For`
+|HTTP header used to resolve the original client address when the request
comes from a trusted proxy.
+|`rest.rateLimit.trustedProxies`
+|Empty
+|Set of proxy addresses whose `X-Forwarded-For` header value is
+trusted. The header is ignored for requests not coming from one of these
addresses.
+|`rest.rateLimit.excludedAddresses`
+|Empty
+|Set of client addresses excluded from rate limiting. This is where addresses
for trusted internal clients,
+such as Admin Console or Enduser instances calling the Core REST API, should
be configured when their
+traffic must not be rate limited.
+|===
+
+Addresses are matched exactly as reported by the servlet request remote
address. CIDR ranges and wildcard
+patterns are not supported.
+
+When Core is deployed behind a reverse proxy, configure the proxy address under
+`rest.rateLimit.trustedProxies` to allow for the original client from the
configured `rest.rateLimit.forwardedForHeader`
+to be identified. +
+Add addresses to `rest.rateLimit.excludedAddresses` only for callers that
should bypass rate limiting
+entirely, for example trusted Console instances or internal monitoring clients.
+
+Example:
+[source,properties]
+----
+rest.rateLimit.enabled=true
+rest.rateLimit.maxRequests=300
+rest.rateLimit.window=1m
+rest.rateLimit.lock=1m
+rest.rateLimit.trustedProxies=127.0.0.1
+rest.rateLimit.excludedAddresses=127.0.0.1,10.0.0.10
+----
+When the limit is exceeded, the following HTTP response is returned:
+[source]
+----
+HTTP/1.1 429 Too Many Requests
+Retry-After: <seconds>
+----
+
==== Batch
Batch requests allow grouping multiple operations into a single HTTP request
payload. +
