Dev Services and Dev UI for OpenID Connect (OIDC)
您可以为 Keycloak 使用 Dev Services，为 OpenID Connect (OIDC) Keycloak 提供程序使用 Dev UI，并将这些服务调整为其他 OpenID Connect 提供程序。您还可以在运行 Quarkus 之前已启动的 OpenID Connect 提供程序中使用 Dev UI。
You can use Dev Services for Keycloak and the Dev UI for the OpenID Connect (OIDC) Keycloak provider and adapt these services for other OpenID Connect providers. You can also use the Dev UI with OpenID Connect providers that have already been started before you run Quarkus in development mode.
Introduction
Quarkus 提供 Keycloak 的 Dev Services 功能，该功能在 quarkus-oidc 扩展程序在开发模式下启动时默认启用，集成测试在测试模式下运行，并且没有配置 quarkus.oidc.auth-server-url 属性时。Keycloak 的 Dev Services 功能为开发和测试模式启动一个 Keycloak 容器。它通过注册现有的 Keycloak 领域或创建新的领域来初始化它们，并为您提供您立即开始开发由 Keycloak 保护的 Quarkus 应用程序所需的客户端和用户。检测到 application.properties 或领域文件发生更改时，该容器将重新启动。
Quarkus provides the Dev Services for Keycloak feature, which is enabled by default when the quarkus-oidc extension is started in dev mode, the integration tests are running in test mode, and when no quarkus.oidc.auth-server-url property is configured.
The Dev Services for Keycloak feature starts a Keycloak container for both the dev and test modes.
It initializes them by registering the existing Keycloak realm or creating a new realm with the client and users required for you to start developing your Quarkus application secured by Keycloak immediately.
The container restarts when the application.properties or the realm file changes have been detected.
Additionally, Dev UI available at /q/dev complements this feature with a Dev UI page, which helps to acquire the tokens from Keycloak and test your Quarkus application.
如果已设置 quarkus.oidc.auth-server-url，则会激活通用 OpenID Connect Dev 控制台（所有 OpenID Connect 提供程序均可使用）。有关更多信息，请参阅 Dev UI for all OpenID Connect providers。
If quarkus.oidc.auth-server-url is already set, then a generic OpenID Connect Dev Console, which can be used with all OpenID Connect providers, is activated.
For more information, see dev-ui-all-oidc-providers.
Dev Services for Keycloak
在 application.properties 文件中不配置 quarkus.oidc 属性的情况下启动应用程序：
Start your application without configuring quarkus.oidc properties in the application.properties file:
Unresolved directive in security-openid-connect-dev-services.adoc - include::{includes}/devtools/dev.adoc[]
控制台将显示类似于此的输出：
The console displays output similar to this:
KeyCloak Dev Services Starting:
2021-11-02 17:14:24,864 INFO [org.tes.con.wai.str.HttpWaitStrategy] (build-10) /unruffled_agnesi: Waiting for 60 seconds for URL: http://localhost:32781 (where port 32781 maps to container port 8080)
2021-11-02 17:14:44,170 INFO [io.qua.oid.dep.dev.key.KeycloakDevServicesProcessor] (build-10) Dev Services for Keycloak started.在登录到 Keycloak 管理控制台时，用户名为 admin，密码为 admin。
When logging in to the Keycloak admin console, the username is admin, and the password is admin.
请注意，如果 Dev Services for Keycloak 检测到标记为 quarkus-dev-service-keycloak 的现有容器，则其默认为不启动新的容器。它会连接到此容器，前提是 quarkus.keycloak.devservices.service-name 属性的值与标签的值匹配（默认为 quarkus）。在这种情况下，在运行以下命令时，预期输出会有轻微更改：
Be aware that Dev Services for Keycloak defaults to not initiating a new container if it detects an existing container labeled quarkus-dev-service-keycloak.
It connects to this container provided the value of the quarkus.keycloak.devservices.service-name property matches the label’s value (default quarkus).
In such cases, expect a slightly altered output when you run the following:
Unresolved directive in security-openid-connect-dev-services.adoc - include::{includes}/devtools/dev.adoc[]
2021-08-27 18:42:43,530 INFO [io.qua.dev.com.ContainerLocator] (build-15) Dev Services container found: 48fee151a31ddfe32c39965be8f61108587b25ed2f66cdc18bb926d9e2e570c5 (quay.io/keycloak/keycloak:21.0.2). Connecting to: 0.0.0.0:32797.
2021-08-27 18:42:43,600 INFO [io.qua.oid.dep.dev.key.KeycloakDevServicesProcessor] (build-15) Dev Services for Keycloak started.
...|
如果 Keycloak 容器在默认的 60 秒超时时间内没有准备就绪，则可以通过延长超时时间来解决此问题。例如，使用 If the Keycloak container is not ready within the default 60-second timeout, you can resolve this by extending the timeout period.
For instance, set it to 2 minutes with |
您可以通过指定 quarkus.keycloak.devservices.shared=false 来关闭容器的共享。
You can turn off sharing of the containers by specifying quarkus.keycloak.devservices.shared=false.
现在，打开主 Dev UI page 并观察链接到 Keycloak 页面的 OpenID Connect 卡片。例如：
Now, open the main Dev UI page and observe the OpenID Connect card linking to a Keycloak page. For example:
单击 Keycloak provider 链接。此操作将打开一个 Keycloak 页面，其外观会根据 Dev Services for Keycloak 功能的配置方式而有所不同。
Click the Keycloak provider link. This action opens a Keycloak page whose appearance varies depending on how the Dev Services for Keycloak feature is configured.
Developing service applications
默认情况下，Keycloak 页面可用于支持 Quarkus OIDC service application 的开发。
By default, the Keycloak page can be used to support the development of a Quarkus OIDC service application.
Authorization code grant
如果你在 application.properties 文件中设置 quarkus.oidc.devui.grant.type=code （这是一个默认值），则使用 authorization_code 授权来获取访问令牌和 ID 令牌。建议使用此授权来模拟典型的流程，其中单页应用程序 (SPA) 获取令牌并使用它们来访问 Quarkus 服务。
If you set quarkus.oidc.devui.grant.type=code in the application.properties file (this is a default value), then an authorization_code grant is used to acquire both access and ID tokens.
Using this grant is recommended to emulate a typical flow where a single page application (SPA) acquires the tokens and uses them to access Quarkus services.
首先，你会看到 Log into Single Page Application 的选项。例如：
First, you see an option to Log into Single Page Application. For example:
在身份验证过程中选择 Keycloak 领域和要使用的客户端 ID。
Choose the Keycloak realm and client ID to use during the authentication process.
|
此 SPA 表示一个公共 OpenID Connect 客户端；因此，你输入的客户端 ID 必须标识没有密钥的公共 Keycloak 客户端。这是因为 SPA 不是 Web 应用程序，并且如果期望客户端密钥也完成授权代码流程，则无法安全处理完成授权代码流程所需的密钥。 This SPA represents a public OpenID Connect client; therefore, the client IDs you enter must identify public Keycloak clients that have no secrets. This is because SPA is not a web application and cannot securely handle the secrets it needs to complete the authorization code flow if the client secret is also expected to complete the authorization code flow. 如果已创建默认领域，或者配置了 The clients requiring secrets can only be supported with this SPA if a default realm has been created or if |
然后，在选择*Log into Single Page Application*，您将被重定向到 Keycloak 进行身份验证，例如，作为`alice:alice`然后，您将返回表示 SPA 的页面：
Next, after selecting Log into Single Page Application, you are redirected to Keycloak to authenticate, for example, as alice:alice.
Then, you are returned to the page representing the SPA:
您可以查看获得的访问和 ID 令牌，例如：
You can view the acquired access and ID tokens, for example:
此视图显示左侧的编码 JSON Web 令牌 (JWT) 令牌，并使用红色突出显示标头、绿色突出显示有效负载或声明，并使用蓝色突出显示签名。它还显示右侧的解码 JWT 令牌，您可以在其中看到标头、声明名称及其值。
This view shows the encoded JSON Web Token (JWT) token on the left side and highlights the headers in red, payload or claims in green, and signature in blue. It also shows the decoded JWT token on the right side, where you can see the header, claim names, and their values.
然后，通过输入相对服务路径并发送令牌来测试服务。SPA 通常将访问令牌发送到应用程序端点，因此请选择*With Access Token*选项，例如：
Next, test the service by entering a relative service path and sending a token. SPA usually sends access tokens to the application endpoint, so choose the With Access Token option, for example:
要清除测试结果区，请使用右下角的橡皮擦图标。
To clear the test results area, use the eraser icon in the lower right corner.
有时，ID 令牌作为持有者令牌转发到应用程序前端。这有助于端点识别登录到 SPA 的用户或执行带外令牌验证。在这种情况下，选择*With ID Token*选项。
Sometimes, ID tokens are forwarded to application frontends as bearer tokens. This helps endpoints identify the user logged into SPA or perform out-of-band token verification. Choose the With ID Token option in such cases.
手动输入服务路径并不理想。有关启用 Swagger 或 GraphQL UI 以使用 OIDC Dev UI 已经获取的访问令牌测试服务的信息，请参阅Test with Swagger UI or GraphQL UI部分。
Manually entering the service paths is not ideal. For information about enabling Swagger or GraphQL UI for testing the service with the access token already acquired by the OIDC Dev UI, see the test-with-swagger-graphql section.
最后，您可以单击*Log Out*image::dev-ui-keycloak-logout.png[alt=Dev UI Keycloak - Log Out,role="center"]，以便您可以身份验证到 Keycloak 作为不同的用户。
Finally, you can click Log Out image::dev-ui-keycloak-logout.png[alt=Dev UI Keycloak - Log Out,role="center"] so you can authenticate to Keycloak as a different user.
当您尝试*Log into Single Page Application*时，Keycloak 可能会返回错误。例如，`quarkus.oidc.client-id`可能与导入到 Keycloak 中的领域中的客户端 ID 不匹配，或者此领域中的客户端可能未正确配置以支持授权代码流。在这种情况下，Keycloak 会返回一个`error_description`查询参数，并且 Dev UI 也会显示此错误描述。例如：
Keycloak might return an error when you try to Log into Single Page Application.
For example, quarkus.oidc.client-id might not match the client ID in the realm imported to Keycloak, or the client in this realm might not be configured correctly to support the authorization code flow.
In such cases, Keycloak returns an error_description query parameter, and the Dev UI also shows this error description.
For example:
如果出现错误，请使用*Keycloak Admin*选项登录到 Keycloak，根据需要更新领域配置，并检查`application.properties`。
If the error occurs, log in to Keycloak by using the Keycloak Admin option, update the realm configuration as necessary, and check the application.properties.
Test with Swagger UI or GraphQL UI
如果您项目中使用了`quarkus-smallrye-openapi`或`quarkus-smallrye-graphql`，则您可以避免手动输入服务路径并使用 Swagger UI 或 GraphQL UI 测试您的服务。例如，在开发模式下使用`quarkus-smallrye-openapi`和`quarkus-smallrye-graphql`依赖项启动 Quarkus。登录到 Keycloak 后，您会看到以下选项：
You can avoid manually entering the service paths and test your service with Swagger UI or GraphQL UI if quarkus-smallrye-openapi or quarkus-smallrye-graphql are used in your project.
For example, start Quarkus in dev mode with both quarkus-smallrye-openapi and quarkus-smallrye-graphql dependencies.
You can see the following options after logging in to Keycloak:
例如，单击*Swagger UI*将在新浏览器选项卡中打开 Swagger UI，您可以在其中使用 Dev UI 为 Keycloak 获取的令牌来测试服务。Swagger UI 不会尝试再次重新身份验证。在 Swagger UI 中，不要选择 Swagger UI `Authorize`选项；OIDC Dev UI 已为 Swagger UI 授权并提供访问令牌以供其用于测试。
For example, clicking Swagger UI opens the Swagger UI in a new browser tab where you can test the service by using the token acquired by Dev UI for Keycloak.
The Swagger UI does not try to re-authenticate again.
In the Swagger UI, do not choose a Swagger UI Authorize option; the OIDC Dev UI has authorized and provided the access token for Swagger UI to use for testing.
与 GraphQL UI 的集成工作方式类似；使用 Dev UI 为 Keycloak 获取的访问令牌。
Integration with GraphQL UI works similarly; the access token acquired by Dev UI for Keycloak is used.
|
您可能需要为 Dev UI 为 Keycloak 发起的授权代码流注册重定向 URI。这是因为 Keycloak 可能会强制要求已验证的用户仅重定向到已配置的重定向 URI。建议在生成环境中执行此操作，以避免用户被重定向到错误的端点，如果身份验证请求 URI 中正确的`redirect_uri`参数已被操纵，则可能会发生这种情况。 You might need to register a redirect URI for the authorization code flow initiated by Dev UI for Keycloak to work.
This is because Keycloak might enforce that the authenticated users are redirected only to the configured redirect URI.
It is recommended to do this in production to avoid the users being redirected to the wrong endpoints, which might happen if the correct 如果 Keycloak 强制执行它，您会看到一个身份验证错误，告知您`redirect_uri`值错误。 If Keycloak enforces it, you see an authentication error informing you that the 在这种情况下，选择右上角的*Keycloak Admin*选项，登录为`admin:admin`，选择测试领域和 Dev UI 为 Keycloak 配置的客户端，并将`http://localhost:8080/q/dev-ui/io.quarkus.quarkus-oidc/keycloak-provider`添加到`Valid Redirect URIs`。如果您在启动 Quarkus 时使用了`-Dquarkus.http.port`，则将`8080`更改为`quarkus.http.port`的值 In this case, select the Keycloak Admin option in the top right corner, login as 如果容器在运行在不同端口上的多个应用程序之间共享，则必须为每个应用程序注册`redirect_uri`值。 If the container is shared between multiple applications running on different ports, you must register 您可以将`redirect_uri`值设置为`*`，仅用于测试目的，尤其是在容器在多个应用程序之间共享时。 You can set the 如果没有导入自定义领域，当 Dev Services 为 Keycloak 创建默认领域时，将`redirect_uri`值设置为`*`。 If no custom realm is imported, Dev Services for Keycloak sets the |
Implicit grant
如果您在 application.properties 文件中设置了 quarkus.oidc.devui.grant.type=implicit，则使用 implicit 授权来获取访问令牌和 ID 令牌。仅当授权代码授权无法运行时，才使用此授权模拟单页应用程序；例如，当客户端已在 Keycloak 中配置为支持隐式授权时。
If you set quarkus.oidc.devui.grant.type=implicit in the application.properties file, then an implicit grant is used to acquire both access and ID tokens.
Use this grant to emulate a single page application only if the authorization code grant does not work; for example, when a client is configured in Keycloak to support an implicit grant.
Password grant
如果您在 application.properties 文件中设置了 quarkus.oidc.devui.grant.type=password，则会看到类似于以下内容的屏幕：
If you set quarkus.oidc.devui.grant.type=password in the application.properties file, then you see a screen similar to this one:
选择领域，输入客户端 ID 和机密、用户名和密码、相对服务端点路径，然后单击 Test service。它会返回一个状态代码，如 200、403、401 或 404。如果用户名也已在包含用户名和密码的 quarkus.keycloak.devservices.users 映射属性中设置，则在测试服务时不必设置密码。请注意，您不必初始化 quarkus.keycloak.devservices.users 来使用 password 授权测试服务。
Select a realm, enter a client ID and secret, user name and password, a relative service endpoint path, and click Test service.
It returns a status code, such as 200, 403, 401, or 404.
If the username is also set in the quarkus.keycloak.devservices.users map property containing usernames and passwords, then you do not have to set a password when testing the service.
Be aware that you do not have to initialize quarkus.keycloak.devservices.users to test the service by using the password grant.
在 Dev UI 控制台中，您还可以看到类似于以下内容的输出：
In the Dev UI console, you can also see output similar to the following:
2021-07-19 17:58:11,407 INFO [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Using password grant to get a token from 'http://localhost:32818/realms/quarkus/protocol/openid-connect/token' for user 'alice' in realm 'quarkus' with client id 'quarkus-app'
2021-07-19 17:58:11,533 INFO [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Test token: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6Z2tDazJQZ1JaYnVlVG5kcTFKSW1sVnNoZ2hhbWhtbnBNcXU0QUt5MnJBIn0.ey...
2021-07-19 17:58:11,536 INFO [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Sending token to 'http://localhost:8080/api/admin'
2021-07-19 17:58:11,674 INFO [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Result: 200通过使用 password 授权从 Keycloak 获取令牌，并将其发送到服务端点。
A token is acquired from Keycloak by using a password grant and is sent to the service endpoint.
Client credentials grant
如果您设置了 quarkus.oidc.devui.grant.type=client，则会使用 client_credentials 授权获取令牌，在此情况下，页面中不会显示 User 字段：
If you set quarkus.oidc.devui.grant.type=client, then a client_credentials grant is used to acquire a token, with the page showing no User field in this case:
选择领域，输入客户端 ID 和机密、相对服务端点路径，然后单击 Test service。它会返回一个状态代码，如 200、403、401 或 404。
Select a realm, enter the client ID and secret, a relative service endpoint path, and click Test service.
It returns a status code, such as 200, 403, 401, or 404.
Developing OpenID Connect web-app applications
要开发 Quarkus OIDC web application，请在启动应用程序之前，在 application.properties 文件中设置 quarkus.oidc.application-type=web-app。
To develop a Quarkus OIDC web application, set quarkus.oidc.application-type=web-app in the application.properties file before starting the application.
启动应用程序会显示一个类似于以下内容的屏幕：
Starting the application displays a screen similar to this one:
设置一个相对服务端点路径并单击 Log in to your web application。您会在新的浏览器标签中重定向到 Keycloak，以输入用户名和密码，然后才能从 Quarkus 应用程序获取响应。
Set a relative service endpoint path and click Log in to your web application. You are redirected to Keycloak to enter a username and password in a new browser tab before you get a response from the Quarkus application.
在此情况下，Dev UI 并不是非常有用，因为 Quarkus OIDC web-app 应用程序控制授权代码流并获取令牌。
In this case, the Dev UI is not very helpful because the Quarkus OIDC web-app application controls the authorization code flow and acquires the tokens.
为了让 Dev UI 更有助于支持 OIDC web-app 应用程序的开发，请考虑为 quarkus.oidc.application-type 设置特定于配置文件的值：
To make Dev UI more helpful in supporting the development of OIDC web-app applications, consider setting profile-specific values for quarkus.oidc.application-type:
%prod.quarkus.oidc.application-type=web-app
%test.quarkus.oidc.application-type=web-app
%dev.quarkus.oidc.application-type=service此配置文件可确保在您的 web-app 应用程序在开发模式下运行时，所有在 Developing service applications 中描述的 Dev UI 选项都可用。此方法的局限性在于，使用代码流返回并通过 Dev UI 获取的访问令牌和 ID 令牌作为 HTTP Bearer 令牌发送到端点，如果您的端点需要注入 IdToken，则不起作用。但是，如果您的 web-app 应用程序仅使用访问令牌（例如，作为角色的来源或获取 UserInfo），则它会按预期工作，即使它在开发模式下被视为 service 应用程序也是如此。
This profile ensures that all Dev UI options described in develop-service-applications are available when your web-app application is run in dev mode.
The limitation of this approach is that both access and ID tokens returned with the code flow and acquired with Dev UI are sent to the endpoint as HTTP Bearer tokens - which does not work well if your endpoint requires the injection of IdToken.
However, it works as expected if your web-app application only uses the access token, for example, as a source of roles or to get UserInfo, even if it is assumed to be a service application in dev mode.
对于开发模式，一个更好的选择是将 application-type 属性设为 hybrid：
For dev mode, an even better option is to set the application-type property to hybrid:
%prod.quarkus.oidc.application-type=web-app
%test.quarkus.oidc.application-type=web-app
%dev.quarkus.oidc.application-type=hybrid此类型可确保如果在没有 OIDC Dev UI 的情况下从浏览器访问应用程序（在开发模式下），则 Quarkus OIDC 也会执行授权代码流，就像在生产模式下一样。OIDC Dev UI 也会更有益，因为混合应用程序也可以接受出示者访问令牌。
This type ensures that if you access the application from the browser in dev mode without the OIDC Dev UI, Quarkus OIDC also performs the authorization code flow as in the production mode. The OIDC Dev UI is also more beneficial because hybrid applications can also accept the bearer access tokens.
Running the tests
可以在 Continuous Testing 模式中针对在测试模式下启动的 Keycloak 容器运行测试。
You can run the tests against a Keycloak container started in a test mode in a Continuous Testing mode.
还建议使用 Dev Services for Keycloak 来针对 Keycloak 运行集成测试。有关更多信息，请参阅 Testing OpenID Connect Service Applications with Dev Services 和 Testing OpenID Connect WebApp Applications with Dev Services。
It is also recommended to run the integration tests against Keycloak by using Dev Services for Keycloak. For more information, see Testing OpenID Connect Service Applications with Dev Services and Testing OpenID Connect WebApp Applications with Dev Services.
Keycloak initialization
包含由 Quarkus 提供支持的 Keycloak 分发的 quay.io/keycloak/keycloak:25.0.2 映像用于默认启动容器。quarkus.keycloak.devservices.image-name 可用于更改 Keycloak 映像名称。例如，将其设为 quay.io/keycloak/keycloak:19.0.3-legacy，以使用由 WildFly 提供支持的 Keycloak 分发。请注意，基于 Quarkus 的 Keycloak 分发仅在 Keycloak 20.0.0 中才可用。
The quay.io/keycloak/keycloak:25.0.2 image which contains a Keycloak distribution powered by Quarkus is used to start a container by default.
quarkus.keycloak.devservices.image-name can be used to change the Keycloak image name.
For example, set it to quay.io/keycloak/keycloak:19.0.3-legacy to use a Keycloak distribution powered by WildFly.
Be aware that a Quarkus-based Keycloak distribution is only available starting from Keycloak 20.0.0.
Keycloak 的开发服务接下来会初始化一个已启动的 Keycloak 服务器。
Dev Services for Keycloak initializes a launched Keycloak server next.
默认情况下，会创建配有 quarkus 和 quarkus-app 客户端、secret 密码、alice 和 bob 用户（密码与名称匹配）以及 user 和 admin 角色，其中 alice 获赋予 admin 和 user 角色，而 bob 获赋予 user 角色。
By default, the quarkus and quarkus-app client with a secret password, alice and bob users (with the passwords matching the names), and user and admin roles are created, with alice given both admin and user roles and bob - the user role.
用户名、密码和角色可以通过 quarkus.keycloak.devservices.users （包含用户名和密码的映射）和 quarkus.keycloak.devservices.roles （包含用户名和逗号分隔的角色值）进行自定义。
Usernames, secrets, and their roles can be customized with quarkus.keycloak.devservices.users (the map which contains usernames and secrets) and quarkus.keycloak.devservices.roles (the map which contains usernames and comma-separated role values).
例如：
For example:
%dev.quarkus.keycloak.devservices.users.duke=dukePassword
%dev.quarkus.keycloak.devservices.roles.duke=reader
%dev.quarkus.keycloak.devservices.users.john=johnPassword
%dev.quarkus.keycloak.devservices.roles.john=reader,writer此配置会创建两个用户：* duke 配有 dukePassword 密码和 reader 角色* john 配有 johnPassword 密码和 reader 和 writer 角色
This configuration creates two users:
* duke with a dukePassword password and a reader role
* john with a johnPassword password and reader and writer roles
若要自定义客户端 ID 和密码，可以使用 quarkus.oidc.client-id 和 quarkus.oidc.credentials.secret 属性。
To customize the client ID and secret, you can use the quarkus.oidc.client-id and quarkus.oidc.credentials.secret properties.
但您的 Keycloak 配置可能比较复杂，需要设置更多属性。
However, it is likely that your Keycloak configuration is more complex and requires setting more properties.
这就是为什么在使用默认或已配置的领域、客户端、用户和角色属性初始化 Keycloak 之前始终会检查 quarkus.keycloak.devservices.realm-path。如果领域文件存在于文件系统或类路径，则仅使用此领域初始化 Keycloak，例如：
This is why quarkus.keycloak.devservices.realm-path is always checked before initializing Keycloak with the default or configured realm, client, user, and roles properties.
If the realm file exists on the file system or classpath, then only this realm is used to initialize Keycloak, for example:
quarkus.keycloak.devservices.realm-path=quarkus-realm.json您可以使用 quarkus.keycloak.devservices.realm-path 通过提供逗号分隔的文件列表来使用多个领域文件初始化 Keycloak：
You can use quarkus.keycloak.devservices.realm-path to initialize Keycloak with multiple realm files by providing a comma-separated list of files:
quarkus.keycloak.devservices.realm-path=quarkus-realm1.json,quarkus-realm2.json
此外，Keycloak 页面提供了一个使用右上角的 Keycloak Admin 选项进行 Sign In To Keycloak To Configure Realms 的选项：
Also, the Keycloak page offers an option to Sign In To Keycloak To Configure Realms by using a Keycloak Admin option in the right top corner:
以 admin:admin 登录 Keycloak 以进一步自定义领域属性，创建或导入新的领域，或导出领域。
Sign in to Keycloak as admin:admin to further customize the realm properties, create or import a new realm, or export the realm.
您还可以将类路径和文件系统资源复制到容器中。例如，如果您的应用程序使用已部署到 Keycloak 的 jar 文件中配置 Keycloak 授权，那么您可以配置 Dev Services for Keycloak 来将此 jar 复制到 Keycloak 容器，如下所示：
You can also copy classpath and file system resources to the container.
For example, if your application configures Keycloak authorization with JavaScript policies that are deployed to Keycloak in a jar file, then you can configure Dev Services for Keycloak to copy this jar to the Keycloak container as follows:
quarkus.keycloak.devservices.resource-aliases.policies=/policies.jar 1
quarkus.keycloak.devservices.resource-mappings.policies=/opt/keycloak/providers/policies.jar 2| 1 | policies alias is created for the classpath /policies.jar resource. |
策略 jar 也可位于文件系统中。<2> 策略 jar 被映射到 /opt/keycloak/providers/policies.jar 容器位置。
Policy jars can also be located in the file system.
<2> The policies jar is mapped to the /opt/keycloak/providers/policies.jar container location.
Disable Dev Services for Keycloak
以下情况均为不激活 Keycloak 开发服务： 如果 quarkus.oidc.auth-server-url 已初始化，或无论是否使用 Keycloak，已使用 quarkus.oidc.tenant.enabled=false 禁用了默认 OIDC 租户。
Dev Services for Keycloak is not activated if either quarkus.oidc.auth-server-url is already initialized or the default OIDC tenant is disabled with quarkus.oidc.tenant.enabled=false, regardless of whether you work with Keycloak or not.
如果您不想启动 Keycloak 开发服务容器或不使用 Keycloak，也可以使用 quarkus.keycloak.devservices.enabled=false 禁用此功能——只有在您期望在没有 quarkus.oidc.auth-server-url 的情况下启动 quarkus:dev 时才需要执行此操作。
If you prefer not to have a Dev Services for Keycloak container started or do not work with Keycloak, then you can also disable this feature with quarkus.keycloak.devservices.enabled=false - it is only necessary if you expect to start quarkus:dev without quarkus.oidc.auth-server-url.
当 Keycloak 开发服务被禁用且 quarkus.oidc.auth-server-url 属性尚未初始化时，主开发 UI 页面会包含一个空的 OpenID Connect 卡牌：
The main Dev UI page includes an empty OpenID Connect card when Dev Services for Keycloak is disabled and the quarkus.oidc.auth-server-url property has not been initialized:
如果已设置 quarkus.oidc.auth-server-url，则能够激活通用 OpenID Connect 开发控制台，可与所有 OpenID Connect 提供程序一同使用。有关更多信息，请参阅 Dev UI for all OpenID Connect providers 部分。
If quarkus.oidc.auth-server-url is already set, then a generic OpenID Connect Dev Console, which can be used with all OpenID Connect providers, can be activated.
For more information, see the dev-ui-all-oidc-providers section.
Dev UI for all OpenID Connect providers
在满足以下条件的情况下，将激活所有 OpenID Connect 提供程序的开发 UI：
The Dev UI for all OpenID Connect providers is activated if the following conditions are met:
-
The
quarkus.oidc.auth-server-urlpoints to an already started OpenID Connect provider, which can be Keycloak or other provider. -
The
quarkus.oidc.application-typeis set toservice, the default value, orhybrid. -
The
quarkus.oidc.client-idis set.
设置 quarkus.oidc.credentials.secret，很可能 Keycloak 和其他提供者需要授权代码流，这是从 Dev UI 初始化的，以便完成，除非使用 quarkus.oidc.client-id 标识的客户端在 OpenID Connect 提供者的管理台中配置为公共客户端。
Setting quarkus.oidc.credentials.secret is most likely required for Keycloak and other providers for the authorization code flow initiated from Dev UI to complete unless the client identified with quarkus.oidc.client-id is configured as a public client in your OpenID Connect provider’s administration console.
例如，你可以使用 Dev UI 测试带有此配置的 Google 认证：
For example, you can use Dev UI to test Google authentication with this configuration:
quarkus.oidc.provider=google
quarkus.oidc.application-type=hybrid
quarkus.oidc.client-id=${google-client-id}
quarkus.oidc.credentials.secret=${google-client-secret}运行：
Run:
Unresolved directive in security-openid-connect-dev-services.adoc - include::{includes}/devtools/dev.adoc[]
此命令输出一条消息，与以下示例类似：
This command outputs a message similar to the following example:
...
2021-09-07 15:53:42,697 INFO [io.qua.oid.dep.dev.OidcDevConsoleProcessor] (build-41) OIDC Dev Console: discovering the provider metadata at https://accounts.google.com/.well-known/openid-configuration
...如果提供者的元数据发现已成功，那么在你打开 Dev UI page 主页后，你可以看到以下 OpenID Connect 卡片，引用 Google 提供者：
If the provider metadata discovery has been successful, then after you open the main Dev UI page, you can see the following OpenID Connect card referencing a Google provider:
遵循链接登录到你的提供者，获取令牌并测试应用程序。体验与 Authorization code grant for Keycloak 部分中描述的相同，其中 Keycloak 容器的 Dev 服务已经启动，特别是如果你使用 Keycloak。
Follow the link to log in to your provider, get the tokens, and test the application. The experience is the same as described in the keycloak-authorization-code-grant section, where the Dev Services for Keycloak container has been started, especially if you work with Keycloak.
你可能需要配置你的 OpenID Connect 提供者，以支持重定向回 Dev Console。你添加 http://localhost:8080/q/dev-ui/io.quarkus.quarkus-oidc/<providerName>-provider 作为受支持的重定向和注销 URL 之一，其中 <providerName> 必须替换为 Dev UI 中显示的提供者名称，例如，<providerName>。
You likely need to configure your OpenID Connect provider to support redirecting back to the Dev Console.
You add http://localhost:8080/q/dev-ui/io.quarkus.quarkus-oidc/<providerName>-provider as one of the supported redirect and logout URLs, where <providerName> must be replaced by the name of the provider shown in the Dev UI, for example, auth0.
如果你使用其他提供者，那么 Authorization code grant for Keycloak 部分中描述的 Dev UI 体验可能略有不同。例如，访问令牌可能不是 JWT 格式，因此无法显示其内部内容。但是，所有提供者都应该以 JWT 格式返回 ID 令牌。
The Dev UI experience described in the keycloak-authorization-code-grant section might differ slightly if you work with other providers. For example, an access token might not be in JWT format, so it would not be possible to show its internal content. However, all providers should return ID tokens in the JWT format.
|
当前访问令牌默认用于通过 Swagger UI 或 GrapghQL UI 测试服务。如果提供者（除了 Keycloak）返回二进制访问令牌，那么它仅在该提供者具有令牌内省端点时才与 Swagger UI 或 GrapghQL UI 一起使用；否则，始终采用 JWT 格式的 The current access token is used by default to test the service with Swagger UI or GrapghQL UI.
If the provider (other than Keycloak) returns a binary access token, then it is used with Swagger UI or GrapghQL UI only if this provider has a token introspection endpoint; otherwise, an |
一些提供者，例如 Auth0，不支持标准 RP 初始化注销，因此必须配置特定提供者的注销属性，以便注销选项可见。有关更多信息，请参阅《OpenID Connect 授权代码流机制以保护 Web 应用程序》指南中的 User-initiated logout 部分。
Some providers, such as Auth0 do not support a standard RP-initiated logout, so the provider-specific logout properties must be configured for a logout option to be visible.
For more information, see User-initiated logout section in the "OpenID Connect authorization code flow mechanism for protecting web applications" guide.
类似地，如果你希望使用 password 或 client_credentials 授权 Dev UI 获取令牌，那么你可能需要配置一些额外的特定提供者属性，例如：
Similarly, if you want to use a password or client_credentials grant for Dev UI to acquire the tokens, then you might need to configure some extra provider-specific properties, for example:
quarkus.oidc.devui.grant.type=password
quarkus.oidc.devui.grant-options.password.audience=http://localhost:8080Non-application root path considerations
本文档在多个位置引用 http://localhost:8080/q/dev-ui Dev UI URL，其中 q 是一个默认的非应用程序根路径。如果你自定义 quarkus.http.root-path 或 quarkus.http.non-application-root-path 属性，那么请相应地替换 q。有关更多信息，请参阅 Path resolution in Quarkus 博文。
This document refers to the http://localhost:8080/q/dev-ui Dev UI URL in several places where q is a default non-application root path.
If you customize quarkus.http.root-path or quarkus.http.non-application-root-path properties, then replace q accordingly.
For more information, see the Path resolution in Quarkus blog post.