KeyCloak 26.1.3权限标签未显示，启用相关特性仍异常

问题背景 #

为Teams Tab App配置令牌交换功能，需将Entra令牌转换为KeyCloak令牌，已通过KC_FEATURE=preview,token-exchange,admin-fine-grained-authz启用特性，且kc.sh show-config验证特性已激活，但管理控制台仍看不到Permissions标签。以下是当前Docker Compose配置及证书生成脚本：

Docker Compose配置 #

services:
  idp2-database:
    image: postgres:17.0
    volumes:
      - ./docker-volumes/userDatabase2:/var/lib/postgresql/data
    restart: always
    ports:
      - "45001:5432"
    environment:
      POSTGRES_DB: userDb
      POSTGRES_USER: keycloakUser
      POSTGRES_PASSWORD: keycloakUser
    container_name: idp2-database
    networks:
      - keycloak2-and-postgres-network
    healthcheck:
      test: ["CMD", "psql", "-U", "keycloakUser", "-d", "userDb", "-c", "SELECT 1"]
      interval: 10s
      timeout: 5s
      retries: 5

  idp2-keycloak:
    image: quay.io/keycloak/keycloak:26.1.3
    container_name: idp2-keycloak
    restart: always
    command: ["start", "--https-certificate-file=/opt/keycloak/certs/tls.crt", "--https-certificate-key-file=/opt/keycloak/certs/tls.key", "--spi-theme-static-max-age=-1", "--spi-theme-cache-themes=false", "--spi-theme-cache-templates=false"]
    environment:
      # features (token-exchange, admin-fine-grained-authz)
      - KC_FEATURE=preview,token-exchange,admin-fine-grained-authz

      # admin user
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin

      # database
      - KC_DB=postgres
      - KC_DB_URL=jdbc:postgresql://idp2-database:5432/userDb
      - KC_DB_USERNAME=keycloakUser
      - KC_DB_PASSWORD=keycloakUser

      # health
      - KC_HEALTH_ENABLED=true

      # logging
      - KEYCLOAK_LOGLEVEL=DEBUG

      # hosting
      - KC_HOSTNAME=localhost
      - KEYCLOAK_FRONTEND_URL=https://localhost:45000/auth
      - KC_HOSTNAME_STRICT=false
      - KC_HOSTNAME_STRICT_HTTPS=true
      - KC_HTTP_ENABLED=false
      - KC_HTTPS_PORT=8443
      # - KC_HTTP_MAX_HEADER_SIZE=32768 
      - QUARKUS_HTTP_HTTP2=false
      
    ports:
      - "45000:8443"
    volumes:
      - ./docker-volumes/keycloak2/standalone/data:/opt/keycloak/standalone/data
      - ./docker-volumes/keycloak2/certs:/opt/keycloak/certs
      - ../src/themes:/opt/keycloak/themes
      - ./docker-volumes/keycloak2/providers:/opt/keycloak/providers
      - ./docker-volumes/keycloak2/standalone/configuration:/opt/keycloak/standalone/configuration
    depends_on:
      idp2-database:
        condition: service_healthy
    networks:
      - keycloak2-and-postgres-network

networks:
  keycloak2-and-postgres-network:

证书生成脚本 #

openssl req -newkey rsa:2048 -nodes \
  -keyout ./docker-volumes/keycloak/certs/tls.key \
  -x509 -days 365 \
  -out ./docker-volumes/keycloak/certs/tls.crt \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,DNS:127.0.0.1"

排查与解决方案 #

1. 修正证书路径不一致问题 #

当前证书脚本输出路径为./docker-volumes/keycloak/certs，但KeyCloak容器挂载的是./docker-volumes/keycloak2/certs，路径不匹配会导致HTTPS启动异常，先修正脚本：

openssl req -newkey rsa:2048 -nodes \
  -keyout ./docker-volumes/keycloak2/certs/tls.key \
  -x509 -days 365 \
  -out ./docker-volumes/keycloak2/certs/tls.crt \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,DNS:127.0.0.1"

2. 确保特性初始化生效 #

KeyCloak的特性是在首次初始化数据库时注册的，若之前已启动过容器，后续修改KC_FEATURE不会自动更新数据库状态，需二选一操作：

• 清理数据库挂载目录./docker-volumes/userDatabase2，重新初始化
• 在KeyCloak启动命令中添加--auto-build参数，强制应用特性变更：

  command: ["start", "--auto-build", "--https-certificate-file=/opt/keycloak/certs/tls.crt", "--https-certificate-key-file=/opt/keycloak/certs/tls.key", "--spi-theme-static-max-age=-1", "--spi-theme-cache-themes=false", "--spi-theme-cache-templates=false"]
  

3. 给管理员账号添加权限 #

即使特性已启用，管理员账号需拥有manage-authorization权限才能看到Permissions标签：

• 进入管理控制台 → Realm Settings → Roles → Client Roles选择realm-management
• 找到manage-authorization角色，添加到当前管理员账号的角色映射中

4. 验证特性是否真的生效 #

除了kc.sh show-config，还可通过API验证：
发送GET请求到https://localhost:45000/auth/admin/realms/master/server-info，查看返回结果的enabledFeatures字段是否包含admin-fine-grained-authz

内容的提问来源于stack exchange，提问作者Ni2Be