빠른 시작

시작하기

1분 안에 Spring Boot 애플리케이션에 Contexa AI 보안을 적용하세요. 스타터 의존성을 추가하고, AI 보안을 활성화하고, 설정하고, 실행합니다.

사전 요구 사항

시작하기 전에 다음이 설치되어 실행 중인지 확인하세요:

요구 사항 버전 비고
Java 21+ LTS 릴리스
PostgreSQL 15+ pgvector 확장 포함
Ollama Latest 로컬 LLM 추론

데이터베이스 설정

데이터베이스를 생성하고 필요한 확장을 활성화하세요:

SQL 
CREATE DATABASE contexa;
\c contexa
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

Ollama 모델

채팅과 임베딩에 필요한 모델을 다운로드하세요:

Shell 
ollama pull qwen3.5:9b
ollama pull mxbai-embed-large
1

의존성 추가

프로젝트에 Contexa Spring Boot Starter를 추가하세요. 이 단일 의존성으로 필요한 모든 모듈이 포함됩니다: contexa-core, contexa-identity, contexa-iam, contexa-common, contexa-autoconfigure.

Gradle (Kotlin DSL) 
dependencies {
    implementation("ai.ctxa:spring-boot-starter-contexa:0.1.0")
}
Gradle (Groovy) 
dependencies {
    implementation 'ai.ctxa:spring-boot-starter-contexa:0.1.0'
}
Maven 
<dependency>
    <groupId>ai.ctxa</groupId>
    <artifactId>spring-boot-starter-contexa</artifactId>
    <version>0.1.0</version>
</dependency>

전이적 의존성 — Starter에는 Spring Security, Spring AI, 그리고 모든 Contexa 모듈이 포함되어 있습니다. 특정 버전을 재정의해야 하는 경우가 아니라면 개별적으로 선언할 필요가 없습니다.

2

AI 보안 활성화

메인 애플리케이션 클래스에 @EnableAISecurity를 추가하세요. 이 어노테이션은 Contexa AI 보안 인프라 전체를 활성화합니다. 사용자가 정의한 PlatformConfig Bean이 없으면 AiSecurityConfiguration.platformDslConfig()가 IdentityDslRegistry를 사용해 기본 PlatformConfig를 자동 등록하고 Zero Trust 필터 체인을 자동으로 연결합니다.

Java 
@SpringBootApplication
@EnableAISecurity
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

내부 동작 원리 — @EnableAISecurity는 @Import(AiSecurityImportSelector.class)로 메타 어노테이션되어 있으며, 이 셀렉터는 AiSecurityConfiguration을 임포트합니다. 해당 구성 클래스에는 @ConditionalOnMissingBean(PlatformConfig.class) 조건이 걸린 platformDslConfig() 팩토리가 있으며, 사용자 Bean이 없을 때 IdentityDslRegistry로 기본 PlatformConfig를 구축합니다.

3

설정

인프라 모드, 데이터소스, LLM 프로바이더에 대한 최소 필수 설정으로 application.yml을 생성하거나 업데이트하세요.

YAML 
contexa:
  infrastructure:
    mode: standalone
  llm:
    chatModelPriority: ollama,anthropic,openai
    embeddingModelPriority: ollama,openai
    chat:
      ollama:
        baseUrl: http://127.0.0.1:11434
        model: qwen3.5:9b
        keepAlive: 24h
    embedding:
      ollama:
        baseUrl: http://127.0.0.1:11434
        model: mxbai-embed-large

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/contexa
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driver-class-name: org.postgresql.Driver

  ai:
    vectorstore:
      pgvector:
        table-name: vector_store
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1024
        initialize-schema: true

  jpa:
    database: POSTGRESQL
    hibernate:
      ddl-auto: update

모델 우선순위 — contexa.llm.chatModelPriority 속성은 쉼표로 구분된 프로바이더 목록을 받습니다. Contexa는 각 프로바이더를 순서대로 시도하며, 사용 불가 시 다음 프로바이더로 폴백합니다. 지원 값: ollama, anthropic, openai. 기본값은 ollama,anthropic,openai입니다.

4

실행 및 확인

애플리케이션을 시작하고 Contexa가 활성 상태인지 확인하세요.

Shell 
# Gradle
./gradlew bootRun

# Maven
mvn spring-boot:run

확인: 자동 설정 리포트

--debug 플래그를 사용하여 어떤 Contexa 자동 설정이 적용되었는지 확인하세요:

Shell 
./gradlew bootRun --args='--debug'

양성 매치(positive matches) 섹션에서 CoreInfrastructureAutoConfiguration, CoreLLMAutoConfiguration, CoreHCADAutoConfiguration을 확인하세요.

확인: Actuator Health 엔드포인트

의존성에 spring-boot-starter-actuator가 없다면 추가한 후, Health 엔드포인트를 확인하세요:

Shell 
curl http://localhost:8080/actuator/health

데이터베이스 필수 — PostgreSQL에 연결할 수 없으면 Contexa가 시작되지 않습니다. 애플리케이션을 실행하기 전에 데이터소스 설정이 올바르고 데이터베이스가 존재하는지 확인하세요.

메서드 수준 보안

첫 번째 메서드 보호하기

@Protectable 어노테이션을 사용하여 모든 서비스 메서드에 AI 기반 Zero Trust 적용을 추가하세요. 각 호출은 AuthorizationManagerMethodInterceptor가 가로채며, ProtectableMethodAuthorizationManager가 Spring Security의 MethodSecurityExpressionHandler를 통해 평가합니다. sync = true인 경우 SynchronousProtectableDecisionService가 SecurityPlaneAgent를 인라인으로 호출하여 메서드 반환 전 ZeroTrustAction 결정을 생성하며, sync = false(기본값)인 경우 ZeroTrustSpringEvent가 발행되고 평가가 비동기로 수행됩니다.

Java 
@Service
public class OrderService {

    @Protectable
    public Order getOrder(Long orderId) {
        return orderRepository.findById(orderId)
                .orElseThrow(() -> new OrderNotFoundException(orderId));
    }
}

@Protectable 속성

속성 타입 기본값 설명
ownerField String "" 소유권 기반 인가 검사를 위해 리소스 소유자를 식별하는 반환 타입의 필드명.
sync boolean false true로 설정하면 메서드가 반환되기 전에 Zero Trust 평가가 동기적으로 완료됩니다. false(기본값)인 경우 평가가 비동기적으로 실행되고 메서드는 즉시 진행됩니다.
AI 결정

다음 단계 — Zero Trust Actions

Contexa가 평가하는 모든 요청은 다음 ZeroTrustAction 결정 중 하나를 생성합니다. AI 엔진은 행동 분석, 위협 평가, 신뢰 점수를 기반으로 적절한 조치를 결정합니다.

액션 HTTP 상태 TTL 동작
ALLOW 200 15s 요청이 정상적으로 처리됩니다
BLOCK 403 영구 요청이 거부됩니다; 사용자에게 ROLE_BLOCKED가 부여됩니다
CHALLENGE 401 1800s 추가 인증이 필요합니다 (MFA); 사용자에게 ROLE_MFA_REQUIRED가 부여됩니다
ESCALATE 423 300s 수동 검토를 위해 요청이 보류됩니다; 사용자에게 ROLE_REVIEW_REQUIRED가 부여됩니다
PENDING_ANALYSIS 503 0s AI 분석이 진행 중입니다; 사용자에게 ROLE_PENDING_ANALYSIS가 부여되며 평가가 완료될 때까지 요청이 지연됩니다

AI 기반 결정 — 기존의 규칙 기반 시스템과 달리, Contexa의 LLM 엔진은 실시간 행동 분석을 기반으로 각 요청에 대한 적절한 조치를 결정합니다. 정적 규칙을 설정할 필요 없이 AI가 애플리케이션의 트래픽 패턴을 학습하고 적응합니다.

다음 단계

전체 문서를 탐색하여 고급 기능, 설정 옵션, 아키텍처 세부 사항을 알아보세요.

Spring Boot 통합

Identity DSL을 설정하고, 인증 흐름을 커스터마이즈하고, CustomDynamicAuthorizationManager와 통합하세요.

문서 보기 →

Core — AI 엔진

AI 파이프라인 아키텍처, 모델 설정, SSE 스트리밍.

문서 보기 →

Zero Trust 아키텍처

이중 흐름 아키텍처, AISecurityContextRepository, 지속적 신뢰 평가.

문서 보기 →

@Protectable 레퍼런스

XACML 정책 엔진, 동적 인가, 메서드 수준 보호.

문서 보기 →

설정 레퍼런스

contexa.*, spring.ai.*, 인프라 모드에 대한 전체 속성 레퍼런스.

문서 보기 →

Shadow Mode 가이드

2단계 마이그레이션 경로: 관찰을 위한 Shadow 모드, 전체 AI 적용을 위한 Enforce 모드.

문서 보기 →