GraphQL API 보호

Keycloak을 활용해 GraphQL API를 보호하는 방식은 전통적인 REST API 보호와 유사하지만, GraphQL의 특성상 스키마 기반 호출, 한 번의 요청에 대한 다양한 리졸버 처리, introspection 쿼리 등의 이슈를 명확하게 고려해야 한다. 따라서 정확한 Access Token 검증, API 게이트웨이 활용, Role 기반 접근 제어, 스키마 보호 등에 대한 설계가 필요하다.

사용 시나리오는 일반적으로 다음과 같은 흐름을 따른다.

• GraphQL 클라이언트(웹/모바일 애플리케이션 등)가 Keycloak에 인증을 요청한다.

• 정상적으로 인증에 성공하면 Access Token을 획득한다.

• 이후 GraphQL API 호출 시, HTTP 요청 헤더에 획득한 Access Token을 포함한다.

• GraphQL 서버 측에서는 Keycloak 라이브러리 또는 자체 JWT 검증 로직을 통해 요청의 유효성을 판별하고, 사용자 권한(Role, Scope) 및 리소스 접근 가능 여부를 확인한다.

1. Keycloak 설정

1. Realm 생성 GraphQL API를 위한 별도의 Realm을 생성하거나 기존 Realm을 사용한다.

2. 클라이언트(Client) 등록 GraphQL 서버 혹은 프런트엔드 애플리케이션을 Keycloak에 클라이언트로 등록한다. 이때 Access Type이 ‘Confidential’인 경우에는 클라이언트 시크릿(Client Secret)을 사용해야 하며, ‘Public’인 경우에는 클라이언트 시크릿이 없이도 OIDC 플로우를 진행할 수 있다.

3. 사용자(User) 및 역할(Role) 설정 GraphQL API가 요구하는 권한 수준에 맞게 사용자 및 역할을 구성한다. 예를 들어 ROLE_ADMIN, ROLE_USER, ROLE_REPORT 등의 역할을 부여해 분기 처리를 수행할 수 있다.

2. GraphQL 서버 측 구성 예시

2.1 Node.js (Apollo Server) 예시

Node.js 환경에서 Apollo Server를 사용할 경우, 다음과 같은 절차로 Keycloak 보호 기능을 연동한다.

1. Keycloak JS/Node 어댑터 설치

   keycloak-connect

   패키지를 설치한다.

   npm install keycloak-connect

2. 세션 스토어 및 Keycloak 미들웨어 등록

   Keycloak은 HTTP 세션을 사용하거나 토큰 기반 방식으로 요청을 검증할 수 있다. 일반적으로 토큰 기반 방식이 선호된다.

   const Keycloak = require('keycloak-connect');
   const session = require('express-session');
   const app = require('express')();
   
   const memoryStore = new session.MemoryStore();
   app.use(session({
     secret: 'YOUR_SESSION_SECRET',
     resave: false,
     saveUninitialized: true,
     store: memoryStore
   }));
   
   const keycloak = new Keycloak({ store: memoryStore });
   app.use(keycloak.middleware());

3. Apollo Server와 통합

   Apollo Server의 context 함수에서 토큰을 검증하고 사용자 정보를 추출한다. 또는 Express 미들웨어 단계에서 이미 검증된 유저 정보를 context로 전달할 수 있다.

   const { ApolloServer, gql } = require('apollo-server-express');
   
   const typeDefs = gql`
     type Query {
       hello: String
       adminData: String
     }
   `;
   
   const resolvers = {
     Query: {
       hello: () => 'Hello World',
       adminData: (_, __, context) => {
         // context.user.role 등을 확인해 권한 판단
         if (!context.user || !context.user.roles.includes('ROLE_ADMIN')) {
           throw new Error('Forbidden');
         }
         return 'Admin data';
       }
     }
   };
   
   const server = new ApolloServer({
     typeDefs,
     resolvers,
     context: ({ req }) => {
       // keycloak-connect를 사용하면 req.kauth에 사용자 정보가 들어있음
       const user = req.kauth && req.kauth.grant
         ? {
             token: req.kauth.grant.access_token.content,
             roles: req.kauth.grant.access_token.content.realm_access.roles
           }
         : null;
       return { user };
     }
   });
   
   server.applyMiddleware({ app });

4. GraphQL API 요청 시 토큰 첨부

   클라이언트 측에서 Keycloak 인증 후 받은 Access Token을 Authorization 헤더에 넣어 전송한다.

   POST /graphql
   Authorization: Bearer <ACCESS_TOKEN>
   {
     query: "{ hello }"
   }

2.2 Java (Spring Boot + GraphQL) 예시

Java 환경에서 Spring Boot와 GraphQL을 사용할 경우, Spring Security와 Keycloak Spring Boot 어댑터를 함께 구성한다.

1. 의존성 추가

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-security</artifactId>
   </dependency>
   <dependency>
       <groupId>org.keycloak</groupId>
       <artifactId>keycloak-spring-boot-starter</artifactId>
       <version>버전에 맞게 입력</version>
   </dependency>
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
   </dependency>
   <dependency>
       <groupId>com.graphql-java</groupId>
       <artifactId>graphql-spring-boot-starter</artifactId>
       <version>버전에 맞게 입력</version>
   </dependency>

2. application.properties 설정

   Keycloak 서버 주소, Realm, 클라이언트 ID 등을 설정한다.

   keycloak.realm=<YOUR_REALM>
   keycloak.auth-server-url=<KEYCLOAK_SERVER_URL>
   keycloak.resource=<CLIENT_ID>
   keycloak.public-client=true
   keycloak.security-constraints[0].authRoles[0]=ROLE_USER
   keycloak.security-constraints[0].securityCollections[0].patterns=/graphql

3. SecurityConfig 구성

   @Configuration
   @EnableWebSecurity
   public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {
   
       @Autowired
       public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
           KeycloakAuthenticationProvider keycloakAuthenticationProvider = keycloakAuthenticationProvider();
           auth.authenticationProvider(keycloakAuthenticationProvider);
       }
   
       @Bean
       @Override
       protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
           return new NullAuthenticatedSessionStrategy();
       }
   
       @Override
       protected void configure(HttpSecurity http) throws Exception {
           super.configure(http);
           http
               .authorizeHttpRequests()
               .antMatchers("/graphql").hasRole("USER")
               .anyRequest().permitAll();
       }
   }

4. GraphQL Resolver에서 사용자 정보 활용

   SecurityContext를 통해 인증된 사용자의 정보를 확인하고, 필요한 경우 권한 기반 처리를 수행한다.

   @Component
   public class QueryResolver implements GraphQLQueryResolver {
   
       public String hello() {
           return "Hello, GraphQL!";
       }
   
       public String adminData() {
           Authentication auth = SecurityContextHolder.getContext().getAuthentication();
           if (auth == null || !auth.getAuthorities().stream().anyMatch(a -> a.getAuthority().equals("ROLE_ADMIN"))) {
               throw new AccessDeniedException("Forbidden");
           }
           return "Admin Data";
       }
   }

3. 보호 범위와 고려 사항

1. Introspection 보호 GraphQL의 스키마 정보는 __schema, __type 등의 introspection 쿼리를 통해 접근 가능하다. 민감도가 높은 환경에서는 introspection을 인증된 사용자 혹은 관리자만 허용하도록 제한해야 한다.

2. 필드 단위 권한 제어 GraphQL은 단일 요청에서 여러 리졸버를 동시에 호출할 수 있다. 특정 필드(혹은 리졸버)에 대해서만 접근 권한을 제한해야 할 수도 있다. 이 경우 리졸버 내에서 또는 별도 권한 체크 로직(Directive, 미들웨어, AOP 등)을 도입해 세분화된 권한 관리를 수행한다.

3. Token 검증 및 갱신 Access Token과 Refresh Token의 유효 기간을 적절히 설정하고, 필요한 경우 자동 갱신(Refresh)을 수행할 수 있도록 클라이언트를 구성한다.

4. 성능 고려 GraphQL은 요청 형태가 매우 유연하기 때문에, 토큰 검증과 Role 확인 절차가 요청마다 여러 번 일어날 수 있다. 로직이 복잡해지면 성능 저하가 발생할 수 있으므로, 캐싱 및 최적화 전략을 마련한다.

Keycloak을 통해 GraphQL API를 보호할 때는 우선 JWT 기반 인증 구조를 확립한 뒤, GraphQL 스키마와 리졸버 수준에서 적절히 권한을 제어해야 한다. 클라이언트와 서버 간 OIDC 플로우를 올바르게 설정하고, Role 기반 접근 제어와 introspection 보호 등 GraphQL 특유의 요구 사항에 맞춘 보안 전략을 마련함으로써 안정적이고 세분화된 인증·인가 환경을 구성할 수 있다.