Authenticator configuration

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:

{
  "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

Password Policy Configuration

{
  "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 for more information