지나패스 연동 가이드

지나패스가 뭔가요

지나패스는 지나월드의 무자각 얼굴인증 신원 제공자(IdP)예요. 사용자는 얼굴로 자기 자신을 증명하지만, 여러분의 서비스에는 그 얼굴이 오지 않습니다. 대신 표준 OIDC 토큰(id_token)이 넘어오고, 그 안에는 이 사용자를 안정적으로 식별하는 익명 sub가 담겨요. 같은 사람은 여러분 서비스에서 언제나 같은 sub로 돌아옵니다.

• 발급기관(issuer): https://pass.jina.world
• 흐름: Authorization Code Flow + PKCE (S256)
• 서명: RS256 — JWKS 공개키로 검증(시크릿 공유 없이 id_token 검증 가능)
• 스코프: openid(필수), profile(name 클레임 추가)

OpenID Connect를 처음 붙이더라도, 이 문서의 3스텝과 코드 예시만 따라 하면 됩니다.

빠른 시작 · 3스텝

{
  "client_id": "ticketfarm",
  "redirect_uris": ["https://ticketfarm.example.com/callback"],
  "name": "티켓팜"
  // client_secret 없으면 공개 클라이언트 → PKCE 필수
}

const ISSUER = 'https://pass.jina.world';
const CLIENT_ID = 'ticketfarm';
const REDIRECT = 'https://ticketfarm.example.com/callback';

// PKCE verifier 생성 → 세션에 보관
const verifier = rand() + rand();          // 충분히 긴 랜덤
sessionStorage.setItem('pkce_verifier', verifier);
const state = rand();
sessionStorage.setItem('oidc_state', state);
const challenge = await sha256b64(verifier); // S256

const u = new URL(ISSUER + '/authorize');
u.search = new URLSearchParams({
  response_type: 'code',
  client_id:     CLIENT_ID,
  redirect_uri:  REDIRECT,
  scope:         'openid profile',
  state,
  nonce:         rand(),
  code_challenge:        challenge,
  code_challenge_method: 'S256',
}).toString();
location.href = u.toString();

const q = new URL(location.href).searchParams;
if (q.get('state') !== sessionStorage.getItem('oidc_state'))
  throw new Error('state 불일치(위조 의심)');

const body = new URLSearchParams({
  grant_type:    'authorization_code',
  code:          q.get('code'),
  redirect_uri:  REDIRECT,
  client_id:     CLIENT_ID,
  code_verifier: sessionStorage.getItem('pkce_verifier'),
  // client_secret 있으면 여기 함께(client_secret_post) — 서버에서만!
});
const r = await fetch(ISSUER + '/token', {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body,
}).then(r => r.json());

// r.id_token 을 JWKS 공개키로 검증 후 클레임 사용
const claims = verifyIdToken(r.id_token); // sub, name, iss, aud, exp ...
console.log(claims.sub, claims.name);

엔드포인트 레퍼런스

모든 경로의 기준(issuer)은 https://pass.jina.world 입니다.

지원 스펙: response_types=["code"], grant_types=["authorization_code"], subject_types=["public"], id_token_signing_alg=["RS256"], scopes=["openid","profile"], code_challenge_methods=["S256"], token_endpoint_auth_methods=["client_secret_post","client_secret_basic","none"].

id_token 클레임

전체 코드 예시

아래는 브라우저(공개 클라이언트) 기준 최소 구현이에요. 실제 동작하는 릴레잉파티(oidc-demo.html)에서 발췌·정리했습니다.

const ISSUER    = 'https://pass.jina.world';
const CLIENT_ID = 'ticketfarm';
const REDIRECT  = location.origin + location.pathname;

// ── PKCE / 유틸 ─────────────────────────────
const b64url = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
const rand = () => { const a = new Uint8Array(32); crypto.getRandomValues(a); return b64url(a.buffer); };
async function sha256b64(s) {
  return b64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(s)));
}
function decodeJwtPayload(jwt) {
  return JSON.parse(atob(jwt.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
}

// ── 1) 로그인 시작 → /authorize ─────────────
async function login() {
  const verifier = rand() + rand();
  sessionStorage.setItem('pkce_verifier', verifier);
  const state = rand();
  sessionStorage.setItem('oidc_state', state);
  const challenge = await sha256b64(verifier);

  const u = new URL(ISSUER + '/authorize');
  u.search = new URLSearchParams({
    response_type: 'code', client_id: CLIENT_ID, redirect_uri: REDIRECT,
    scope: 'openid profile', state, nonce: rand(),
    code_challenge: challenge, code_challenge_method: 'S256',
  }).toString();
  location.href = u.toString();
}

// ── 2) 콜백 처리 → /token 교환 ──────────────
async function handleCallback() {
  const q = new URL(location.href).searchParams;
  if (q.get('error')) throw new Error(q.get('error'));
  const code = q.get('code');
  if (!code) return null;                       // 첫 방문
  if (q.get('state') !== sessionStorage.getItem('oidc_state'))
    throw new Error('state 불일치');

  const body = new URLSearchParams({
    grant_type: 'authorization_code', code, redirect_uri: REDIRECT,
    client_id: CLIENT_ID, code_verifier: sessionStorage.getItem('pkce_verifier'),
  });
  const r = await fetch(ISSUER + '/token', {
    method: 'POST',
    headers: { 'content-type': 'application/x-www-form-urlencoded' },
    body,
  }).then(r => r.json());
  if (!r.id_token) throw new Error(r.error || 'token 교환 실패');

  history.replaceState({}, '', REDIRECT);        // URL에서 code 제거
  return decodeJwtPayload(r.id_token);          // { sub, name, iss, aud, ... }
}

직접 눌러보기

실제로 동작하는 릴레잉파티 데모가 준비돼 있어요. "티켓팜"이라는 가상의 외부 서비스가 지나패스로 로그인하고, 넘어온 sub/name/iss/aud 클레임을 그대로 보여줍니다.

보안 노트

• PKCE(S256)를 항상 사용하세요. 공개 클라이언트(SPA·모바일)는 client_secret이 없으므로 PKCE가 필수입니다. 서버 앱도 함께 쓰면 더 안전해요.
• redirect_uri는 등록한 값과 정확히 일치해야 합니다. 미등록 URI로는 리다이렉트 자체가 거부됩니다(오픈 리다이렉트 방지). 경로·쿼리·트레일링 슬래시까지 동일해야 해요.
• client_secret은 서버에만 보관하세요. 브라우저·앱 번들에 넣지 마세요. 시크릿이 필요 없는 구조라면 공개 클라이언트 + PKCE로 가는 편이 안전합니다.
• 인가 code는 1회용, TTL 1분입니다. 받은 즉시 /token으로 교환하세요. 재사용·만료된 코드는 invalid_grant로 거부됩니다.
• state와 nonce를 검증하세요. state는 CSRF, nonce는 토큰 재생을 막습니다.
• 토큰 검증은 iss·aud·exp·서명까지. iss가 https://pass.jina.world인지, aud가 여러분의 client_id인지 반드시 확인하세요.