OAuth 인증

이 페이지는 Immich에서 OAuth를 사용하는 방법에 대한 세부 정보를 제공합니다.

팁

app.immich:///oauth-callback를 유효한 리디렉션 URI로 설정할 수 없나요? 대체 솔루션은 모바일 리디렉션 URI에서 확인하세요.

개요

Immich는 OAuth2 위에 구축된 ID 계층인 OpenID Connect (OIDC)를 통해 3자 인증을 지원합니다. OIDC는 다음과 같은 대부분의 ID 제공자가 지원합니다:

사전 준비 사항

Immich에서 OAuth를 활성화하기 전에, 3자 인증 서버에 새 클라이언트 애플리케이션을 구성해야 합니다. 이 설정의 구체적인 내용은 제공자마다 다르지만 일반적인 접근 방식은 동일해야 합니다.

새 (클라이언트) 애플리케이션 생성
1. 제공자 유형은 OpenID Connect 또는 OAuth2 여야 합니다.
2. 클라이언트 유형은 Confidential 여야 합니다.
3. 애플리케이션 유형은 Web 여야 합니다.
4. Grant 유형은 Authorization Code 여야 합니다.
리디렉션 URI/출처 구성

**로그인 리디렉션 URI(Sign-in redirect URIs)**는 다음을 포함해야 합니다:
- app.immich:///oauth-callback - OAuth를 통해 모바일 앱에서 로그인할 때 사용
- http://DOMAIN:PORT/auth/login - 웹 클라이언트에서 OAuth로 로그인할 때 사용
- http://DOMAIN:PORT/user-settings - 웹 클라이언트에서 수동으로 OAuth 연결할 때 사용
리디렉션 URI에는 Immich에 접근하는 데 사용할 모든 도메인이 포함되어야 합니다. 다음은 몇 가지 예입니다:

모바일
- app.immich:///oauth-callback (iOS 및 Android 모바일 앱이 제대로 작동하려면 반드시 포함해야 합니다)
로컬호스트
- http://localhost:2283/auth/login
- http://localhost:2283/user-settings
로컬 IP
- http://192.168.0.200:2283/auth/login
- http://192.168.0.200:2283/user-settings
호스트 이름
- https://immich.example.com/auth/login
- https://immich.example.com/user-settings

OAuth 활성화

새 OAuth 클라이언트 애플리케이션이 구성되면, Immich는 웹에서 관리 페이지(관리 -> 설정)를 사용하여 구성할 수 있습니다.

설정	유형	기본값	설명
활성화	boolean	false	OAuth 활성화/비활성화
발급자 URL	URL	(필수)	필수. 클라이언트에 대한 셀프 디스커버리 URL (이전 단계에서 제공됨)
클라이언트 ID	string	(필수)	필수. 클라이언트 ID (이전 단계에서 제공됨)
클라이언트 비밀키	string	(필수)	필수. 클라이언트 비밀키 (이전 단계에서 제공됨)
범위	string	openid email profile	요청과 함께 보낼 전체 범위 목록 (공백으로 구분)
서명 알고리즘	string	RS256	ID 토큰을 서명하는 데 사용되는 알고리즘 (예: RS256, HS256)
저장 라벨 클레임	string	preferred_username	사용자의 저장소 라벨의 클레임 맵핑¹
역할 클레임	string	immich_role	사용자의 역할에 대한 클레임 맵핑. ("user" 또는 "admin" 반환 필요)¹
저장소 할당량 클레임	string	immich_quota	사용자의 저장소에 대한 클레임 맵핑¹
기본 저장소 할당량 (GiB)	number	0	저장소 할당량 클레임 없는 사용자의 기본 할당량 (무제한 할당량은 0 입력)
버튼 텍스트	string	OAuth로 로그인하기	웹의 OAuth 버튼 텍스트
자동 등록	boolean	true	true일 경우 사용자가 처음 로그인할 때 자동으로 등록
자동 시작	boolean	false	true일 경우 로그인 페이지를 건너뛰고 자동으로 OAuth 로그인 프로세스를 시작함
모바일 리디렉션 URI 재정의	URL	(비어 있음)	Http(s) 대체 모바일 리디렉션 URI

클레임 옵션 [1]

클레임은 사용자 생성 시에만 사용되며 이후에는 동기화되지 않습니다.

정보

발급자 URL은 다음과 같으며 유효한 JSON 문서를 반환해야 합니다.

https://accounts.google.com/.well-known/openid-configuration
http://localhost:9000/application/o/immich/.well-known/openid-configuration

URL의 .well-known/openid-configuration 부분은 선택 사항이며 디스커버리 동안 자동으로 추가됩니다.

자동 시작

자동 시작이 활성화되면 로그인 페이지가 자동으로 OAuth 인증 URL로 리디렉션되어 OAuth로 로그인합니다. 다시 로그인 화면에 액세스하려면 브라우저의 뒤로 가기 버튼을 사용하거나 /auth/login?autoLaunch=0로 직접 이동하십시오. 자동 시작은 요청별로 /auth/login?authLaunch=1로 이동하여 활성화할 수 있으며, 이는 Nextcloud에서 외부 사이트 앱 및 oidc 앱을 사용하여 Immich와 직접 상호작용하는 경우에 유용할 수 있습니다.

모바일 리디렉션 URI

모바일 앱의 리디렉션 URI는 app.immich:///oauth-callback이며, 이는 사용자 정의 스키마입니다. 이 사용자 정의 스키마가 OAuth 제공자에게 유효한 리디렉션 URI가 아닌 경우, 다음 단계를 통해 이를 해결할 수 있습니다:

요청을 app.immich:///oauth-callback로 전달하는 http(s) 엔드포인트를 구성합니다.
새로운 엔드포인트를 제공자에 대해 유효한 리디렉션 URI로 허용 리스트에 추가합니다.
OAuth 설정에서 새로운 엔드포인트를 모바일 리디렉션 URI 재정의로 지정합니다.

이 단계가 완료되면 사용자 정의 스키마 리디렉션 URI 없이도 모바일 앱에서 OAuth를 사용할 수 있어야 합니다.

정보

Immich에는 이미 app.immich:///oauth-callback로 요청을 전달하도록 구성된 경로 (/api/oauth/mobile-redirect)가 있으며 1단계에 사용할 수 있습니다.

예제 구성

Authentik 예제

다음은 Authentik에 대해 OAuth가 구성된 예제입니다:

인증된 리디렉션 URI 구성 (Authentik OAuth2/OpenID 제공자)

Immich 시스템 설정에서 OAuth 구성

설정	값
발급자 URL	`https://example.immich.app/application/o/immich/.well-known/openid-configuration`
클라이언트 ID	AFCj2rM1f4rps*************lCLEum6hH9...
클라이언트 비밀키	0v89FXkQOWO**************mprbvXD549HH6s1iw...
범위	openid email profile
서명 알고리즘	RS256
저장 라벨 클레임	preferred_username
저장소 할당량 클레임	immich_quota
기본 저장소 할당량 (GiB)	0 (무제한 할당량은 0 입력)
버튼 텍스트	Authentik로 로그인 (선택 사항)
자동 등록	활성화됨 (선택 사항)
자동 시작	활성화됨 (선택 사항)
모바일 리디렉션 URI 재정의	비활성
모바일 리디렉션 URI

Google 예제

다음은 Google에 대해 OAuth가 구성된 예제입니다:

인증된 리디렉션 URI 구성 (Google 콘솔)

Immich 시스템 설정에서 OAuth 구성

설정	값
발급자 URL	`https://accounts.google.com`
클라이언트 ID	7***************vuls.apps.googleusercontent.com
클라이언트 시크릿	G******************OO
범위	openid email profile
서명 알고리즘	RS256
저장 레이블 클레임	preferred_username
저장 쿼터 클레임	immich_quota
기본 저장 쿼터 (GiB)	0 (0은 무제한 쿼터)
버튼 텍스트	Google로 로그인 (선택 사항)
자동 등록	활성화 (선택 사항)
자동 실행	활성화
모바일 리다이렉션 URI 대체	활성화 (필수)
모바일 리다이렉션 URI	`https://example.immich.app/api/oauth/mobile-redirect`

개요​

사전 준비 사항​

OAuth 활성화​

자동 시작​

모바일 리디렉션 URI​

예제 구성​

Authentik 예제​

Google 예제​

개요