애플리케이션 키 관리자

애플리케이션 키 관리자는 reCAPTCHA, AI API Key, 결제 키, Webhook Secret, Public Site Key 등 외부 서비스 연동에 필요한 키를 안전하게 저장하고 관리하는 기능입니다.

외부 서비스 키를 페이지, JavaScript, 컨트롤러, 설정 파일에 직접 하드코딩하지 않고 중앙에서 안전하게 관리해야 할 때 사용하는 기능입니다.

화면 개요

Application Key Manager는 애플리케이션 수준의 Secret 값과 Public Key를 관리하는 보안 키 저장소입니다. 그룹, Provider, Environment, Key Type, 암호화 저장, Public Key 조회, 서버 코드 사용, HTML Token Replacement 기능을 지원합니다.

Search Filters

Search Filters 영역은 저장된 키를 빠르게 찾기 위한 검색 조건입니다.

Summary Cards

Summary Cards는 현재 키 저장소의 상태를 빠르게 확인할 수 있게 해줍니다.

Key List

Key List 테이블에는 저장된 애플리케이션 키가 표시됩니다. 등록된 키가 없으면 No application keys found. 메시지가 표시됩니다.

Create Application Key

Create Application Key 화면은 외부 서비스 키를 안전하게 저장하는 화면입니다. Secret 값은 저장 전에 암호화됩니다.

Basic Settings

기존 키를 수정할 때 현재 저장된 값을 유지하려면 Key Value를 비워 둔 상태로 저장하세요.

Key Types

Usage Guide

Usage Guide는 애플리케이션 키를 생성하고 서버 코드, 브라우저 코드, reCAPTCHA 연동, 보안 규칙, Token Replacement에서 사용하는 방법을 설명합니다.

기본 사용법

1. 필터를 사용해 저장된 키를 검색합니다.
2. Create Key를 클릭해 새 키를 추가합니다.
3. 기존 키는 Edit로 수정합니다.
4. Test 기능이 있다면 암호화된 키가 정상적으로 복호화되는지 확인합니다.

Server Usage

내부 서비스나 컨트롤러에서 키 값을 읽어야 할 때는 IAppKeyProvider를 사용합니다.

IAppKeyProvider 주입

private readonly IAppKeyProvider _appKeyProvider;

public MyService(IAppKeyProvider appKeyProvider)
{
    _appKeyProvider = appKeyProvider;
}

일반 키 값 가져오기

string apiKey = await _appKeyProvider.GetValueAsync("OPENAI_API_KEY", "PROD");

Google reCAPTCHA Site Key 가져오기

string siteKey = await _appKeyProvider.GetGoogleRecaptchaSiteKeyAsync("PROD");

Google reCAPTCHA Secret Key 가져오기

string secretKey = await _appKeyProvider.GetGoogleRecaptchaSecretKeyAsync("PROD");

Public Key Usage

Public Key 사용은 브라우저에 노출해도 되는 키에만 사용해야 합니다. Public Key 전용 Endpoint는 SECRET 키를 차단하고 Key Type이 PUBLIC인 키만 반환합니다.

Controller Endpoint

/Admin/AppKeys/GetSiteKey?keyCode=GOOGLE_RECAPTCHA_SITE_KEY&environmentCode=PROD

JavaScript 예제

async function loadSiteKey() {
    const response = await fetch("/Admin/AppKeys/GetSiteKey?keyCode=GOOGLE_RECAPTCHA_SITE_KEY&environmentCode=PROD");
    const result = await response.json();

    if (!result.success) {
        throw new Error(result.message || "Failed to load site key.");
    }

    return result.value;
}

SECRET, TOKEN, 결제 Secret, Webhook Secret, AI API Key를 JavaScript에 노출하지 마세요.

reCAPTCHA Enterprise v3 예제

점수 기반 reCAPTCHA Enterprise에서는 브라우저가 grecaptcha.enterprise.execute로 토큰을 받은 뒤, 서버가 Google Cloud Assessment API로 토큰을 검증합니다.

필요한 키

• GOOGLE_RECAPTCHA_SITE_KEY - Key Type: PUBLIC
• GOOGLE_RECAPTCHA_PROJECT_ID - Key Type: CONFIG
• GOOGLE_RECAPTCHA_API_KEY - Key Type: SECRET

Client Script 예제

<script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY"></script>

const token = await grecaptcha.enterprise.execute(SITE_KEY, {
    action: "newsletter_subscribe"
});

Server Validation 개념

if (!tokenProperties.Valid) return false;
if (tokenProperties.Action != "newsletter_subscribe") return false;
if (riskAnalysis.Score < 0.5m) return false;

Security Notes

저장, 삭제, 상태 변경 후 컨트롤러가 캐시된 키 값을 비워 최신 키를 바로 사용할 수 있도록 합니다.

Token Replacement

Token Replacement는 저장된 HTML, 스킨 파일, 페이지 빌더 콘텐츠, DB 관리 템플릿을 렌더링할 때 유용합니다.

기본 개념

실제 키 값을 HTML에 직접 쓰지 않고 ##{GOOGLE_RECAPTCHA_SITE_KEY}## 같은 토큰 패턴을 작성합니다. 렌더링 시 서버가 해당 토큰을 키 관리자에 저장된 실제 값으로 교체합니다.

HTML Template 예제

<input type="hidden"
       id="NewsletterRecaptchaSiteKey"
       value="##{GOOGLE_RECAPTCHA_SITE_KEY}##" />

Rendered HTML 결과

<input type="hidden"
       id="NewsletterRecaptchaSiteKey"
       value="actual-google-recaptcha-site-key" />

Server Replacement 예제

string googleRecaptchaSiteKey =
    await _appKeyProvider.GetGoogleRecaptchaSiteKeyAsync("PROD");

result = result.Replace(
    "##{GOOGLE_RECAPTCHA_SITE_KEY}##",
    googleRecaptchaSiteKey ?? string.Empty
);

General Replacement Helper 예제

private async Task<string> ReplaceAppKeyTokensAsync(string html)
{
    if (string.IsNullOrWhiteSpace(html))
    {
        return string.Empty;
    }

    string googleRecaptchaSiteKey =
        await _appKeyProvider.GetValueAsync("GOOGLE_RECAPTCHA_SITE_KEY", "PROD");

    string googleProjectId =
        await _appKeyProvider.GetValueAsync("GOOGLE_RECAPTCHA_PROJECT_ID", "PROD");

    html = html.Replace("##{GOOGLE_RECAPTCHA_SITE_KEY}##", googleRecaptchaSiteKey ?? string.Empty);
    html = html.Replace("##{GOOGLE_RECAPTCHA_PROJECT_ID}##", googleProjectId ?? string.Empty);

    return html;
}

권장 작업 순서

1. Admin > Site > AppKeys 메뉴로 이동합니다.
2. Create Key를 클릭합니다.
3. 고유한 Key Code를 입력합니다.
4. 관리자가 알아보기 쉬운 Key Name을 입력합니다.
5. Group, Provider, Environment, Key Type을 선택합니다.
6. Key Value를 입력합니다.
7. 이 키가 어디에 사용되는지 Description에 작성합니다.
8. 사용 가능한 키라면 Active를 체크합니다.
9. Save Key를 클릭합니다.
10. 키 타입에 따라 서버 코드, Public Endpoint, Token Replacement에서 사용합니다.

자주 사용하는 작업

주의사항

• SECRET 값은 저장 전에 암호화됩니다.
• 기존 SECRET 값은 평문으로 표시되지 않습니다.
• 기존 저장 값을 유지하려면 수정 시 Key Value를 비워 두세요.
• 브라우저에 노출해도 되는 값에만 PUBLIC을 사용하세요.
• SECRET, TOKEN, 결제 Secret, Webhook Secret, AI API Key를 JavaScript나 HTML에 노출하지 마세요.
• DEV, TEST, PROD처럼 환경을 분리해서 사용하세요.
• 유출되었거나 오래된 키는 즉시 교체하세요.

문제 해결

관리 권장 사항

• GOOGLE_RECAPTCHA_SITE_KEY, OPENAI_API_KEY처럼 명확한 Key Code를 사용하세요.
• Provider 이름은 GOOGLE, OPENAI, STRIPE, SENDGRID처럼 일관되게 관리하세요.
• 운영 키와 개발 키는 Environment로 분리하세요.
• 비공개 인증 정보는 SECRET으로 저장하고, 브라우저 안전 값에만 PUBLIC을 사용하세요.
• Description에 각 키가 어디에 사용되는지 기록하세요.
• 민감한 키는 주기적으로 교체하세요.
• 이 화면은 신뢰할 수 있는 관리자에게만 접근 권한을 부여하세요.

애플리케이션 키는 외부 서비스 접근 권한과 직접 연결되는 경우가 많습니다. Secret 값을 보호하고, 비공개 인증 정보가 브라우저에 노출되지 않도록 신중하게 관리하세요.