FINERACT-2310: collate and improve security documentation

* fix various typos, spacing, formatting issues
* fix links to legacy docs in API docs
* update keycloak oauth dev instructions
* update default oauth URL for latest Keycloak
* use consistent quoting in oauth docs (single quotes)
* use asciidoc auto-enumerated lists whenever possible
* migrate security topics from readme into asciidoc: oauth, 2FA, HTTPS
* move :hardbreaks: setting to config file so all config settings are in one place. (I think it's fine that `license.adoc` will use hardbreaks -- that's how the plain text version is formatted so it should look more familiar)
* add intro to security chapter
* migrate in Securing Fineract wiki content from https://cwiki.apache.org/confluence/display/FINERACT/Securing+Fineract
* just say "oauth" (not "oauth2") to conform terminology throughout docs -- OAuth 2.0 is just the latest version
* cross-ref HTTPS section from Securing Fineract
* reposition hardening options as tips
* see also: https://lists.apache.org/thread/81qdxttffp6wn23c48zvk93hc13373qv
* simplify/clarify example oauth curl requests
  * Testing just now and I didn't need --location.
  * Also I imagine folks will need --insecure with the self-signed default cert in dev.
* don't change default oauth URL
  * no surprises for existing deployments
  * clarifies the keycloak v26 example
This commit is contained in:
Adam Monsen
2025-06-16 15:12:55 -07:00
parent 2c77f6a277
commit f28d252f17
16 changed files with 199 additions and 96 deletions
+3 -43
View File
@@ -86,46 +86,9 @@ The tenants database connection details are configured [via environment variable
<br>SECURITY
============
NOTE: The HTTP Basic and OAuth2 authentication schemes are mutually exclusive. You can't enable them both at the same time. Fineract checks these settings on startup and will fail if more than one authentication scheme is enabled.
If you believe you have found a security vulnerability, [let us know privately](https://fineract.apache.org/#contribute).
HTTP Basic Authentication
------------
By default Fineract is configured with a HTTP Basic Authentication scheme, so you actually don't have to do anything if you want to use it. But if you would like to explicitly choose this authentication scheme then there are two ways to enable it:
1. Use environment variables (best choice if you run with Docker Compose):
```
FINERACT_SECURITY_BASICAUTH_ENABLED=true
FINERACT_SECURITY_OAUTH_ENABLED=false
```
2. Use JVM parameters (best choice if you run the Spring Boot JAR):
```
java -Dfineract.security.basicauth.enabled=true -Dfineract.security.oauth.enabled=false -jar fineract-provider.jar
```
<br>OAuth2 AUTHENTICATION
------------
There is also an OAuth2 authentication scheme available. Again, two ways to enable it:
1. Use environment variables (best choice if you run with Docker Compose):
```
FINERACT_SECURITY_BASICAUTH_ENABLED=false
FINERACT_SECURITY_OAUTH_ENABLED=true
```
2. Use JVM parameters (best choice if you run the Spring Boot JAR):
```
java -Dfineract.security.basicauth.enabled=false -Dfineract.security.oauth.enabled=true -jar fineract-provider.jar
```
TWO FACTOR AUTHENTICATION (2FA)
------------
You can also enable 2FA authentication. Depending on how you start Fineract add the following:
1. Use environment variable (best choice if you run with Docker Compose):
```
FINERACT_SECURITY_2FA_ENABLED=true
```
2. Use JVM parameter (best choice if you run the Spring Boot JAR):
```
-Dfineract.security.2fa.enabled=true
```
For details about security during development and deployment, see <https://fineract.apache.org/docs/current/#_security>.
<br>INSTRUCTIONS: How to build a WAR file
@@ -313,10 +276,7 @@ NOTE: we'll keep backwards compatibility until one of the next releases to ensur
<br>SSL CONFIGURATION
=================
Read also [the HTTPS related doc](fineract-doc/src/docs/en/chapters/deployment/https.adoc).
By default SSL is enabled, but all SSL related properties are now tunable. SSL can be turned off by setting the environment variable `FINERACT_SERVER_SSL_ENABLED` to false. If you do that then please make sure to also change the server port to `8080` via the variable `FINERACT_SERVER_PORT`, just for the sake of keeping the conventions.
You can choose now easily a different SSL keystore by setting `FINERACT_SERVER_SSL_KEY_STORE` with a path to a different (not embedded) keystore. The password can be set via `FINERACT_SERVER_SSL_KEY_STORE_PASSWORD`. See the `application.properties` file and the latest Spring Boot documentation (https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html) for more details.
See [the HTTPS related doc](https://fineract.apache.org/docs/current/#_https).
<br>TOMCAT CONFIGURATION