Part 1

연동 설정

기관 시스템과 aiedu.nextain.io를 연결하는 방법입니다. 키 발급부터 SSO 연동, 도메인 등록까지 다룹니다.

개요

aiedu.nextain.io는 Nextain이 운영하는 AI 튜터 플랫폼입니다. 기관은 자체 인증 시스템에 SSO를 연결하고, 학생별 API 키를 발급받아 플랫폼을 사용합니다.

전체 흐름

text

Nextain admin
  └─ 기관 키(org_key) 발급 → 기관 담당자에게 전달
       └─ 기관 시스템이 학생 키(user_key) 발급 (API 호출)
            └─ 학생이 user_key로 AI 튜터 이용

개발자님이 직접 구현할 부분은 SSO 연동과 학생 키 발급 두 가지입니다. 나머지는 저희가 처리합니다.

키 구조

키 종류	발급 주체	용도
org_key	Nextain (저희)	기관 식별, 페르소나/모델 설정 저장
user_key	기관 시스템 (개발자님)	학생 개인 인증, AI 호출

→org_key는 저희가 발급해서 전달드립니다. 코드에 직접 넣지 않고 서버 환경변수로만 보관하세요.
→user_key는 학생 로그인 시 기관 시스템이 저희 API를 호출해서 자동 발급합니다.

인증 흐름

text

[기관 로그인 시스템 (SSO)]
        │
        │ 로그인 성공 → 유저 정보 (이름, 이메일 등)
        ▼
[기관 백엔드 (언어 무관)]
        │
        │ POST /v1/keys  (org_key + 유저 정보)
        │ → user_key 발급 또는 기존 키 반환
        ▼
[브라우저 / 클라이언트]
        │
        │ POST /api/ai  (user_key + 메시지 + 콘텐츠)
        ▼
[aiedu.nextain.io]
        │
        │ user_key 검증 → 유저 식별 → 페르소나 로드
        │ → AI 응답 반환
        ▼
[AI 튜터 응답]

SSO 연동

방식	설명
OIDC (권장)	OAuth2 기반 로그인. 최신 시스템에서 주로 사용.
SAML 2.0	기업·기관 레거시 시스템에서 주로 사용. XML 기반.

모르시면 기관 IT 담당자에게 "로그인 시스템이 SAML인지 OIDC인지" 확인 후 알려주세요.

OIDC 연동

저희가 제공하는 client_id와 client_secret을 환경변수에 설정합니다.

.env

AIEDU_CLIENT_ID=...
AIEDU_CLIENT_SECRET=...
ORG_KEY=org_...          # Nextain이 전달하는 기관 키

SAML 연동

SAML Assertion에서 추출한 이메일과 이름을 학생 키 발급 API에 전달하면 됩니다. SAML 파싱 라이브러리는 기관 기술 환경에 맞게 선택하세요.

학생 키 발급

학생이 로그인하면 기관 백엔드에서 아래 API를 호출해 user_key를 발급합니다. 같은 user_id로 재호출하면 기존 키가 반환됩니다 (중복 발급 없음).

요청 스펙 — 언어 무관

Method POST

URL {GATEWAY_URL}/v1/keys

Header Authorization: Bearer {ORG_KEY}

json

{
  "user_id": "student@example.com",
  "name": "홍길동",
  "metadata": {
    "type": "user_key",
    "org_key_id": "<저희가 알려드리는 값>"
  }
}

Response { "key": "user_..." }

Python 예시:

python

import requests, os

ORG_KEY = os.environ["ORG_KEY"]
GATEWAY_URL = "https://naia-gateway-181404717065.asia-northeast3.run.app"

def issue_user_key(user_name: str, user_email: str) -> str:
    res = requests.post(
        f"{GATEWAY_URL}/v1/keys",
        headers={"Authorization": f"Bearer {ORG_KEY}"},
        json={
            "user_id": user_email,
            "name": user_name,
            "metadata": {
                "type": "user_key",
                "org_key_id": "<저희가 알려드리는 값>",
            },
        },
    )
    res.raise_for_status()
    return res.json()["key"]

도메인 등록

기관 전용 접속 주소를 등록할 수 있습니다. 예: learn.example.com → 해당 기관 학생만 접속, 해당 기관 SSO 자동 적용.

등록 절차

1
도메인 등록 요청
아래 필요 정보를 이메일로 제출합니다.
2
인증 토큰 수령
저희가 도메인 소유권 확인용 TXT 레코드 값을 발급합니다.
3
DNS TXT 레코드 추가
기관 DNS 관리자에게 요청해 TXT 레코드를 추가합니다.
4
인증 확인 후 활성화
저희가 레코드를 확인하면 도메인 등록이 완료됩니다.

DNS TXT 레코드 예시

dns

# 레코드 타입: TXT
# 호스트: _aiedu-challenge.learn.example.com
# 값: aiedu-challenge=abc123xyz (저희가 발급하는 토큰)

DNS 전파는 최대 48시간 소요될 수 있습니다. 추가 후 저희에게 알려주시면 확인합니다.

등록 시 필요 정보

항목	설명	예시
도메인	기관 전용 접속 주소	learn.example.com
SSO 방식	해당 도메인에 적용할 인증 방식	SAML / OIDC
SSO 메타데이터 URL	IdP 메타데이터 주소	https://idp.example.com/metadata
허용 이메일 도메인	접속 허용할 이메일 패턴	@example.com

페르소나 설정→