Merge pull request #1231 from adorsys/feat/authentication-config-doc

Feat/authentication config doc

docs/config/Authenticator-Configuration.md

@@ -0,0 +1,69 @@
+## AuthenticatorConfig
+### Introduction
+AuthenticatorConfig is a powerful feature in Keycloak that allows you to customize authentication flows by configuring specific authenticators. This documentation will guide you through using AuthenticatorConfig with the Keycloak Config CLI tool.
+### Syntax
+AuthenticatorConfig is defined within the authenticationFlows section of your Keycloak configuration JSON file. Here's the basic structure:
+```json
+{
+  "authenticationFlows": [
+    {
+      "alias": "my-custom-flow",
+      "authenticationExecutions": [
+        {
+          "authenticator": "auth-username-password-form",
+          "requirement": "REQUIRED",
+          "authenticatorConfig": "my-custom-config"
+        }
+      ]
+    }
+  ],
+  "authenticatorConfig": [
+    {
+      "alias": "my-custom-config",
+      "config": {
+        "key1": "value1",
+        "key2": "value2"
+      }
+    }
+  ]
+}
+```
+### Key Components
+#### Alias
+The alias field is a unique identifier for your AuthenticatorConfig. It's used to reference the configuration from within authentication executions1.
+#### Config
+The config object contains key-value pairs that define the specific settings for your authenticator. The available keys and their meanings depend on the authenticator being configured1.
+#### Common Use Cases
+
+<b>Password Policy Configuration</b>
+
+```json
+{
+  "alias": "password-policy-config",
+  "config": {
+    "passwordPolicy": "length(8) and upperCase(1) and lowerCase(1) and digits(1)"
+  }
+}
+
+OTP Policy Configuration
+json
+{
+  "alias": "otp-config",
+  "config": {
+    "otpType": "totp",
+    "otpHashAlgorithm": "HmacSHA1",
+    "otpPolicyDigits": "6",
+    "otpPolicyPeriod": "30"
+  }
+}
+```
+#### Best Practices
+- `Unique Aliases`: Ensure each AuthenticatorConfig has a unique alias to avoid conflicts1.
+- `Consistent Naming`: Use descriptive and consistent naming conventions for your aliases.
+- `Minimal Configuration`: Only include necessary configuration keys to keep your JSON file clean and manageable.
+- `Version Control`: Store your Keycloak configuration files in a version control system for easy tracking of changes7.
+#### Troubleshooting
+If you encounter issues with your AuthenticatorConfig:
+- Verify that the alias in the authenticatorConfig section matches the one referenced in authenticationExecutions.
+- Check that the config keys are valid for the specific authenticator you're configuring.
+- Ensure that the Keycloak Config CLI tool has the necessary permissions to apply the configuration changes. You can click [here](https://www.keycloak.org/securing-apps/client-registration-cli) for more information

mkdocs.yml

@@ -52,6 +52,7 @@ nav:
       - Remote State Management: config/remote-state-management.md
       - Adding Multiple post.logout.redirect.uris: config/addind-multiple-post-logout-redirect-uris.md
       - Minimal Configurations From exported JSON: config/minimal-configuration.md
+      - Authenticator configuration: config/Authenticator-Configuration.md
 
 
 markdown_extensions: