docs(security): update generic-security.md (#43)

Enhanced "Generic Security.md" file by adding

introduction and disclaimer
new section "limiting user sessions"
updating existing sections (minor adjustments on wording and details)

---------

Co-authored-by: Phil Schneider <[email protected]>

docs/static/authenticationflow.png.license

@@ -0,0 +1,5 @@
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+- SPDX-License-Identifier: CC-BY-4.0
+- SPDX-FileCopyrightText: Copyright (c) 2021, 2023 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-assets

docs/technical documentation/10. Generic Security.md

@@ -1,5 +1,23 @@
 ## Security Generic
 
+This document serves as a introduction for the security config of the catena-x reference implementation with Keycloak. The settings outlined are designed to provide a robust security framework for test environments - ensuring the integrity, confidentiality, and availability of our system and data.
+
+Disclaimer:
+The configurations suggested in this file are starting points and should be adapted to meet the specific security requirements of your environment. It's important to regularly review and update these settings to adapt to new threats and changing organizational needs.
+
+Please proceed with caution and consult security experts as needed when implementing these configurations.
+
+- [Host](#host)
+- [Bruce Force Detection](#bruce-force-detection)
+- [Clickjacking](#clickjacking)
+- [Open Redirects](#open-redirects)
+- [Compromised Authorization code](#compromised-authorization-code)
+- [Compromised access and refresh tokens](#compromised-access-and-refresh-tokens)
+- [CSRF attack](#csrf-attack)
+- [Limiting Scope - Client Token](#limiting-scope---client-token)
+- [Client Policies](#client-policies)
+- [Limiting User Sessions](#limiting-user-sessions)
+
 ### Host
 
 Keycloak uses the public hostname in several ways, such as within token issuer fields and URLs in password reset emails.
@@ -8,7 +26,6 @@ By default, the hostname derives from the request header. No validation exists t
 
 The hostname’s Service Provider Interface (SPI) provides a way to configure the hostname for requests. You can use this built-in provider to set a fixed URL for frontend requests while allowing backend requests based on the request URI. If the built-in provider does not have the required capability, you can develop a customized provider.
 
-
 ### Bruce Force Detection
 
 A brute force attack happens when an attacker is trying to guess a user’s password multiple times. Keycloak has some limited brute force detection capabilities. If turned on, a user account will be temporarily disabled if a threshold of login failures is reached. To enable this feature go to the Realm Settings left menu item, click on the Security Defenses tab, then additional go to the Brute Force Detection sub-tab.
@@ -21,7 +38,6 @@ When a user is temporarily locked and attempts to log in, {project_name} display
 
 Details: https://www.keycloak.org/docs/latest/server_admin/index.html#password-guess-brute-force-attacks
 
-
 Config:
 
 1. Click Realm Settings in the menu
@@ -32,26 +48,25 @@ Brute force detection
 
 ![BruteForce](/docs/static/brute-force.png)
 
-
 Common Parameters
 
 ![CommonParameters](/docs/static/common-parameters.png)
 
-
 #### Catena-X configuration
 
 ##### Preventing automated attacks
 
 - Lock after 10 subsequent login failures
 - 1 second between failures (too quick for a human)
-- Lock remains active for ~5 min
+- Lock remains active for ~15 min
 
 ##### Preventing manual attacks
 
 - Lock after 10 subsequent login failures
 - Sliding window of 12 hours
-- Lock remains active for ~ 45 min
+- Lock remains active for ~ 15 min
 
+Brute force detection activation is highly recommended and configures as part of the reference solution.
 
 ### Clickjacking
 
@@ -68,14 +83,12 @@ In the Admin Console, you can specify the values of the X-FRAME_OPTIONS and Cont
 
 By default, Keycloak sets up a same-origin policy for iframes.
 
-
-### Open redirections
+### Open redirects
 
 An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without validation. An attacker can use the end-user authorization endpoint and the redirect URI parameter to use the authorization server as an open redirector, using a user’s trust in an authorization server to launch a phishing attack.
 
 Keycloak requires that all registered applications and clients register at least one redirection URI pattern. When a client requests that Keycloak performs a redirect, Keycloak checks the redirect URI against the list of valid registered URI patterns. Clients and applications must register as specific a URI pattern as possible to mitigate open redirector attacks.
 
-
 ### Compromised Authorization code
 
 For the OIDC Auth Code Flow, Keycloak generates a cryptographically strong random value for its authorization codes. An authorization code is used only once to obtain an access token.
@@ -86,7 +99,6 @@ You can also defend against leaked authorization codes by applying Proof Key for
 
 -- not yet considered in CX --
 
-
 ### Compromised access and refresh tokens
 
 Keycloak includes several actions to prevent malicious actors from stealing access tokens and refresh tokens. The crucial action is to enforce SSL/HTTPS communication between {project_name} and its clients and applications. {project_name} does not enable SSL by default.
@@ -97,7 +109,6 @@ In the current project phase, we will proceed with the default values for the to
 
 ![Tokens](/docs/static/tokens.png)
 
-
 ### CSRF attack
 
 A Cross-site request forgery (CSRF) attack uses HTTP requests from users that websites have already authenticated. Any site using cookie-based authentication is vulnerable to CSRF attacks. You can mitigate these attacks by matching a state cookie against a posted form or query parameter.
@@ -108,7 +119,6 @@ The {project_name} Admin Console is a JavaScript/HTML5 application that makes RE
 
 The user account management section in {project_name} can be vulnerable to CSRF. To prevent CSRF attacks, {project_name} sets a state cookie and embeds the value of this cookie in hidden form fields or query parameters within action links. {project_name} checks the query/form parameter against the state cookie to verify that the user makes the call.
 
-
 ### Limiting Scope - Client Token
 
 By default, new client applications have unlimited role scope mappings. Every access token for that client contains all permissions that the user has. If an attacker compromises the client and obtains the client’s access tokens, each system that the user can access is compromised.
@@ -117,11 +127,23 @@ Limit the roles of an access token by using the Scope menu for each client. Alte
 
 For any clients in CX, the scope is limited to the client scope.
 
-
 ### Client Policies
 
 tbd
 
+### Limiting User Sessions
+
+With the possibility "Limiting User Session" the number of sessions a user can run at once can get limited. When a user reaches the user session limit, they must end their current user sessions before they begin a new session.
+
+As part of the reference solution - the limit is not configured - it is up to the respective operator and env. owner to decide if the session limit is used/configured.
+If a configuration is planned, the limit needs to get configured as part of the realm authentication flow setup.
+
+![Tokens](/docs/static/authenticationflow.png)
+
+The flow that you must configure depends on how you authenticate users:
+
+- Configure a browser flow if you use local or LDAP/AD authentication
+- Configure a post-sign in client flow if you use SSO
 
 ## NOTICE