OAuth 2.0 인증

비대칭 키 암호화 방식을 사용해 백엔드 서비스를 Zonos와 인증합니다 — 공유 비밀키가 필요 없습니다.

Zonos는 OAuth 2.0 JWT Bearer 토큰 부여(RFC 7523)를 통한 서버 간(machine-to-machine) 인증을 지원합니다. 서비스가 RSA 개인 키로 단기 유효 JWT에 서명하면, Zonos는 등록된 공개 키로 이를 검증하고 조직 범위로 한정된 Bearer 토큰을 반환합니다.

흐름 요약:

RSA 키 페어를 생성하고 공개 키를 Zonos에 등록합니다.
실행 시점에 개인 키로 JWT assertion에 서명하고 토큰 엔드포인트로 POST합니다.
Zonos가 단기 유효 액세스 토큰을 반환합니다.
모든 API 요청에 액세스 토큰을 Authorization: Bearer <token> 형식으로 포함합니다.

Step 1 — 공개 키 등록(최초 1회 설정)

4096비트 RSA 키 페어를 생성하고 공개 키를 Zonos와 공유합니다. 이 작업은 온보딩 과정에서 한 번만 수행합니다.

키 페어 생성

1# Generate private key

2openssl genrsa -out private_key.pem 4096

4# Extract public key

5openssl rsa -in private_key.pem -pubout -out public_key.pem

public_key.pem을 Zonos와 공유합니다. private_key.pem은 전용 시크릿 관리 서비스(AWS Secrets Manager, HashiCorp Vault 등)에 저장하고, 소스 코드나 환경 변수에는 절대 두지 마세요.

Zonos가 키를 등록하고 조직 ID(Organization ID)를 반환하며, 이 값은 모든 JWT assertion의 iss 클레임이 됩니다.

Step 2 — JWT assertion 생성

개인 키로 RS256 방식의 JWT에 서명합니다. assertion은 단 한 번의 토큰 교환에만 유효하므로, 유효 기간(60~300초)을 짧게 유지하세요.

필수 클레임

클레임↕	값↕
`iss`	Zonos 조직 ID(예: `"org_abc123"`)
`sub`	호출하는 서비스를 식별(예: `"checkout-service"`)
`aud`	정확히 `"zonos-auth"`여야 함
`exp`	Unix 타임스탬프; `iat`로부터 60~300초 후
`iat`	발급 시점의 Unix 타임스탬프
`jti`	assertion마다 고유한 UUID(재사용 공격 탐지에 사용)

JWT header에는 "alg": "RS256"과 "typ": "JWT"를 지정해야 합니다.

코드 예제

1import jwt, uuid, time

3with open("private_key.pem") as f:

4 private_key = f.read()

6now = int(time.time())

7assertion = jwt.encode(

8 {

9 "iss": "org_abc123",

10 "sub": "checkout-service",

11 "aud": "zonos-auth",

12 "iat": now,

13 "exp": now + 300,

14 "jti": str(uuid.uuid4()),

15 },

16 private_key,

17 algorithm="RS256",

18)

Step 3 — Assertion을 액세스 토큰으로 교환

서명된 JWT를 Zonos 토큰 엔드포인트로 전송해 단기 유효 Bearer 토큰을 받습니다.

엔드포인트

POST https://auth.zonos.com/oauth/token
Content-Type: application/json

application/x-www-form-urlencoded 형식도 허용됩니다.

요청 필드

필드↕	필수 여부↕	값↕
`grant_type`	예	`"urn:ietf:params:oauth:grant-type:jwt-bearer"`
`assertion`	예	서명된 JWT(compact serialization)

요청 및 응답

1{

2 "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",

3 "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

4}

응답 필드↕	설명↕
`access_token`	이후 모든 API 요청에 사용할 Bearer 토큰
`token_type`	항상 `"Bearer"`
`expires_in`	만료까지 남은 시간(초 단위, 기본값: 300)
`scope`	이 토큰에 부여된 공백으로 구분된 권한 목록

전체 코드 예제

1import requests

3response = requests.post(

4 "https://auth.zonos.com/oauth/token",

5 json={

6 : ,

7 : assertion,

8 },

9)

10data = response.json()

11access_token = data[]

12expires_in = data[]

Step 4 — 액세스 토큰으로 Zonos API 호출

토큰 수명 및 캐싱

액세스 토큰은 기본적으로 5분 후 만료됩니다. 토큰을 캐시하고 선제적으로 갱신하세요 — API를 호출할 때마다 새 토큰을 요청하지 마세요. 갱신할 때마다 새로 서명된 JWT assertion이 필요합니다.

1import time, requests

3_cache = {"access_token": None, "expires_at": 0}

5def get_access_token():

6 if time.time() < _cache["expires_at"] - 30:

7 return _cache["access_token"]

9 assertion = build_jwt_assertion()

10 data = requests.post(

11 "https://auth.zonos.com/oauth/token",

12 json={

13 "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",

14 "assertion": assertion,

15 },

16 ).json()

18 _cache["access_token"] = data["access_token"]

19 _cache["expires_at"] = time.time() + data["expires_in"]

20 return _cache["access_token"]

오류 참조

모든 오류는 OAuth 2.0 오류 응답 형식(RFC 6749 §5.2)을 따릅니다: