Improve formatting of the docs (#39)

* Disable maximum line length for Markdown files to allow semantic line breaks Signed-off-by: Tim Walter <[email protected]> * Fix some Markdown formatting Signed-off-by: Tim Walter <[email protected]> * Use semantic line breaks and fix some typos and phrasing issues Signed-off-by: Tim Walter <[email protected]> --------- Signed-off-by: Tim Walter <[email protected]>
iteratec · Oct 2, 2024 · 130f7d9 · 130f7d9
1 parent c815b71
commit 130f7d9
Show file tree

Hide file tree

Showing 16 changed files with 249 additions and 316 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,17 @@
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.md]
+indent_size = 4
+max_line_length = off
+ij_markdown_wrap_text_if_long = false
diff --git a/README.md b/README.md
@@ -9,32 +9,30 @@
 
 [![last release status](https://github.com/iteratec/kcwarden/actions/workflows/publish.yaml/badge.svg)](https://github.com/iteratec/kcwarden/actions/workflows/publish.yaml)
 
-**[kcwarden](https://iteratec.github.io/kcwarden/) checks your Keycloak configuration for common misconfigurations and
-security vulnerabilities.**
+**[kcwarden](https://iteratec.github.io/kcwarden/) checks your Keycloak configuration for common misconfigurations and security vulnerabilities.**
 
 ## 🚀 Getting started
 
 Install it using Python:
 
-````shell
+```shell
 pip install kcwarden
-````
+```
 
 For details and other methods, see our [documentation](https://iteratec.github.io/kcwarden/installation/).
 
 ## ▶️ Usage
 
 Download your Keycloak's config:
 
-````shell
+```shell
 kcwarden download --realm $REALM --user admin --output config.json $KEYCLOAK_BASE_URL
-````
+```
 
 and run the checks against it:
 
-````shell
+```shell
 kcwarden audit config.json
-````
+```
 
 For more information, see the [documentation on the project website](https://iteratec.github.io/kcwarden/).
-
diff --git a/docs/auditors/clients.md b/docs/auditors/clients.md
diff --git a/docs/auditors/idp.md b/docs/auditors/idp.md
@@ -3,7 +3,8 @@ title: IDP
 ---
 
 # IDP Misconfigurations
-Keycloak can be configured to delegate user authentication to an upstream Identity Provider (IDP) like Google, Azure AD, or an LDAP server. The IDP auditors check for problems related to how this integration is configured.
+Keycloak can be configured to delegate user authentication to an upstream Identity Provider (IDP) like Google, Azure AD, or an LDAP server.
+The IDP auditors check for problems related to how this integration is configured.
 
 !!! info
 
@@ -14,60 +15,44 @@ Keycloak can be configured to delegate user authentication to an upstream Identi
 This auditor warns about Identity Providers configured not to check the signatures of the upstream IDP.
 Not checking the signatures of the tokens the IDP provides is dangerous, as the tokens are no longer cryptographically protected against tampering.
 This may lead to an account takeover or other attacks.
-We strongly recommend to set up signature checks.
+We strongly recommend setting up signature checks.
 
 The auditor supports OIDC, Keycloak OIDC, and SAML IDPs.
 Provider-specific IDPs (like GitHub, GitLab, etc.) do not have an option to disable signature verification and should thus be safe by default.
 
 ## OIDCIdentityProviderWithoutPKCE
 
-This auditor warns about OIDC Identity Providers configured within a realm that do not have the Proof Key for Code
-Exchange (PKCE) enabled. PKCE is a security enhancement for the authorization code flow in OAuth 2.0 and OpenID
-Connect (OIDC) protocols, designed to mitigate several attack vectors, including interception and unauthorized use of
-authorization codes.
+This auditor warns about OIDC Identity Providers configured within a realm that do not have the Proof Key for Code Exchange (PKCE) enabled.
+PKCE is a security enhancement for the authorization code flow in OAuth 2.0 and OpenID Connect (OIDC) protocols, designed to mitigate several attack vectors, including interception and unauthorized use of authorization codes.
 
-The recommendation is for all OIDC Identity Providers, particularly those utilizing the "oidc" or "keycloak-oidc"
-provider types, to enable PKCE and set it to use the "S256" method. This configuration is crucial for protecting against
-attacks on the OIDC protocol by ensuring that the code challenge and verifier mechanism is securely implemented.
+The recommendation is for all OIDC Identity Providers, particularly those using the `oidc` or `keycloak-oidc` provider types, to enable PKCE and set it to use the `S256` method.
+This configuration is crucial for protecting against attacks on the OIDC protocol by ensuring that the _code challenge and verifier mechanism_ is securely implemented.
 
-Identity Providers failing to enable PKCE, leaving it unset (which defaults to disabled), or incorrectly using the "
-plain" method instead of "S256" are flagged by this auditor. Such configurations expose the authentication process to
-potential vulnerabilities, emphasizing the need for immediate corrective actions to uphold security best practices in
-authentication flows.
+Identity Providers failing to enable PKCE, leaving it unset (which defaults to disabled), or incorrectly using the `plain` method instead of `S256` are flagged by this auditor.
+Such configurations expose the authentication process to potential vulnerabilities, emphasizing the need for immediate corrective actions to uphold security best practices in authentication flows.
 
 ## IdentityProviderWithOneTimeSync
 
-This auditor highlights external identity providers (IDPs) configured within Keycloak that are set to only synchronize
-user information from the upstream IDP at the time of the user's first login, without accepting updates on subsequent
-logins. Keycloak's default behavior imports user details (such as name and email address) from the external IDP during
-the user's initial login, but it does not automatically update these details based on subsequent changes in the upstream
-IDP.
+This auditor highlights external identity providers (IDPs) configured within Keycloak that are set to only synchronize user information from the upstream IDP at the time of the user's first login, without accepting updates on later logins.
+Keycloak's default behavior imports user details (such as name and email address) from the external IDP during the user's initial login, but it does not automatically update these details based on later changes in the upstream IDP.
 
 This setup might be by design, intending to prevent overwriting local modifications to user attributes within Keycloak.
-However, if keeping user information in sync with the upstream IDP is required, the auditor recommends considering the
-synchronization mode 'Force'. The 'Force' mode ensures that updates made to a user's information in the upstream IDP are
-imported into Keycloak at every login, potentially overwriting any local changes.
+However, if keeping user information in sync with the upstream IDP is required, the auditor recommends considering the synchronization mode `Force`.
+The `Force` mode ensures that updates made to a user's information in the upstream IDP are imported into Keycloak at every login, potentially overwriting any local changes.
 
-Entities configured without the 'Force' sync mode are identified by this auditor to encourage a review of the intended
-behavior regarding user data synchronization. If the current setup aligns with the organizational requirements, the
-finding can be ignored. Otherwise, updating the sync mode to 'Force' may be advisable to ensure consistent and
-up-to-date user information across systems.
+Entities configured without the `Force` sync mode are identified by this auditor to encourage a review of the intended behavior regarding user data synchronization.
+If the current setup aligns with the organizational requirements, the finding can be ignored.
+Otherwise, updating the sync mode to `Force` may be advisable to ensure consistent and up-to-date user information across systems.
 
 ## IdentityProviderWithMappersWithoutForceSyncMode
 
-This auditor targets Keycloak configurations where external identity providers are set up with Identity Provider Mappers
-but are not configured to update user information from the upstream IDP beyond the initial login. Keycloak's default
-behavior for Identity Provider Mappers is to import data (e.g., group assignments or roles) from the upstream IDP's
-access token only once, during the user's first login, without reflecting any subsequent changes in the upstream IDP.
+This auditor targets Keycloak configurations where external identity providers are set up with Identity Provider Mappers but are not configured to update user information from the upstream IDP beyond the initial login.
+Keycloak's default behavior for Identity Provider Mappers is to import data (e.g., group assignments or roles) from the upstream IDP's access token only once, during the user's first login, without reflecting any later changes in the upstream IDP.
 
-This configuration could lead to security issues or inconsistencies in user permissions if the upstream IDP modifies
-user roles, groups, or other attributes that affect access control within Keycloak-managed services. If the use of
-mappers to assign static groups or roles without future updates is intentional, this finding may be disregarded.
+This configuration could lead to security issues or inconsistencies in user permissions if the upstream IDP modifies user roles, groups, or other attributes that affect access control within Keycloak-managed services.
+If the use of mappers to assign static groups or roles without future updates is intentional, this finding may be disregarded.
 
-However, if dynamic synchronization of user attributes and roles with the upstream IDP is required, it's advised to
-adjust the sync mode to 'Force'. This setting can be applied globally to the IDP, affecting all user data, including
-name and email, or specifically to relevant mappers, allowing for selective updates based on upstream changes.
+However, if dynamic synchronization of user attributes and roles with the upstream IDP is required, it's advised to adjust the sync mode to `Force`.
+This setting can be applied globally to the IDP, affecting all user data, including name and email, or specifically to relevant mappers, allowing for selective updates based on upstream changes.
 
-This finding carries a higher severity compared to the general recommendation for enabling 'Force' sync mode due to the
-explicit use of Identity Provider Mappers, indicating a reliance on upstream IDP data for crucial access control
-decisions.
+This finding carries a higher severity compared to the general recommendation for enabling `Force` sync mode due to the explicit use of Identity Provider Mappers, indicating a reliance on upstream IDP data for crucial access control decisions.
diff --git a/docs/auditors/index.md b/docs/auditors/index.md
@@ -7,9 +7,7 @@ title: Introduction
 kcwarden comes with a number of pre-built detection rules that can detect common Keycloak misconfigurations.
 We call these _auditors_, and each auditor checks for one specific problem.
 There are auditors for OAuth clients, scopes, upstream Identity Provider (IDP) configurations, and realm settings. 
-The auditors are based on a combination of
-the [OAuth 2.0 Security Best Current Practices RFC Draft (Version 24)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-24),
-and additional, Keycloak-specific checks.
+The auditors are based on a combination of the [OAuth 2.0 Security Best Current Practices RFC Draft (Version 24)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-24), and additional, Keycloak-specific checks.
 
 ## Running Auditors
 
@@ -47,21 +45,21 @@ The following areas aren't covered at all:
 - Required Actions
 - Anything related to the implementation of the applications working with the clients (out of scope)
 
-We would be grateful for input on which checks you would like to see - ideally with a description of what exactly to check for, what a good and an insecure configuration would look like, and what the impact of the misconfiguration would be.
-Feel free to open an issue in our GitHub and we'll be happy to add it to the code.
+We would be grateful for input on which checks you would like to see—ideally with a description of what exactly to check for, what a good and an insecure configuration would look like, and what the impact of the misconfiguration would be.
+Feel free to open an issue in our GitHub, and we'll be happy to add it to the code.
 
 ## Silencing Findings
 
 If you run kcwarden for the first time on a Keycloak configuration, chances are that you will receive a large number of
 findings.
-kcwarden tends to err on the side of reporting too much instead of too little, so there are likely to be some findings
-that you don't want to act on because you have good reasons to configure the system in this way, even though it may not
-be 100% compliant with official recommendations.
+kcwarden tends to err on the side of reporting too much instead of too little.
+Thus, there are likely to be some findings that you don't want to act on because you have good reasons to configure the system in this way, even though it may not be 100% compliant with official recommendations.
 In these cases, you can ignore specific findings or entire auditors to prevent kcwarden from reporting them again.
 
 ### Ignoring a Specific Finding
 
-To ignore a specific finding, you can [create a config file](../usage.md#generate-config-template) and add the specific entity that was flagged to the allowlist. For example, if you have a client `mobile_app` that is used by a native mobile application that requires the use of offline access tokens, you can silence the warning about the use of these tokens for this specific client with the following configuration entry:
+To ignore a specific finding, you can [create a config file](../usage.md#generate-config-template) and add the specific entity that was flagged to the allowlist.
+For example, if you have a client `mobile_app` that is used by a native mobile application that requires the use of offline access tokens, you can silence the warning about the use of these tokens for this specific client with the following configuration entry:
 
 ```yaml
 auditors:
@@ -84,4 +82,4 @@ auditors:
   # Due to the use of legacy software, we need to allow client-secret 
   # auth for the forseeable future. Allowlist all clients.
   - .*  
-```
+```