싱글 사인온

싱글 사인온(SSO)을 사용하면 신뢰할 수 있는 외부 ID 공급자가 셀프 호스팅 Nodaro에 사용자를 로그인시킬 수 있습니다. 각 공급자를 EXTERNAL_SSO_PROVIDERS 변수에 기술하면 로그인 페이지에 SSO 버튼이 표시됩니다. 사용자가 최종적으로 들어가는 계정은 내 설치의 일반 사용자입니다. SSO는 세션을 시작하는 방법일 뿐입니다. 이 페이지는 운영자 쪽 설정을 다루며, 프로토콜은 개발자용 외부 로그인(SSO)에 있습니다.

사용할 공급자 종류

SSO는 기본적으로 꺼져 있습니다. EXTERNAL_SSO_PROVIDERS가 설정되지 않으면 로그인 페이지에 SSO 버튼이 표시되지 않고, GET /v1/sso/providers는 빈 목록을 반환하며, 모든 공급자 경로가 404 unknown_provider로 응답합니다.

공급자 구성

EXTERNAL_SSO_PROVIDERS를 JSON 배열로 설정하세요. 값을 직접 쓰거나, 파일을 읽으려면 @/path/to/providers.json 형식으로 지정합니다.

[
  {
    "id": "librechat",
    "label": "LibreChat",
    "kind": "assertion",
    "secret": "a-dedicated-32+char-hmac-key-not-the-idp-session-secret",
    "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"
  }
]

형식이 잘못된 값은 부팅을 멈춥니다. 시크릿이 들어 있는 항목의 오타 때문에 공급자가 조용히 빠져서는 안 됩니다. 그러면 SSO가 404로 실패하는 것처럼 보이거나 로그인이 절반만 구성되기 때문입니다.

Compose 스택에서는 Compose 파일이 .env에서 EXTERNAL_SSO_PROVIDERS와 EXTERNAL_SSO_LINK_EXISTING을 전달하지 않으므로, nodaro 서비스의 environment: 아래에 추가하세요. 파일을 쓰려면 컨테이너에 파일을 마운트하고 컨테이너 안의 경로를 지정하세요.

공급자 필드

공개되는 것은 id, label, kind뿐이며, GET /v1/sso/providers로만 공개됩니다. 시크릿은 서버를 벗어나지 않습니다.

Nodaro가 어서션에서 확인하는 것

assertion 공급자의 ID 서버는 JWT에 서명하고 브라우저를 GET /v1/sso/<id>?assertion=<jwt>로 보냅니다. Nodaro는 다음 조건을 모두 충족할 때만 이를 받습니다.

• HS256과 공급자의 secret으로 서명되어 있어야 합니다.
• aud 값이 공급자의 audience와 같아야 합니다.
• exp 값이 있고 5초의 허용 오차 안에서 지나지 않았어야 하며, 수명이 maxLifetimeSeconds 이내여야 합니다.
• jti 값이 있고 한 번도 쓰인 적이 없어야 합니다. 각 어서션은 한 번만 작동합니다.
• 이메일 클레임이 있어야 합니다. 계정을 만들거나 연결하려면 인증 여부 클레임이 true여야 합니다.

확인에 실패하면 401로 응답합니다. 이 경로는 IP 주소 하나당 60초에 20회까지 요청을 허용하고, 그다음에는 429로 응답합니다. 전체 계약, 오류 코드, 리디렉션 흐름은 개발자용 외부 로그인(SSO)에 있습니다.

계정 연결 방식

어서션이 통과하면 Nodaro는 일치하는 사용자를 찾거나 만듭니다. 이 규칙은 이메일 주소가 같다는 이유만으로 어서션이 기존 계정을 가로채는 일이 절대 없도록 합니다.

EXTERNAL_SSO_LINK_EXISTING의 기본값은 false이며, 계정 탈취에 안전한 설정입니다. 대소문자와 관계없이 true 또는 1만 이 기능을 활성화합니다. 공급자의 인증된 이메일 클레임을 기존 계정에 붙여도 될 만큼 신뢰할 때만 활성화하세요.

account_exists와 email_unverified는 모든 계정에 같은 문구를 쓰므로, 로그인 양식으로 어떤 주소가 있는지 알아낼 수 없습니다. 서버 로그에는 어떤 계정이 대상이었는지 기록됩니다.

로그인 버튼

공급자가 하나 이상 구성되면 로그인 페이지에 SSO 버튼이 표시됩니다.

• 공급자가 하나일 때: 버튼에 싱글 사인온 또는 서피스 프로필의 auth.ssoLabel이 표시됩니다.
• 공급자가 여러 개일 때: 서피스 프로필에 auth.ssoLabel이 없으면 각 버튼에 해당 공급자의 label이 표시됩니다.

로그인한 뒤 사용자는 /projects로 이동합니다. 공급자는 다시 리디렉션할 때 &next=<path>를 추가해 다른 페이지로 보낼 수 있습니다. Nodaro는 이 값이 같은 출처의 상대 경로이고, /로 시작하되 //로 시작하지 않을 때만 따릅니다. 그 밖의 값은 /projects로 갑니다. CORS_ORIGIN에 나열된 호스트에서는 도착 리디렉션이 상대 경로로 유지되어, 사용자가 들어온 호스트에 머뭅니다.

SSO로만 로그인 허용

Business 에디션에서는 서피스 프로필로 다른 로그인 방법을 없앨 수 있습니다.

NODARO_SURFACE_PROFILE={"auth":{"methods":["sso"],"ssoLabel":"Sign in with Acme"}}

sso만 나열한 목록은 서버 쪽 규칙도 활성화합니다. 로그인한 모든 계정이 SSO를 통해 만들어졌거나 연결되어 있어야 합니다. 다른 세션은 첫 API 호출에서 403 sso_required로 거부되므로, 로그인 서비스에 직접 등록한 계정은 설치를 쓸 수 없습니다. 목록에 email을 추가하면 이 규칙이 꺼집니다. 에디션과 서피스 프로필을 참조하세요.

보안 요약

• 공급자마다 공급자 자체의 세션 시크릿과 다른 전용 시크릿.
• 서버가 강제하는 짧은 수명의 일회용 어서션.
• 로그인 후에는 같은 출처로만 리디렉션.
• 시크릿은 서버를 벗어나지 않습니다. 어서션과 일회용 토큰은 요청 로그에서 제거됩니다.
• IP 주소별로 교환 경로에 요청 한도 적용.
• 일반 세션. 교환 후 사용자는 특별한 자격 증명이 없는 일반 사용자입니다.