LinkOStar

인증

LinkOStar는 4가지 자격증명을 받습니다. 각각 다른 경로에 적용되며, 한 요청이 여러 자격을 동시에 들고 와도 우선순위에 따라 하나만 활성화됩니다.

한눈에 정리

자격증명헤더적용 경로발급
X-API-KeyX-API-Key: <key>/tenant/**Supplier 운영팀 발급. Supplier 시크릿.
sdx-oauth JWTAuthorization: Bearer <jwt>/tenant/** · /app/** · /platform/**sdx-oauth 로그인 흐름
Hub BearerAuthorization: Bearer <token>/v1/hubs/** (claim 제외)POST /v1/hubs/claim 응답
X-Tenant-UUIDX-Tenant-UUID: <uuid>/tenant/** 보조supplier_uuid 와 동일 (1:1)

1. X-API-Key (Supplier ↔ BFF)

Supplier BFF가 LinkOStar를 호출할 때 표준. End-user 브라우저에 노출하지 마세요— 키가 새면 다른 supplier 데이터까지 모두 보입니다.

curl https://api.linkostar.sandevaux.com/tenant/hubs \
  -H "X-API-Key: ${LINKOSTAR_API_KEY}" \
  -H "X-Tenant-UUID: ${LINKOSTAR_TENANT_UUID}"

2. sdx-oauth JWT (Operator / End-user)

LinkOStar 운영자 콘솔과 LinkOStar 모바일 앱은 sdx-oauth 로 사용자 인증을 받고 JWT를 받습니다. 이 JWT를 그대로 LinkOStar에 보냅니다.

  • JWT는 사용자가 누구인지를 알려줍니다.
  • X-Tenant-UUID는 어떤 tenant scope로 동작할지 알려줍니다.
  • 두 헤더를 같이 보내야 /tenant/** 가 정상 동작합니다.

sdx-oauth 발급/갱신 흐름은 sdx 측 문서 참조 (PKCE + refresh_token).

3. Hub Bearer (Hub-Agent ↔ LinkOStar)

Pi에서 동작하는 hub-agent가 /v1/hubs/{uuid}/telemetry 같은 endpoint를 호출할 때 씁니다. 발급 흐름:

  1. Pi 부팅 → boot config 의 claim_code로 POST /v1/hubs/claim
  2. 응답으로 accessToken + refreshToken + hubUuid 수령
  3. 이후 모든 /v1/hubs/** 요청에 Authorization: Bearer <accessToken>
  4. 토큰 만료 5분 전 자동 갱신: POST /v1/hubs/refresh (body에 refreshToken, 헤더에 현재 accessToken)

이 토큰은 1개 hub 1개입니다. 같은 hub_uuid로 refresh 하면 이전 accessToken은 즉시 invalidate됩니다 (Pi와 다른 곳에서 동시에 들고 있으면 한 쪽은 401).

4. X-Tenant-UUID

/tenant/** 경로에서 어떤 tenant scope로 동작할지 결정합니다. JWT 사용자가 여러 tenant에 속할 수 있기 때문에 필요한 disambiguation 헤더입니다. X-API-Key 흐름에서도 동일하게 필요합니다.

헤더가 누락되거나 사용자가 그 tenant에 access 권한이 없으면 자격 박탈 → /tenant/** 요청은 403/401 응답.

우선순위 / 필터 순서

같은 요청에 여러 자격이 동시에 들어오면 다음 순서로 한 번만 활성화됩니다.

  1. X-API-Key 필터 — /tenant/**에서만 동작
  2. JWT 필터 — sdx-oauth JWT, /tenant · /app · /platform
  3. Hub Token 필터 — /v1/**에서만 동작

안전 가이드

  • X-API-Key를 secret manager(1Password, AWS Secrets Manager 등)에 보관. Git에 절대 commit 금지.
  • BFF 로그에 자격 헤더 redaction 처리.
  • Hub token은 /var/lib/agent/state.json (Pi 측)에서 root 만 읽음.
  • 의심되는 키 유출 시 LinkOStar 운영팀에 즉시 알림 — 키 재발급.