パート 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

ペルソナ設定→