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:

{
  "realm": "test-realm",
  "authenticationFlows": [
    {
      "alias": "custom-browser-flow",
      "description": "Custom browser authentication flow",
      "providerId": "basic-flow",
      "topLevel": true,
      "builtIn": false,
      "authenticationExecutions": [
        {
          "authenticator": "identity-provider-redirector",
          "requirement": "ALTERNATIVE",
          "authenticatorConfig": "identity-provider-redirector-config"
        }
      ]
    }
  ],
  "authenticatorConfig": [
    {
      "alias": "identity-provider-redirector-config",
      "config": {
        "defaultProvider": "keycloak-us-oidc"
      }
    }
  ]
}

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

Authenticator Configuration

When exporting Keycloak configurations using kc.sh export, authenticator configurations include internal Keycloak IDs that are ignored by keycloak-config-cli during import. This documentation explains how to properly handle authenticator configurations for successful imports.

Related issues: #1084

The Problem

Users encounter issues when trying to import authenticator configurations because:

• Exported configurations contain internal Keycloak UUIDs
• keycloak-config-cli ignores the id field and only uses aliases
• Authenticator settings appear missing after import
• UI configurations don't match the expected setup

Example: Problematic Export

{
  "authenticatorConfig": [
    {
      "alias": "keycloak-us-oidc",
      "config": {
        "defaultProvider": "keycloak-us-oidc"
      },
      "id": "d863d33c-de7a-4649-a005-54d6b424f664" 
    }
  ]
}

Result: The authenticator configuration is not applied during import.

Understanding Authenticator Configuration Behavior

How keycloak-config-cli Handles Authenticators

keycloak-config-cli uses aliases instead of internal IDs for referencing authenticators:

1. Alias-based referencing: Uses the alias field to identify authenticators
2. ID field ignored: The id field containing UUIDs is completely ignored
3. Name-based references: All references use names/aliases, not internal IDs

Why IDs Are Ignored

• Environment consistency: IDs are generated by Keycloak and differ between environments
• Reference stability: Names/aliases remain consistent across deployments
• Import reliability: Name-based referencing ensures reliable imports

Solution: Remove ID Fields

Step 1: Export Configuration

# Export from Keycloak
kc.sh export --realm your-realm --dir /path/to/export

Step 2: Clean Exported Configuration

Remove all id fields from authenticatorConfig sections:

Before (problematic):

{
  "authenticatorConfig": [
    {
      "alias": "keycloak-us-oidc",
      "config": {
        "defaultProvider": "keycloak-us-oidc"
      },
      "id": "d863d33c-de7a-4649-a005-54d6b424f664"
    }
  ]
}

After (correct):

{
  "authenticatorConfig": [
    {
      "alias": "keycloak-us-oidc",
      "config": {
        "defaultProvider": "keycloak-us-oidc"
      }
    }
  ]
}

Step 3: Import Clean Configuration

java -jar keycloak-config-cli.jar \
  --keycloak.url=<keycloak-url> \
  --keycloak.user=admin \
  --keycloak.password=admin \
  --import.files.locations=clean-config.json

Complete Examples

Example 1: Single Authenticator Configuration

Configuration file: auth-config.json

{
  "realm": "my-realm",
  "authenticatorConfig": [
    {
      "alias": "keycloak-us-oidc",
      "config": {
        "defaultProvider": "keycloak-us-oidc"
      }
    }
  ]
}

Import command:

java -jar keycloak-config-cli.jar \
  --keycloak.url=<keycloak-url> \
  --keycloak.user=admin \
  --keycloak.password=admin \
  --import.files.locations=auth-config.json

Result: Authenticator configuration is properly applied and visible in the UI.

Example 2: Multiple Authenticator Configurations

Configuration file: multi-auth-config.json

{
  "realm": "my-realm",
  "authenticatorConfig": [
    {
      "alias": "keycloak-us-oidc",
      "config": {
        "defaultProvider": "keycloak-us-oidc"
      }
    },
    {
      "alias": "keycloak-eu-oidc",
      "config": {
        "defaultProvider": "keycloak-eu-oidc"
      }
    }
  ]
}

Example 3: Authenticator with Flow References

Configuration file: auth-flow-config.json

{
  "realm": "my-realm",
  "authenticationFlow": [
    {
      "alias": "browser",
      "description": "browser based authentication",
      "providerId": "basic-flow",
      "topLevel": true,
      "builtIn": false,
      "authenticatorConfig": [
        {
          "config": {},
          "authenticator": "identity-provider-redirector",
          "requirement": "ALTERNATIVE",
          "priority": 0,
          "userSetupAllowed": false,
          "authenticatorFlow": false
        }
      ]
    }
  ],
  "authenticatorConfig": [
    {
      "alias": "identity-provider-redirector-config",
      "config": {
        "defaultProvider": "keycloak-us-oidc"
      }
    }
  ]
}

Automation Scripts

Script to Clean Exported Configuration

File: clean-auth-config.sh

#!/bin/bash

# Remove ID fields from authenticatorConfig sections
CONFIG_FILE="$1"

if [ -z "$CONFIG_FILE" ]; then
  echo "Usage: $0 <config-file>"
  exit 1
fi

# Create backup
cp "$CONFIG_FILE" "$CONFIG_FILE.backup"

# Remove id fields from authenticatorConfig
jq '(.authenticatorConfig // []) |= map(del(.id))' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"

echo "Cleaned authenticatorConfig IDs from $CONFIG_FILE"
echo "Backup saved as $CONFIG_FILE.backup"

Usage:

./clean-auth-config.sh exported-config.json

Script to Export and Clean Automatically

File: export-clean-import.sh

#!/bin/bash

REALM="$1"
KEYCLOAK_URL="$2"
OUTPUT_DIR="$3"

if [ -z "$REALM" ] || [ -z "$KEYCLOAK_URL" ] || [ -z "$OUTPUT_DIR" ]; then
  echo "Usage: $0 <realm> <keycloak-url> <output-dir>"
  exit 1
fi

# Export configuration
echo "Exporting realm configuration..."
kc.sh export --realm "$REALM" --dir "$OUTPUT_DIR"

# Clean authenticatorConfig IDs
echo "Cleaning authenticatorConfig IDs..."
find "$OUTPUT_DIR" -name "*.json" -exec jq '(.authenticatorConfig // []) |= map(del(.id))' {} \; -exec mv {} {}.clean \;

echo "Export and clean completed. Clean files have .clean extension."

Best Practices

1. Always Clean Exported Files

# Make it part of your workflow
kc.sh export --realm my-realm --dir ./export
jq '(.authenticatorConfig // []) |= map(del(.id))' ./export/realm-my-realm.json > ./export/clean-config.json

2. Use Version Control

# Track cleaned configurations
git add ./export/clean-config.json
git commit -m "Add cleaned authenticator configuration"

3. Validate Before Import

# Check configuration syntax
jq empty clean-config.json

# Verify authenticatorConfig structure
jq '.authenticatorConfig' clean-config.json

4. Document Your Authenticator Setups

## Authenticator Configurations

| Alias | Purpose | Config Keys |
|-------|---------|------------|
| keycloak-us-oidc | US OIDC provider | defaultProvider |
| keycloak-eu-oidc | EU OIDC provider | defaultProvider |

Troubleshooting

Authenticator Configuration Not Applied

Symptoms: - Import succeeds but authenticator settings are missing in UI - No error messages during import

Diagnosis:

# Check for ID fields in configuration
jq '.authenticatorConfig | map(has("id")) | any' config.json

Solution: Remove all id fields from authenticatorConfig.

Import Fails with Reference Errors

Symptoms: - Import fails with "authenticator not found" errors - Authentication flow references missing authenticators

Diagnosis:

# Check authenticator aliases
jq -r '.authenticatorConfig[].alias' config.json

# Check flow references
jq -r '.authenticationFlow[].authenticator' config.json

Solution: Ensure all referenced authenticators are defined.

Configuration Works in One Environment but Not Another

Symptoms: - Configuration works in development but fails in production - Different environments have different authenticator setups

Cause: Environment-specific authenticator configurations or aliases.

Solution: Standardize authenticator aliases across environments or use environment-specific configuration files.

Related Issues and References

• Issue #1084 - authenticatorConfig is ignored
• Authentication Flows Documentation
• Authenticator Configuration

Additional Resources

• Keycloak Export/Import Guide
• keycloak-config-cli Configuration Reference