기존 인증 시스템 연동하기

기존 인증 시스템을 사용하여 Volr SDK를 원활하게 통합하세요. BYO Auth를 사용하면 필요할 때만 Volr 세션을 생성할 수 있으며, 사용자가 실제로 결제를 해야 할 때까지 지갑 생성을 지연시킬 수 있습니다.

어떤 방법을 선택해야 하나요?

기존 인증 설정에 가장 적합한 통합 방법을 선택하세요:

빠른 결정 가이드

백엔드 서버가 있나요?

✅ 예 → Server Session Injection 사용 (권장)
❌ 아니오 → OIDC Token Exchange 사용

OIDC/JWT 인증을 사용하고 있나요?

✅ 예 → OIDC Token Exchange 사용
❌ 아니오 → Server Session Injection 사용

비교

특징	Server Session Injection	OIDC Token Exchange
보안	높음 (서버 측)	중간 (클라이언트 측 교환)
구현 난이도	쉬움	중간
권장 상황	백엔드 서버가 있는 경우	이미 OIDC/JWT를 사용하는 경우
필요 사항	백엔드 API 엔드포인트	OIDC 발급자 설정

Server Session Injection

이 방법이 맞나요?

✅ 백엔드 서버가 있습니다 (Node.js, Python 등)
✅ 서버 측 API 호출이 가능합니다
✅ 최고의 보안을 원합니다 (서버 측 토큰 생성)

작동 원리

[사용자 로그인]
    ↓
[백엔드 인증 완료]
    ↓
[백엔드 → Volr API]
    ↓
[Volr 토큰 받기]
    ↓
[SDK에 주입]
    ↓
[Volr SDK 준비 완료!]

단계별 가이드

1단계: Server Secret 생성

Volr Dashboard의 프로젝트 설정으로 이동
Settings > Authentication > BYO Auth로 이동
Server Session Injection 선택
Generate Secret 또는 Rotate Secret 클릭
즉시 시크릿 복사 (한 번만 표시됨)
서버 환경 변수에 안전하게 저장 (예: AWS Secrets Manager)

⚠️ 서버 시크릿을 클라이언트에 노출하지 마세요!

2단계: 백엔드 엔드포인트 생성

Volr API를 호출하여 세션을 생성하는 백엔드 엔드포인트를 만듭니다.

Node.js/Express 예제:

app.post('/api/auth/volr-session', async (req, res) => {
  // 인증 미들웨어에서 인증된 사용자 가져오기
  const { userId, email, name } = req.user;
  
  const response = await fetch('https://api.volr.io/auth/external/session', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.VOLR_API_KEY,
      'X-Volr-Server-Secret': process.env.VOLR_SERVER_SECRET,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      externalUserId: userId,
      email: email,
      name: name,
    }),
  });
  
  if (!response.ok) {
    return res.status(500).json({ error: 'Failed to create Volr session' });
  }
  
  const { accessToken, refreshToken } = await response.json();
  res.json({ accessToken, refreshToken });
});

Next.js API Route 예제:

// pages/api/auth/volr-session.ts (또는 app/api/auth/volr-session/route.ts)
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // 세션/인증에서 인증된 사용자 가져오기
  const user = await getAuthenticatedUser(req);
  if (!user) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  try {
    const response = await fetch('https://api.volr.io/auth/external/session', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.VOLR_API_KEY!,
        'X-Volr-Server-Secret': process.env.VOLR_SERVER_SECRET!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        externalUserId: user.id,
        email: user.email,
        name: user.name,
      }),
    });
    
    if (!response.ok) {
      const error = await response.text();
      return res.status(response.status).json({ error });
    }
    
    const { accessToken, refreshToken } = await response.json();
    res.json({ accessToken, refreshToken });
  } catch (error) {
    console.error('Volr session creation failed:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
}

Python/FastAPI 예제:

from fastapi import FastAPI, Depends, HTTPException
import httpx
import os

app = FastAPI()

@app.post("/api/auth/volr-session")
async def create_volr_session(user: dict = Depends(get_authenticated_user)):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.volr.io/auth/external/session",
            headers={
                "X-API-Key": os.getenv("VOLR_API_KEY"),
                "X-Volr-Server-Secret": os.getenv("VOLR_SERVER_SECRET"),
                "Content-Type": "application/json",
            },
            json={
                "externalUserId": user["id"],
                "email": user.get("email"),
                "name": user.get("name"),
            },
        )
        
        if response.status_code != 200:
            raise HTTPException(status_code=500, detail="Failed to create Volr session")
        
        data = response.json()
        return {"accessToken": data["accessToken"], "refreshToken": data["refreshToken"]}

3단계: 클라이언트에 세션 주입

사용자가 로그인한 후 백엔드 엔드포인트를 호출하고 Volr 세션을 주입합니다.

React 예제:

import { useVolrSession } from '@volr/react';
import { useEffect } from 'react';

function App() {
  const { setSession } = useVolrSession();
  
  useEffect(() => {
    // 기존 로그인이 성공한 후
    yourLoginFunction().then(async (user) => {
      // 백엔드에서 Volr 세션 가져오기
      const res = await fetch('/api/auth/volr-session', {
        credentials: 'include', // 세션 쿠키 포함
      });
      
      if (!res.ok) {
        console.error('Failed to get Volr session');
        return;
      }
      
      const { accessToken, refreshToken } = await res.json();
      
      // Volr SDK에 주입
      await setSession({ accessToken, refreshToken });
      
      // 이제 Volr SDK를 사용할 수 있습니다!
    });
  }, [setSession]);
}

4단계: 통합 테스트

세션이 올바르게 주입되고 Volr SDK가 정상적으로 작동하는지 확인합니다.

import { useVolr } from '@volr/react';

function TestComponent() {
  const { evm, isLoggedIn } = useVolr();
  
  if (!isLoggedIn) {
    return <div>로그인되지 않음</div>;
  }
  
  return (
    <div>
      <p>지갑 주소: {evm.address}</p>
      {/* Volr SDK가 준비되었습니다! */}
    </div>
  );
}

문제 해결

오류: "Failed to create Volr session"

서버 환경에서 VOLR_API_KEY와 VOLR_SERVER_SECRET이 올바르게 설정되었는지 확인
externalUserId가 올바르게 전송되는지 확인
자세한 오류 메시지는 서버 로그 확인

오류: "Unauthorized"

서버 시크릿이 만료되지 않았는지 확인 (대시보드에서 회전 날짜 확인)
시크릿이 대시보드에 구성된 것과 일치하는지 확인

세션이 유지되지 않음

로그인 성공 후 setSession을 호출하는지 확인
백엔드 엔드포인트에서 토큰이 올바르게 반환되는지 확인

OIDC Token Exchange

이 방법이 맞나요?

✅ OIDC/JWT 기반 인증을 사용하고 있습니다 (Auth0, Okta 등)
✅ 인증 제공자에서 ID 토큰에 액세스할 수 있습니다
✅ 백엔드 변경 없이 더 간단한 통합을 원합니다

작동 원리

[OIDC로 사용자 로그인]
    ↓
[ID 토큰 받기]
    ↓
[Volr과 교환]
    ↓
[Volr SDK 준비 완료!]

단계별 가이드

1단계: OIDC 설정 구성

Volr Dashboard의 프로젝트 설정으로 이동
Settings > Authentication > BYO Auth로 이동
OIDC Token Exchange 선택
OIDC 제공자 세부 정보 입력:
- OIDC Issuer: OIDC 제공자의 발급자 URL (예: https://your-domain.auth0.com/)
- JWKS URL: Volr이 제공자의 공개 키를 가져올 수 있는 URL (예: https://your-domain.auth0.com/.well-known/jwks.json)
- Audience: ID 토큰의 aud 클레임과 일치해야 함
Save OIDC Settings 클릭

2단계: 인증 제공자에서 ID 토큰 가져오기

OIDC 제공자로 사용자가 로그인한 후 ID 토큰을 가져옵니다.

// 예제: OIDC 로그인 후
const idToken = await yourOidcProvider.getIdToken();

3단계: ID 토큰을 Volr 세션으로 교환

ID 토큰으로 exchangeOidc를 호출하여 Volr 세션 토큰을 가져옵니다.

import { useVolrSession } from '@volr/react';
import { useEffect } from 'react';

function AfterOidcLogin({ idToken }) {
  const { exchangeOidc } = useVolrSession();
  
  useEffect(() => {
    exchangeOidc(idToken)
      .then((result) => {
        console.log('Volr session created:', result);
        // Volr SDK가 이제 준비되었습니다!
      })
      .catch((error) => {
        console.error('Failed to exchange token:', error);
      });
  }, [idToken, exchangeOidc]);
}

4단계: 통합 테스트

세션이 올바르게 생성되고 Volr SDK가 작동하는지 확인합니다.

import { useVolr } from '@volr/react';

function TestComponent() {
  const { evm, isLoggedIn } = useVolr();
  
  if (!isLoggedIn) {
    return <div>로그인되지 않음</div>;
  }
  
  return (
    <div>
      <p>지갑 주소: {evm.address}</p>
    </div>
  );
}

보안 팁

더 엄격한 보안을 위해 서버에서 토큰을 교환한 다음 클라이언트에서 setSession을 호출하세요. 이렇게 하면 토큰 교환 로직이 서버 측에 유지됩니다.

문제 해결

오류: "Invalid token"

OIDC 발급자, JWKS URL 및 대상이 올바르게 구성되었는지 확인
ID 토큰의 aud 클레임이 구성된 대상과 일치하는지 확인
토큰이 만료되지 않았는지 확인

오류: "Token validation failed"

JWKS URL에 액세스할 수 있고 유효한 키를 반환하는지 확인
토큰 서명이 제공자의 키와 일치하는지 확인

세션이 유지되지 않음

OIDC 로그인 성공 후 exchangeOidc를 호출하는지 확인
ID 토큰이 유효하고 만료되지 않았는지 확인

다음 단계

BYO Auth를 성공적으로 통합한 후:

지갑 생성 테스트: 사용자가 처음 결제할 때 지갑이 생성되는지 확인
결제 흐름 구성: Volr SDK를 사용하여 결제 통합 설정
사용량 모니터링: 대시보드에서 인증 및 지갑 생성 메트릭 확인

자세한 내용은 다음을 참조하세요:

어떤 방법을 선택해야 하나요?​

빠른 결정 가이드​

비교​

Server Session Injection​

이 방법이 맞나요?​

작동 원리​

단계별 가이드​

1단계: Server Secret 생성​

2단계: 백엔드 엔드포인트 생성​

3단계: 클라이언트에 세션 주입​

4단계: 통합 테스트​

문제 해결​

OIDC Token Exchange​

이 방법이 맞나요?​

작동 원리​

단계별 가이드​

1단계: OIDC 설정 구성​

2단계: 인증 제공자에서 ID 토큰 가져오기​

3단계: ID 토큰을 Volr 세션으로 교환​

4단계: 통합 테스트​

보안 팁​

문제 해결​

다음 단계​

어떤 방법을 선택해야 하나요?

빠른 결정 가이드

비교

Server Session Injection

이 방법이 맞나요?

작동 원리

단계별 가이드

1단계: Server Secret 생성

2단계: 백엔드 엔드포인트 생성

3단계: 클라이언트에 세션 주입

4단계: 통합 테스트

문제 해결

OIDC Token Exchange

이 방법이 맞나요?

작동 원리

단계별 가이드

1단계: OIDC 설정 구성

2단계: 인증 제공자에서 ID 토큰 가져오기

3단계: ID 토큰을 Volr 세션으로 교환

4단계: 통합 테스트

보안 팁

문제 해결

다음 단계