ownCloud Infinite Scale에서 Keycloak을 IDP로 구성하는 방법

이 가이드는 OAuth 2.0 기반의 ID 계층인 OpenID Connect(OIDC)를 사용하여 ownCloud Infinite Scale(oCIS)과 Keycloak을 연결합니다. Keycloak은 사용자를 인증하고, oCIS는 서명된 ID를 신뢰하여 Keycloak에서 발급한 액세스 정보에 접근합니다. 브라우저 기반 로그인은 HTTPS 리디렉션을 사용하며, oCIS는 Keycloak의 검색 및 서명 키 엔드포인트에도 접근해야 합니다.

2026년 10월 6일 기준, ownCloud의 최신 관리 문서에서는 이러한 설정을 Infinite Scale 9.0에서 설명하고 있습니다. 공식 Keycloak 배포 예제는 유용한 시작점이지만, 해당 예제의 Compose 파일과 영역 내보내기 파일은 변경될 수 있습니다. 호환되는 이미지 버전을 고정하고 배포하는 파일을 검토한 후, 버전 관리가 되지 않은 예제를 그대로 복사하지 마십시오.

OIDC를 구성하기 전에 필요한 사항

oCIS의 공개 HTTPS 주소(예: https://cloud.example.com)와 Keycloak의 공개 HTTPS 주소(예: )를 준비하십시오 https://sso.example.com. 두 주소 모두 사용자의 브라우저에서 올바르게 확인되어야 합니다. 또한 oCIS 서버는 Keycloak의 OIDC 메타데이터 및 공개 서명 키에 접근할 수 있어야 합니다. 리버스 프록시가 두 서비스 중 하나를 대신하는 경우, 해당 서비스의 공개 호스트 이름과 전달 헤더를 일관되게 구성하십시오.

• 정상적으로 작동하는 ownCloud Infinite Scale 배포 환경과 해당 환경 또는 Compose 구성에 대한 관리자 액세스 권한이 필요합니다.
• 정상적으로 작동하는 Keycloak 영역 및 관리자 액세스 권한입니다. 영역은 사용자, 클라이언트, 역할 및 ID 설정을 위한 Keycloak 네임스페이스입니다.
• 브라우저와 Keycloak의 TLS 인증서를 검증하는 서버에서 신뢰하는 TLS 인증서입니다. 실제 운영 환경에서는 인증서 검증 기능을 비활성화해서는 안 됩니다.
• 계정 매칭에 대한 결정: 기존 oCIS 사용자를 안정적인 ID 클레임에 연결할지, 아니면 필요한 쓰기 권한이 있는 사용자 백엔드를 사용하여 최초 로그인 계정 프로비저닝을 활성화할지 여부.

1. 정확한 Keycloak 발급자를 찾으세요

Keycloak에서 OIDC 발급자는 일반적으로 관리 콘솔 URL이나 검색 문서 URL이 아닌 영역 URL입니다. 예를 들어 team, 'realm'이라는 이름의 영역의 경우 다음과 같은 형식일 수 있습니다 https://sso.example.com/realms/team. 이전 설치 또는 경로 접두사가 있는 배포 환경에서는 값이 다를 수 있으므로, 기억에 의존하여 값을 생성하지 마십시오. 해당 영역의 검색 문서를 열고 https://sso.example.com/realms/team/.well-known/openid-configuration속성 값을 issuer정확하게 복사하십시오.

Keycloak에 접속할 수 있는 서버에서 다음 명령어를 사용하여 문서를 검사할 수 있습니다.

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

반환된 발급자가 oCIS에서 구성할 스키마, 호스트, 경로 및 영역 이름과 동일한지 확인하십시오. OpenID Connect는 발급자 ID를 정확하게 검증합니다. 리버스 프록시 호스트 이름이 일치하지 않거나 슬래시가 하나 더 있으면 로그인이 실패할 수 있습니다.

2. ownCloud Web용 OIDC 클라이언트를 등록합니다.

클라이언트는 Keycloak이 로그인 요청을 허용하는 서비스를 결정하는 데 사용하는 애플리케이션 등록 정보입니다. oCIS에 사용되는 영역에 OpenID Connect 클라이언트를 생성하거나 수정하세요. 클라이언트 ID는 `<ClientId>` web또는 사용자 지정 값을 사용하고, 이 값이 oCIS의 값과 일치하는지 확인하세요 WEB_OIDC_CLIENT_ID. ownCloud 공식 예제에서는 web기본값으로 `<ClientId>`를 사용합니다.

브라우저 기반 클라이언트의 경우, 표준 인증 코드 흐름과 공식 예제 영역과 일치하는 공개 클라이언트 구성을 사용하십시오. 배포에 필요한 정확한 HTTPS 리디렉션 및 로그아웃 후 리디렉션 패턴을 입력하십시오. https://cloud.example.com/*모든 호스트에 걸쳐 광범위한 와일드카드를 사용하는 것보다 특정 호스트 이름 패턴을 사용하는 것이 감사가 더 쉽습니다. 배포에 필요한 웹 출처만 추가하십시오. 공개 브라우저 클라이언트에 대한 클라이언트 암호를 생성한 다음 프런트엔드 구성에 포함시키지 마십시오.

3. 주장 내용과 범위를 확인하십시오.

OIDC 클레임은 토큰에 포함되거나 사용자 정보 엔드포인트에서 반환되는 ID 속성입니다. 최소한 사용자 이름 클레임은 신중하게 선택해야 합니다. ownCloud 프록시는 기본적으로 preferred_username사용자를 확인하는 데 사용되며, Keycloak 예제는 웹 클라이언트를 표준 프로필 및 이메일 범위로 구성합니다. 사용하는 클레임이 ownrealm에서 실제로 반환되는지 확인하십시오. 클레임 가용성은 클라이언트 범위 및 프로토콜 매퍼에 따라 달라집니다.

기존 계정의 경우, 구성된 클레임은 해당 안정적인 ownCloud 사용자 속성에 매핑되어야 합니다. 사용자 이름이나 이메일이 변경된 경우, 이를 영구 식별자로 사용하면 계정 일치 문제가 발생할 수 있습니다. 클레임은 subID 공급자별로 고유하고 안정적이지만, 기존 사용자 이름과 일치하지 않을 수 있습니다. 모든 사용자에게 액세스를 허용하기 전에 관리자가 아닌 계정으로 계정 매핑을 테스트하십시오.

4. 무한 스케일을 키클록에 적용

oCIS 배포를 위해 환경 변수에 다음 값을 설정하십시오. 예시에서는 HTTPS와 Keycloak 영역(주소는 `/keycloak.realm`)을 가정합니다 /realms/team. 실제 URL을 사용하십시오. 이 YAML 형식 블록은 예시일 뿐이며, Docker Compose, Kubernetes, systemd 및 기타 배포 방법에서는 환경 변수를 다르게 표현합니다.

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUER외부 ID 공급자를 선택합니다. PROXY_OIDC_REWRITE_WELLKNOWN=true프록시가 OpenID Connect 검색 엔드포인트를 구성된 발급자로 다시 작성하도록 합니다. ownCloud는 데스크톱 및 모바일 클라이언트가 공급자를 검색하는 데 이 기능이 필요하다고 문서화했습니다. WEB_OIDC_CLIENT_IDKeycloak 클라이언트와 일치해야 합니다. 제외는 idpownCloud의 Keycloak 예제를 따르므로 내장 공급자가 활성 로그인 공급자로 시작되지 않습니다.

oCIS에서 첫 로그인 성공 시 계정을 생성하도록 하려면, PROXY_AUTOPROVISION_ACCOUNTS=true쓰기 권한이 있는 사용자 백엔드를 사용하여 그래프 서비스를 설정하고 구성하십시오. 사용자 이름 속성은 동일한 클레임으로 설정해야 하며, ownCloud 문서에서 PROXY_USER_OIDC_CLAIM이 흐름에 대한 자세한 내용을 확인할 수 있습니다. 자동 프로비저닝은 선택 사항이며 인증과 별도로 테스트해야 합니다. 수신되는 클레임이 고유하고 의도한 대로 매핑되지 않은 경우에는 자동 프로비저닝을 활성화하지 마십시오.PROXY_AUTOPROVISION_CLAIM_USERNAMEPROXY_USER_CS3_CLAIM=username

5. 콘텐츠 보안 정책에서 ID 공급자를 허용합니다.

Infinite Scale은 콘텐츠 보안 정책(CSP)을 사용하여 웹 클라이언트가 연결할 수 있는 외부 출처를 제어합니다. ownCloud 문서에 따르면 Keycloak과 같은 외부 ID 공급자는 적절한 CSP 정의가 필요합니다. 로그인 버튼이 표시되지만 브라우저에서 요청을 차단하는 경우 브라우저 콘솔에서 CSP 오류를 확인하십시오. 정책을 구성하여 PROXY_CSP_CONFIG_FILE_LOCATION배포에 필요한 Keycloak 출처 및 지시문만 허용하십시오. 파일을 변경한 후 프록시 또는 배포를 다시 시작하십시오. 모든 출처를 허용하여 연결 문제를 해결하지 마십시오.

6. 전체 흐름을 재시작하고 확인합니다.

환경 변경 사항을 적용하고 기존에 관리하던 방법을 사용하여 oCIS 배포를 다시 시작하십시오. 모든 경우에 적용되는 재시작 명령은 없습니다. Compose 프로젝트, Kubernetes 워크로드 및 systemd 서비스는 각각 다른 제어 방식을 사용합니다. 그런 다음 각 단계를 확인하십시오.

1. Keycloak 검색 URL을 열고 issuer, authorization_endpoint, token_endpoint, 가 포함된 JSON이 반환되는지 확인하십시오 jwks_uri.
2. ownCloud 웹 URL을 개인 정보 보호 모드 브라우저 창에서 엽니다. 브라우저가 예상한 Keycloak 영역으로 리디렉션되는지 확인합니다.
3. 테스트 계정으로 로그인하고 브라우저가 리디렉션 루프 없이 동일한 ownCloud 호스트 이름으로 돌아오는지 확인하십시오.
4. 의도한 사용자(새로 생성된 중복 사용자가 아님)가 Infinite Scale에 나타나고 예상되는 리소스에만 액세스할 수 있는지 확인하십시오.
5. 로그아웃을 테스트한 다음 두 번째 계정으로 반복합니다. 데스크톱 또는 모바일 클라이언트가 테스트 대상에 포함되는 경우, 각 클라이언트의 검색 및 로그인 기능을 별도로 테스트합니다.

흔히 발생하는 오류와 그 의미

생산 체크리스트

• Pin은 플로팅 태그에 의존하는 대신 ownCloud 및 Keycloak 버전을 테스트했습니다 latest.
• 공용 서비스에는 HTTPS를 사용하고 인증서 검증을 유지하세요. ownCloud는 안전하지 않은 TLS 재정의 기능이 프로덕션 환경에 적합하지 않다고 명시하고 있습니다.
• Keycloak 관리자 자격 증명을 보호하고, Keycloak 데이터베이스 및 영역 구성을 백업하고, Keycloak 관리자 액세스를 제한합니다.
• 리디렉션 URI와 웹 출처는 ownCloud 호스트 이름으로만 제한하십시오.
• 선택한 식별자 클레임과 사용자 이름, 영역 이름, 발급자 URL 또는 클라이언트 ID를 변경할 경우 발생하는 결과를 문서화하십시오.
• 운영 인스턴스를 전환하기 전에 복구 액세스를 테스트하고 이전 구성으로의 계획된 롤백을 유지하십시오.

공식 참고 자료

• ownCloud Infinite Scale 9.0 프록시 서비스 구성
• ownCloud Keycloak 배포 예시 가이드
• 공식 ownCloud ocis_keycloak 배포 파일
• Keycloak 26.8 서버 관리 가이드
• ownCloud 무한 확장 보안 측면