외부 로그인(SSO)

외부 로그인(SSO)을 사용하면 신뢰할 수 있는 ID 공급자(IdP)가 사용자를 Nodaro 설치에 로그인시킬 수 있습니다. 주요 연동 방식에서는 IdP가 수명이 짧은 JWT 어서션에 서명하고, Nodaro가 이를 검증하며, 브라우저는 일반 Nodaro 세션을 받습니다. 설치 운영자가 공급자를 하나 이상 구성하기 전까지 SSO는 꺼져 있습니다.

사용자가 최종적으로 들어가는 계정은 일반 계정입니다. SSO는 특별한 자격 증명을 추가하지 않습니다. 세션을 시작하는 방법일 뿐입니다.

두 가지 연동 방식

공급자 구성

서버의 EXTERNAL_SSO_PROVIDERS를 공급자의 JSON 배열로 설정하세요. 값을 직접 쓰거나 @/path/to/providers.json 형식으로 지정합니다(맨 앞의 @는 그 경로의 파일을 읽으라는 뜻입니다). 값의 형식이 잘못되면 서버가 시작할 때 멈추므로, 오타 때문에 공급자가 조용히 빠지거나 로그인이 절반만 구성되는 일은 없습니다.

[
  {
    "id": "acme-chat",
    "label": "Acme Chat",
    "kind": "assertion",
    "secret": "a-dedicated-32-character-hmac-key-for-nodaro-only",
    "audience": "nodaro",
    "claimMap": { "email": "email", "emailVerified": "email_verified", "subject": "sub" },
    "initiateUrl": "https://chat.example.com/oauth/nodaro",
    "maxLifetimeSeconds": 300
  },
  {
    "id": "keycloak",
    "label": "Acme (Keycloak)",
    "kind": "oidc",
    "supabaseProvider": "keycloak"
  }
]

• initiateUrl은 IdP에 아무것도 전달하지 않습니다. 로그인 후 사용자가 특정 페이지에 도착하게 하려면, IdP가 다시 리디렉션할 때 &next=<path>를 추가하게 하세요.
• initiateUrlByHost의 키는 시작할 때 검증됩니다. 대문자나 포트가 들어 있는 키가 있으면 서버가 멈춥니다. 이 맵은 공개되지 않으며, 계정 연결은 사용자가 어느 호스트로 들어왔는지와 관계가 없습니다.

어서션 규약

IdP가 JWT를 발급하고 브라우저를 GET /v1/sso/:provider?assertion=<jwt>로 보냅니다. Nodaro는 다음 규칙을 모두 충족할 때만 어서션을 허용합니다.

• 알고리즘. JWT는 HS256과 공급자의 secret으로 서명됩니다.
• 대상. aud가 공급자의 audience와 같습니다.
• 만료. exp가 있고 과거 시각이 아닙니다. 시계 차이는 5초까지 허용됩니다.
• 수명. exp에서 iat를 뺀 값이 maxLifetimeSeconds 이하입니다. 이 값은 Nodaro의 시계로 측정합니다. 5초 넘게 미래를 가리키는 iat는 보정되고, iat가 없으면 현재 시각으로 간주합니다.
• 일회용. jti가 있고 고유합니다. Nodaro는 어서션 자체의 유효 기간이 지날 때까지 각 jti를 기억하고, 두 번째에는 거부합니다.
• 이메일. 이메일 클레임이 있습니다.
• 인증된 이메일. 계정을 만들거나 연결하려면 인증 여부 플래그가 true여야 합니다. 플래그가 없으면 인증되지 않은 것으로 간주합니다.

어서션이 규칙을 어기면 401과 함께 invalid_signature, invalid_claims, expired, too_long_lived, missing_jti, missing_email, assertion_replayed 중 하나로 응답합니다. 이 엔드포인트는 IP 주소당 60초에 20개의 요청을 받습니다. 이를 넘으면 Retry-After 헤더와 함께 429 rate_limit_exceeded로 응답합니다.

다음은 IdP 쪽 예제로, Node.js용 jose 라이브러리로 유효한 어서션을 발급합니다.

import { SignJWT } from "jose"
import { randomUUID } from "node:crypto"

const secret = new TextEncoder().encode(process.env.NODARO_SSO_SECRET)

const assertion = await new SignJWT({ email: user.email, email_verified: true })
  .setProtectedHeader({ alg: "HS256" })
  .setSubject(user.id)
  .setAudience("nodaro")
  .setIssuedAt()
  .setExpirationTime("2m")
  .setJti(randomUUID())
  .sign(secret)

const url = new URL("https://nodaro.example.com/v1/sso/acme-chat")
url.searchParams.set("assertion", assertion)
url.searchParams.set("next", "/projects")
res.redirect(url.toString())

로그인 흐름

1. 사용자가 Nodaro 로그인 페이지에서 SSO 버튼을 클릭하면, 버튼이 어서션 없이 GET /v1/sso/:provider를 호출합니다.
2. Nodaro가 공급자의 initiateUrl로 리디렉션(302)합니다.
3. IdP가 사용자를 인증하고 브라우저를 GET /v1/sso/:provider?assertion=<jwt>로 돌려보냅니다. 선택적으로 &next=<path>를 붙입니다.
4. Nodaro가 어서션을 검증하고, 재사용을 거부하고, 계정 연결 규칙을 적용합니다.
5. Nodaro가 /sso?sso_token=<one-time token>으로 리디렉션합니다. 이 페이지가 일회용 토큰을 세션으로 교환합니다.
6. 사용자는 /projects 또는 next 경로에 도착합니다.

임베딩 호스트 같은 IdP는 3단계부터 시작할 수도 있습니다. 새 어서션을 붙여 브라우저를 교환 엔드포인트로 리디렉션하면 됩니다. 로그인 페이지 자체의 ?redirect= 파라미터는 SSO 리디렉션을 거치며 전달되지 않습니다. 전달되는 것은 IdP가 추가한 next뿐입니다.

로그인 페이지에 SSO 버튼 표시

로그인 페이지는 다음 두 조건을 모두 충족할 때 SSO 버튼을 표시합니다.

• 배포 환경의 서피스 프로필이 auth.methods에 sso를 포함하고 auth.ssoLabel을 설정합니다. ssoLabel이 없는 프로필에서는 메서드에서 sso가 빠집니다. 버튼 텍스트는 ssoLabel입니다.
• 공급자가 하나 이상 구성되어 있습니다. 페이지는 GET /v1/sso/providers로 이를 확인합니다.

서피스 프로필은 Business 에디션과 Cloud 에디션의 기능입니다. 에디션과 서피스 프로필을 참조하세요.

auth.methods에 sso만 나열한 프로필은 서버 측 제한도 켭니다. 로그인한 모든 계정은 SSO를 통해 만들어지거나 연결된 계정이어야 하며, 그 밖의 세션은 첫 API 호출에서 403 sso_required로 거부됩니다. 유일한 예외는 아래에서 설명하는 배포 환경의 결제 계정입니다. 메서드에 email을 추가하면 설치 전체에서 이 제한이 꺼집니다.

계정 연결 방식

어서션이 유효하면 Nodaro는 규칙에 따라 계정을 찾거나 만듭니다. 이 규칙은 이메일 주소가 같을 뿐인 기존 계정을 어서션이 절대 가로챌 수 없도록 설계되었습니다.

EXTERNAL_SSO_LINK_EXISTING은 기본적으로 꺼져 있으며, 이것이 계정 탈취에 안전한 설정입니다. 대소문자와 관계없이 true 또는 1만 이 설정을 켭니다. IdP의 인증된 이메일 클레임을 이미 있는 계정에 연결해도 될 만큼 신뢰할 때만 켜세요.

account_exists와 email_unverified 거부는 모든 계정에 같은 문구를 사용하므로, 로그인 양식으로 어떤 주소가 특별한 역할을 가졌는지 알아낼 수 없습니다. account_exists는 주소가 둘 이상의 계정과 일치할 때, 조회가 실패할 때, 두 로그인이 같은 계정을 동시에 만들려고 경쟁할 때도 반환됩니다.

결제 계정이 있는 배포 환경

배포 환경은 설치의 모든 사용자 비용을 내는 결제 계정 하나를 지정할 수 있습니다. 외부 지갑을 참조하세요. 이 계정은 배포 환경의 크레딧을 보유하므로 규칙이 더 엄격합니다.

• 처음으로 인증된 로그인을 할 때 연결됩니다. EXTERNAL_SSO_LINK_EXISTING 설정과는 관계없습니다. 이 계정에 대한 인증되지 않은 어서션은 email_unverified로, 다른 공급자의 어서션은 account_linked_other_provider로 거부됩니다.
• 이후의 모든 로그인을 다시 확인합니다. 이메일이 인증되어 있어야 하고, 서브젝트가 처음 계정을 연결한 서브젝트와 같아야 합니다. 그렇지 않으면 로그인이 403 account_linked_other_subject로 거부됩니다.
• 비상용 수단으로 비밀번호를 유지합니다. IdP가 이 계정을 어서트할 수 없게 되는 날을 위한 것입니다. SSO 전용 배포 환경에서는 그 양식이 /login?billing=1에 있으며, 결제 계정만 들어갈 수 있습니다.
• 설치 관리자가 차단하거나 삭제할 수 없습니다(403 payer_account_protected). 따라서 배포 환경 자체의 IdP가 나눠 준 관리자 역할로 설치를 크레딧에서 차단할 수 없습니다.

IdP에서 결제 계정의 서브젝트가 바뀌면, 그 계정의 SSO 로그인은 계속 account_linked_other_subject로 실패합니다. 이 계정은 여전히 비밀번호로 로그인할 수 있습니다.

플랫폼 운영자의 주소(PLATFORM_OPERATOR_EMAILS, 이 값이 비어 있으면 PLATFORM_OWNER_EMAIL)는 결제 계정이 있는 배포 환경에서 새로 연결되지 않습니다. 이 주소들은 account_exists로 거부되므로, 운영자 계정은 SSO 밖에 머뭅니다. 이미 연결된 운영자 계정은 계속 로그인할 수 있습니다.

OIDC와 SAML 공급자

oidc와 saml 종류는 로그인을 설치 자체의 Supabase Auth에 넘기고, Supabase Auth가 IdP의 응답을 검증합니다. 둘 다 제한이 있습니다.

• oidc: 로그인 페이지는 공급자의 id를 OAuth 공급자 이름으로 전달합니다. 따라서 id 자체가 설치의 Supabase Auth에 구성된 OAuth 공급자의 이름(예: keycloak, azure)이어야 합니다.
• saml: 로그인 페이지는 공급자의 id를 SAML 도메인으로 전달합니다. id에는 점을 넣을 수 없으므로 acme.com 같은 도메인을 표현할 수 없고, saml은 처음부터 끝까지 작동하지 않습니다.
• oidc 또는 saml 공급자로 보낸 어서션은 400 not_assertion_provider로 거부됩니다.

엔드포인트

두 엔드포인트 모두 공개되어 있으며 토큰이 필요 없습니다. /v1/sso/ 아래의 경로는 이 두 개뿐입니다.

보안 참고 사항

• 전용 시크릿을 사용하세요. secret은 Nodaro 전용 검증 키이며, IdP 자체의 세션 시크릿과 분리되어 있습니다.
• 어서션은 한 번만 작동합니다. jti 검사가 제출된 어서션을 두 번째에는 거부하고, 수명 상한이 유효 시간을 짧게 유지합니다.
• 리디렉션은 설치 안에 머뭅니다. next는 같은 설치의 상대 경로이고, /로 시작하되 //로 시작하지 않을 때만 적용됩니다. 그 밖의 경우에는 /projects에 도착합니다.
• 시크릿은 서버 밖으로 나가지 않습니다. GET /v1/sso/providers는 id, label, kind만 반환합니다. 어서션과 일회용 토큰은 요청 로그에서 제거됩니다.
• 교환에는 요청 한도가 있습니다. IP 주소별로 적용됩니다.