支持控制台（Console）开发人员开始试用联系人

17.6. realm 操作

创建新域

在 realm 端点上使用 create 命令来创建新的启用的域。将属性设置为 realm 并启用。 

$ kcadm.sh create realms -s realm=demorealm -s enabled=true

红帽构建的 Keycloak 默认禁用域。您可以通过启用它来立即使用 realm 进行身份验证。

新对象的描述也可以是 JSON 格式。 

$ kcadm.sh create realms -f demorealm.json

您可以直接向文件发送带有 realm 属性的 JSON 文档，或者将文档传送到标准输入。

例如：

  • linux: 

    $ kcadm.sh create realms -f - << EOF
{ "realm": "demorealm", "enabled": true }
EOF

  • Windows： 

    c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f -

列出现有域

此命令返回所有域的列表。 

$ kcadm.sh get realms
注意

红帽构建的 Keycloak 会过滤服务器上的域列表，以返回用户只能看到的域。

所有 realm 属性的列表都非常详细，大多数用户都对属性的子集感兴趣，如 realm name 和 enabled realm 的状态。您可以使用 --fields 选项指定要返回的属性。 

$ kcadm.sh get realms --fields realm,enabled

您可以使用逗号分隔的值显示结果。 

$ kcadm.sh get realms --fields realm --format csv --noquotes

获取特定域

将 realm 名称附加到集合 URI，以获取单个域。 

$ kcadm.sh get realms/master

更新域

  1. 当您不想更改所有域属性时，请使用 -s 选项为属性设置新值。

    例如： 

    $ kcadm.sh update realms/demorealm -s enabled=false

  2. 如果要将所有可写属性设置为新值：

    1. 运行 get 命令。
    2. 编辑 JSON 文件中的当前值。

    3. 重新提交。

      例如： 

      $ kcadm.sh get realms/demorealm > demorealm.json
$ vi demorealm.json
$ kcadm.sh update realms/demorealm -f demorealm.json

删除域

运行以下命令以删除域： 

$ kcadm.sh delete realms/demorealm

打开域的所有登录页面选项

将控制特定功能的属性设置为 true。

例如： 

$ kcadm.sh update realms/demorealm -s registrationAllowed=true -s registrationEmailAsUsername=true -s rememberMe=true -s verifyEmail=true -s resetPasswordAllowed=true -s editUsernameAllowed=true

列出 realm 密钥

对目标域的 key 端点使用 get 操作。 

$ kcadm.sh get keys -r demorealm

生成新的 realm 密钥

  1. 在添加新的 RSA 生成的密钥对前，获取目标域的 ID。

    例如： 

    $ kcadm.sh get realms/demorealm --fields id --format csv --noquotes

  2. 添加一个优先级高于现有提供程序的新密钥提供程序，如 kcadm.sh get keys -r demorealm 所示。

    例如：

    • linux: 

      $ kcadm.sh create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keySize=["2048"]'

    • Windows： 

      c:\> kcadm create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keySize=[\"2048\"]"

  3. 将 parentId 属性设置为目标域 ID 的值。

    新添加的密钥现在是活跃的密钥，如 kcadm.sh get keys -r demorealm 所示。

从 Java Key Store 文件添加新的域密钥

  1. 添加新密钥提供程序，以作为 JKS 文件预先准备添加新密钥对。

    例如，在：

    • linux: 

      $ kcadm.sh create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keystore=["/opt/keycloak/keystore.jks"]' -s 'config.keystorePassword=["secret"]' -s 'config.keyPassword=["secret"]' -s 'config.keyAlias=["localhost"]'

    • Windows： 

      c:\> kcadm create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keystore=[\"/opt/keycloak/keystore.jks\"]" -s "config.keystorePassword=[\"secret\"]" -s "config.keyPassword=[\"secret\"]" -s "config.keyAlias=[\"localhost\"]"
  2. 确保更改 keystore、storePassword、keyPassword 和 alias 的属性值，以匹配您的特定密钥存储。
  3. 将 parentId 属性设置为目标域 ID 的值。

使密钥被动或禁用密钥

  1. 识别您要进行被动的密钥。 

    $ kcadm.sh get keys -r demorealm
  2. 使用密钥的 providerId 属性来构造端点 URI，如 components/PROVIDER_ID。

  3. 执行 更新。

    例如：

    • linux: 

      $ kcadm.sh update components/PROVIDER_ID -r demorealm -s 'config.active=["false"]'

    • Windows： 

      c:\> kcadm update components/PROVIDER_ID -r demorealm -s "config.active=[\"false\"]"

      您可以更新其他关键属性：

    • 设置一个新的 enabled 值来禁用键，如 config.enabled=["false "]。
    • 设置一个新的 优先级值 以更改键的优先级，如 config.priority=["110 "]。

删除旧密钥

  1. 确保您要删除的密钥不活跃，并已禁用它。此操作是防止应用程序和用户持有的现有令牌失败。

  2. 识别要删除的密钥。 

    $ kcadm.sh get keys -r demorealm

  3. 使用密钥的 providerId 来执行删除。 

    $ kcadm.sh delete components/PROVIDER_ID -r demorealm

为域配置事件日志记录

对 events/config 端点使用 update 命令。

eventListener s 属性包含 EventListenerProviderFactory ID 列表，指定接收事件的所有事件监听程序。可以使用属性来控制内置事件存储，因此您可以使用 Admin REST API 查询过去的事件。红帽构建的 Keycloak 对服务调用(eventsEnabled)和 Admin REST API (adminEventsEnabled)触发的审计事件有单独的控制。您可以将 eventsExpiration 事件设置为过期，以防止数据库填满。Red Hat build of Keycloak 将 eventExpiration 设置为 time-to-live，以秒为单位。

您可以设置内置事件监听程序，通过 JBoss-logging 接收所有事件，并记录事件。通过使用 org.keycloak.events 日志记录器，红帽构建的 Keycloak 会记录错误事件，作为 WARN 和其他事件作为 DEBUG。

例如：

  • linux: 

    $ kcadm.sh update events/config -r demorealm -s 'eventsListeners=["jboss-logging"]'

  • Windows： 

    c:\> kcadm update events/config -r demorealm -s "eventsListeners=[\"jboss-logging\"]"

例如：

您可以为所有可用 ERROR 事件（不包括审计事件）打开存储，以便您可以通过 Admin REST 检索事件。

  • linux: 

    $ kcadm.sh update events/config -r demorealm -s eventsEnabled=true -s 'enabledEventTypes=["LOGIN_ERROR","REGISTER_ERROR","LOGOUT_ERROR","CODE_TO_TOKEN_ERROR","CLIENT_LOGIN_ERROR","FEDERATED_IDENTITY_LINK_ERROR","REMOVE_FEDERATED_IDENTITY_ERROR","UPDATE_EMAIL_ERROR","UPDATE_PROFILE_ERROR","UPDATE_PASSWORD_ERROR","UPDATE_TOTP_ERROR","VERIFY_EMAIL_ERROR","REMOVE_TOTP_ERROR","SEND_VERIFY_EMAIL_ERROR","SEND_RESET_PASSWORD_ERROR","SEND_IDENTITY_PROVIDER_LINK_ERROR","RESET_PASSWORD_ERROR","IDENTITY_PROVIDER_FIRST_LOGIN_ERROR","IDENTITY_PROVIDER_POST_LOGIN_ERROR","CUSTOM_REQUIRED_ACTION_ERROR","EXECUTE_ACTIONS_ERROR","CLIENT_REGISTER_ERROR","CLIENT_UPDATE_ERROR","CLIENT_DELETE_ERROR"]' -s eventsExpiration=172800

  • Windows： 

    c:\> kcadm update events/config -r demorealm -s eventsEnabled=true -s "enabledEventTypes=[\"LOGIN_ERROR\",\"REGISTER_ERROR\",\"LOGOUT_ERROR\",\"CODE_TO_TOKEN_ERROR\",\"CLIENT_LOGIN_ERROR\",\"FEDERATED_IDENTITY_LINK_ERROR\",\"REMOVE_FEDERATED_IDENTITY_ERROR\",\"UPDATE_EMAIL_ERROR\",\"UPDATE_PROFILE_ERROR\",\"UPDATE_PASSWORD_ERROR\",\"UPDATE_TOTP_ERROR\",\"VERIFY_EMAIL_ERROR\",\"REMOVE_TOTP_ERROR\",\"SEND_VERIFY_EMAIL_ERROR\",\"SEND_RESET_PASSWORD_ERROR\",\"SEND_IDENTITY_PROVIDER_LINK_ERROR\",\"RESET_PASSWORD_ERROR\",\"IDENTITY_PROVIDER_FIRST_LOGIN_ERROR\",\"IDENTITY_PROVIDER_POST_LOGIN_ERROR\",\"CUSTOM_REQUIRED_ACTION_ERROR\",\"EXECUTE_ACTIONS_ERROR\",\"CLIENT_REGISTER_ERROR\",\"CLIENT_UPDATE_ERROR\",\"CLIENT_DELETE_ERROR\"]" -s eventsExpiration=172800

您可以将存储的事件类型重置为 所有可用事件类型。将值设为空列表与枚举 all 相同。 

$ kcadm.sh update events/config -r demorealm -s enabledEventTypes=[]

您可以启用审计事件存储。 

$ kcadm.sh update events/config -r demorealm -s adminEventsEnabled=true -s adminEventsDetailsEnabled=true

您可以获取最后 100 个事件。事件从最新到最旧的排序。 

$ kcadm.sh get events --offset 0 --limit 100

您可以删除所有保存的事件。 

$ kcadm delete events

刷新缓存

  1. 使用带有其中一个端点的 create 命令清除缓存：

    • clear-realm-cache
    • clear-user-cache
    • clear-keys-cache

  2. 将 realm 设置为与目标域相同的值。

    例如： 

    $ kcadm.sh create clear-realm-cache -r demorealm -s realm=demorealm
$ kcadm.sh create clear-user-cache -r demorealm -s realm=demorealm
$ kcadm.sh create clear-keys-cache -r demorealm -s realm=demorealm

从导出的 .json 文件导入域

  1. 在 partialImport 端点上使用 create 命令。
  2. 将 ifResourceExists 设置为 FAIL、SKIP 或 OVERWRITE。

  3. 使用 -f 提交导出的域 .json 文件。

    例如： 

    $ kcadm.sh create partialImport -r demorealm2 -s ifResourceExists=FAIL -o -f demorealm.json

    如果域尚不存在，请首先创建它。

    例如： 

    $ kcadm.sh create realms -s realm=demorealm2 -s enabled=true
Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

© 2024 Red Hat, Inc.