SnapOtter/apps/docs/ko/guide/oidc.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash

description	i18n_source_hash	i18n_provenance	i18n_output_hash
OpenID Connect로 싱글 사인온을 설정하세요. Keycloak, Authentik, Google 및 기타 OIDC 공급자에 대한 단계별 가이드입니다.	4296343b3cc5	human	cb2481dcd32f

OIDC / Single Sign-On

SnapOtter는 싱글 사인온을 위해 OpenID Connect(OIDC)를 지원합니다. 사용자는 로컬 사용자 이름/비밀번호 인증 대신(또는 이와 함께) Keycloak, Authentik, Google과 같은 외부 ID 공급자로 로그인할 수 있습니다.

::: tip 함께 참고하기 SAML SSO | SCIM Provisioning | Users, Roles & Permissions :::

Quick start

docker-compose.yml에 다음 환경 변수를 추가하세요:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

공급자의 리디렉션 URI는 항상 다음과 같습니다:

${EXTERNAL_URL}/api/auth/oidc/callback

예를 들어 EXTERNAL_URL가 https://photos.example.com라면, 공급자의 리디렉션 URI를 https://photos.example.com/api/auth/oidc/callback으로 구성하세요.

Configuration reference

Variable	Default	Description
OIDC_ENABLED	false	OIDC 로그인을 활성화합니다. 로그인 페이지에 "Sign in with SSO" 버튼이 나타납니다.
OIDC_ISSUER_URL		공급자의 issuer URL. OIDC Discovery(/.well-known/openid-configuration)를 지원해야 합니다.
OIDC_CLIENT_ID		공급자에 등록된 OAuth 클라이언트 ID.
OIDC_CLIENT_SECRET		OAuth 클라이언트 시크릿.
OIDC_SCOPES	openid profile email	요청할 스코프의 공백으로 구분된 목록.
OIDC_AUTO_CREATE_USERS	true	첫 OIDC 로그인 시 로컬 사용자 계정을 자동으로 생성합니다.
OIDC_DEFAULT_ROLE	user	자동 생성된 OIDC 사용자에게 할당되는 역할. admin, editor, user 중 하나.
OIDC_AUTO_LINK_USERS	false	이메일 주소가 일치하면 OIDC ID를 기존 로컬 사용자에 연결합니다.
OIDC_PROVIDER_NAME		로그인 버튼에 표시되는 이름(예: "Keycloak", "Google"). 비어 있으면 버튼에 "SSO"라고 표시됩니다.
OIDC_CLOCK_TOLERANCE	30	토큰 검증을 위한 시계 오차 허용 범위(초 단위).
OIDC_USERNAME_CLAIM	preferred_username	새 계정의 사용자 이름으로 사용되는 ID 토큰 클레임.
EXTERNAL_URL		SnapOtter에 접근할 수 있는 공개 URL. OIDC가 올바른 리디렉션 URI를 구성하려면 필요합니다.
COOKIE_SECRET	auto-generated	세션 쿠키 서명을 위한 시크릿. 여러 레플리카를 실행할 때 명시적으로 설정하세요.

Provider guides

Keycloak

1. 새 realm을 생성합니다(또는 기존 realm 사용).
2. Clients로 이동하여 새 클라이언트를 생성합니다:
   • Client ID: snapotter
   • Client authentication: On (confidential)
   • Authentication flow: Standard flow (Authorization Code)
3. 클라이언트의 Settings 탭에서 Valid redirect URIs를 콜백 URL로 설정합니다(예: https://photos.example.com/api/auth/oidc/callback).
4. Credentials 탭에서 Client secret을 복사합니다.
5. OIDC_ISSUER_URL을 https://keycloak.example.com/realms/your-realm로 설정합니다.

Authentik

1. 관리자 인터페이스에서 Applications > Providers로 이동하여 새 OAuth2/OpenID Provider를 생성합니다.
   • Client type: Confidential
   • Redirect URIs: 콜백 URL
   • Signing key: 기존 키를 선택하거나 새로 생성
2. Application을 생성하고 공급자에 연결합니다.
3. 공급자 설정에서 Client ID와 Client Secret을 복사합니다.
4. OIDC_ISSUER_URL을 https://authentik.example.com/application/o/snapotter/으로 설정합니다(끝의 슬래시가 중요합니다).

Google

1. Google Cloud Console로 이동합니다.
2. 프로젝트를 생성합니다(또는 기존 프로젝트 선택).
3. APIs & Services > OAuth consent screen으로 이동하여 구성합니다.
4. APIs & Services > Credentials로 이동하여 OAuth 2.0 Client ID를 생성합니다:
   • Application type: Web application
   • Authorized redirect URIs: 콜백 URL
5. Client ID와 Client secret을 복사합니다.
6. OIDC_ISSUER_URL을 https://accounts.google.com로 설정합니다.
7. OIDC_USERNAME_CLAIM을 email으로 설정합니다(Google은 preferred_username을 제공하지 않습니다).

User provisioning

Auto-create

OIDC_AUTO_CREATE_USERS가 true일 때(기본값), 누군가 OIDC로 처음 로그인하면 로컬 사용자 계정이 생성됩니다. 사용자 이름은 OIDC_USERNAME_CLAIM로 지정된 클레임에서 가져오며, 역할은 OIDC_DEFAULT_ROLE로 설정됩니다.

사용자 이름 충돌이 발생하면 숫자 접미사가 추가됩니다(예: jane이 jane_2이 됨).

Auto-link

OIDC_AUTO_LINK_USERS가 true일 때, SnapOtter는 이메일 주소가 일치하면 OIDC ID를 기존 로컬 계정에 연결합니다. 사용자 계정을 미리 생성해 두고, 데이터를 잃지 않으면서 SSO를 사용하기 시작하도록 하려는 경우에 유용합니다.

::: warning OIDC 공급자가 이메일 주소를 검증한다고 신뢰하는 경우에만 auto-link를 활성화하세요. 검증되지 않은 이메일은 누군가가 다른 사용자의 계정을 탈취하도록 허용할 수 있습니다. :::

Disabling local login

OIDC는 로컬 사용자 이름/비밀번호 로그인을 비활성화하지 않습니다. 두 방식 모두 계속 사용할 수 있습니다. OIDC 공급자에 접근할 수 없는 경우에도 관리자는 로컬 자격 증명으로 로그인할 수 있습니다.

Self-signed certificates

OIDC 공급자가 자체 서명 또는 사설 CA 인증서를 사용하는 경우, CA 번들을 컨테이너에 마운트하고 NODE_EXTRA_CA_CERTS이 이를 가리키도록 하세요:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

::: danger NODE_TLS_REJECT_UNAUTHORIZED=0을 설정하지 마세요. 이는 모든 TLS 검증을 비활성화하며 보안 위험입니다. :::

Troubleshooting

Redirect URI mismatch

가장 흔한 오류입니다. 공급자가 기대하는 것과 SnapOtter가 보내는 것 사이에서 다음 차이를 확인하세요:

• http 대 https - 스킴이 정확히 일치해야 합니다
• 끝의 슬래시 - 일부 공급자는 이에 대해 엄격합니다
• 포트 번호 - 비표준인 경우 포트를 포함하세요
• 경로 - /api/auth/oidc/callback여야 합니다

EXTERNAL_URL를 다시 확인하세요. 사용자가 브라우저에 입력하는 URL과 일치해야 합니다.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

OIDC 공급자가 Node.js가 신뢰하지 않는 인증서를 사용하고 있습니다. 위의 Self-signed certificates를 참고하세요.

Clock skew errors

서버 시계와 OIDC 공급자 시계가 동기화되지 않으면 토큰 검증이 실패할 수 있습니다. OIDC_CLOCK_TOLERANCE을 늘리세요(기본값은 30초). 더 나은 해결책은 두 머신 모두에서 NTP를 실행하는 것입니다.

"OIDC provider unreachable"

SnapOtter는 시작 시점과 로그인 중에 공급자의 discovery 문서를 가져옵니다. 다음을 확인하세요:

• Docker 컨테이너 내부에서의 DNS 확인(docker exec snapotter nslookup auth.example.com)
• 컨테이너와 공급자 사이의 방화벽 규칙
• OIDC_ISSUER_URL 값 - 브라우저뿐만 아니라 서버에서도 접근할 수 있어야 합니다

Missing claims

로그인 후 사용자 이름이나 이메일이 비어 있다면, 공급자가 기대하는 클레임을 반환하지 않을 수 있습니다. 다음을 확인하세요:

• OIDC_SCOPES에 구성된 스코프에 profile과 email이 포함되어 있는지
• ID 토큰에 OIDC_USERNAME_CLAIM로 지정된 클레임을 포함하도록 공급자가 구성되어 있는지
• 일부 공급자는 클레임을 릴리스하기 위해 명시적인 매퍼/스코프 구성이 필요합니다