如何为Quarkus GraphQL UI添加OAuth 2.0认证支持？

1. 添加必要依赖 #

在pom.xml（Maven）或build.gradle（Gradle）中引入以下依赖：

• quarkus-oidc：处理Keycloak的OIDC认证流程
• quarkus-smallrye-graphql-ui：提供GraphQL可视化调试UI
• quarkus-smallrye-graphql：核心GraphQL API支持

Maven示例：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-graphql-ui</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-graphql</artifactId>
</dependency>

2. 配置OIDC与GraphQL UI #

在application.properties中配置Keycloak参数及GraphQL UI的自动认证支持：

# Keycloak OIDC核心配置
quarkus.oidc.auth-server-url=http://localhost:8080/realms/你的领域名
quarkus.oidc.client-id=你的GraphQL客户端ID
quarkus.oidc.credentials.secret=你的客户端密钥（仅客户端为confidential类型时需要）
quarkus.oidc.application-type=web-app

# 启用GraphQL UI的OIDC自动认证
quarkus.smallrye-graphql-ui.oidc.enabled=true
quarkus.smallrye-graphql-ui.oidc.client-id=${quarkus.oidc.client-id}
quarkus.smallrye-graphql-ui.oidc.realm=${quarkus.oidc.auth-server-url}/../你的领域名
quarkus.smallrye-graphql-ui.oidc.url=${quarkus.oidc.auth-server-url}

3. 保护GraphQL API端点 #

可通过两种方式保护API：

• 注解方式：在GraphQL Resolver类或方法上添加安全注解：

  import javax.annotation.security.RolesAllowed;
  import org.eclipse.microprofile.graphql.Query;
  
  @RolesAllowed("user")
  public class BookResolver {
      @Query
      public List<Book> getAllBooks() {
          // 业务逻辑实现
      }
  }
  

• 全局路径配置：在application.properties中设置路径级安全规则：

  quarkus.http.auth.permission.graphql.path=/graphql
  quarkus.http.auth.permission.graphql.policy=authenticated
  

4. Keycloak客户端配置 #

在Keycloak后台完成以下设置：

• 创建新客户端，类型选择public或confidential（按需选择）
• 设置有效重定向URI为http://localhost:8081/graphql-ui/*（替换为你的应用实际端口）
• 确保客户端启用Authorization Code Flow（默认已开启）

5. 测试流程 #

1. 启动Quarkus应用
2. 访问http://localhost:8081/graphql-ui（替换为你的应用端口）
3. 页面自动跳转到Keycloak登录界面，输入合法账号密码登录
4. 登录成功后返回GraphQL UI，所有发送的GraphQL请求会自动携带Authorization请求头，无需手动添加

注意事项 #

• 确保Quarkus版本在2.15及以上，该版本开始smallrye-graphql-ui内置OIDC集成支持
• 若遇跨域问题，添加CORS配置：

  quarkus.http.cors.enabled=true
  quarkus.http.cors.origins=http://localhost:8081
  quarkus.http.cors.methods=GET,POST,OPTIONS
  

• 需自动刷新令牌可开启：quarkus.oidc.token.refresh.enabled=true

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