OAuth2를 사용하여 Gmail 또는 Microsoft 365를 Nextcloud 메일에 연결합니다.

Gmail 또는 Microsoft 365를 OAuth2를 사용하여 Nextcloud Mail에 연결하려면 메일 제공업체에 웹 애플리케이션을 등록하고, Nextcloud Mail의 리디렉션 URI를 해당 등록 정보에 복사한 다음, 클라이언트 ID와 암호를 Nextcloud 그룹웨어 관리 설정에 저장하세요. 그런 다음 Mail 앱에서 사서함을 연결하고 제공업체의 로그인 메시지를 승인합니다. 정상적으로 작동하는 설정은 수신 메시지를 로드하고 테스트 메시지를 보낼 수 있어야 하며, 단순히 인증 성공 화면을 표시하는 것만으로는 충분하지 않습니다.

계정과 Nextcloud 설치가 이 방법에 적합한지 확인하십시오.

Nextcloud 메일은 메시지를 읽을 때 IMAP을 사용하고 보낼 때 SMTP를 사용합니다. OAuth2는 ID 공급자로부터 권한을 획득하며, XOAUTH2는 메일 클라이언트가 이러한 메일 서비스에 액세스 토큰을 제공하는 데 사용하는 메커니즘입니다. 이는 Nextcloud 로그인을 모든 메일 서버에 대한 단일 로그인으로 만들어주지는 않습니다.

Nextcloud의 최신 관리 문서에는 Gmail OAuth 및 Microsoft Outlook XOAUTH2 통합에 대한 내용이 포함되어 있습니다. Microsoft 지원은 Mail 3.0.0 버전에 추가되었으며, Mail 및 Nextcloud 릴리스에 따라 메뉴 문구가 다를 수 있습니다. 이 안내서는 2026년 10월 기준으로 최신 버전인 Nextcloud 35 Mail 관리 설명서를 기반으로 작성되었습니다.

메일 앱이 설치 및 활성화된 브라우저에서 안정적으로 열리는 HTTPS Nextcloud URL을 사용하십시오.
Nextcloud 관리자 액세스 권한이 있어야 Google Cloud 또는 Microsoft Entra에 OAuth 애플리케이션을 등록할 수 있습니다.
해당 계정이 Gmail/Google Workspace, Outlook.com 또는 Exchange Online에서 호스팅되는 Microsoft 365 사서함인지 확인하십시오.
서비스 제공업체가 조직 정책에 따라 IMAP 액세스와 전송을 위한 인증된 SMTP를 허용하는지 확인하십시오.

중요 제한 사항: OAuth2를 허용하는 사용자 지정 IMAP 공급자는 Nextcloud Mail의 Gmail/Microsoft 설정 화면에서 자동으로 지원되지 않습니다. 일반 OAuth2 공급자에 대한 Nextcloud Mail 기능 요청 문서에 이 내용이 명시되어 있습니다. 다른 공급자를 사용하는 경우, Google 또는 Microsoft 자격 증명을 입력하지 말고 사용 중인 Mail 버전과 지원되는 인증 방법을 확인하십시오.

올바른 리디렉션 URI를 사용하여 OAuth 클라이언트를 등록하세요.

Gmail 또는 Google Workspace

Nextcloud에서 관리자 계정으로 로그인한 다음, 관리 설정 → 그룹웨어로 이동하여 Gmail 통합을 찾으세요 . 인스턴스에 표시된 리디렉션 URI를 복사합니다. 다른 사용자의 설치에서 복사한 URL이 올바르다고 가정하지 마세요.
Google Cloud 콘솔을 열고 프로젝트를 선택하거나 생성합니다. Workspace 조직 또는 외부 사용자를 위해 Google 인증 플랫폼 동의/브랜딩 및 대상 설정1을 적절하게 구성합니다. 애플리케이션이 테스트 단계에 있는 경우 테스트 사용자를 추가합니다.
웹 애플리케이션 유형의 OAuth 클라이언트를 생성합니다 . 승인된 리디렉션 URI 에 Nextcloud의 정확한 URL을 입력한 다음 클라이언트 ID와 클라이언트 암호를 안전하게 저장합니다. Google은 스키마, 경로, 대소문자 및 마지막 슬래시를 포함하여 리디렉션 URI가 정확히 일치해야 합니다.
권한 범위 및 게시 요구 사항을 검토하십시오. Gmail IMAP 및 SMTP OAuth 액세스는 https://mail.google.com/Google의 사용자 데이터 및 인증 정책이 적용되는 광범위한 제한된 범위 내에서 사용됩니다. 관리자는 제안된 사용이 이러한 요구 사항을 충족하는지 여부를 판단해야 합니다.

Google은 OAuth2 웹 애플리케이션 지침 과 Gmail XOAUTH2 범위 및 프로토콜 에 대한 구체적인 내용을 통해 웹 서버 등록 흐름을 설명합니다 . 테스트 구성은 초기 유효성 검사에 유용하지만, 테스트 환경에 있는 외부 OAuth 애플리케이션은 일반적으로 Gmail 메일 접근을 요청할 때 7일 후에 만료되는 갱신 토큰을 받습니다. Google의 토큰 만료 지침을 참조하세요 . 따라서 매주 반복되는 재인증은 IMAP 암호 오류보다는 게시 상태 제한을 나타낼 수 있습니다.

Microsoft 365 또는 Outlook.com

Nextcloud의 관리 설정 → 그룹웨어 에서 Microsoft 통합을 찾고 표시된 리디렉션 URI를 복사합니다.
Microsoft Entra 관리 센터 에서 앱 등록 으로 이동하여 등록을 생성합니다. Nextcloud 표준 가이드에 설명된 계정 유형에 대해 조직 및 개인 Microsoft 계정을 모두 선택하고 웹 리디렉션 플랫폼을 사용하며 Nextcloud의 URI를 정확하게 입력합니다.
애플리케이션(클라이언트) ID를 복사합니다 . 인증서 및 비밀 키 메뉴에서 클라이언트 비밀 키를 생성하고 해당 값을 즉시 복사합니다(비밀 키 식별자는 복사하지 마십시오). 운영 일정에 해당 비밀 키의 만료일을 기록해 두십시오.
공급자의 IMAP 및 SMTP OAuth 흐름에 필요한 메일 관련 위임 권한을 사용하고, 필요한 경우 조직의 동의를 받으십시오. Microsoft는 범위와 IMAP.AccessAsUser.All새로 고침 토큰에 대한 문서를 제공합니다. 이러한 프로토콜 권한을 Microsoft Graph Mail.Read/Mail.Send 권한과 혼동하지 마십시오.SMTP.Sendoffline_access

등록 세부 정보는 Microsoft 앱 등록 설명서 및 Exchange Online의 IMAP/SMTP OAuth 지침을 참조하십시오 . Nextcloud의 일반적인 설정 설명서에서는 테넌트 필드를 비워 둡니다 common. 관리자가 관련 계정 유형 및 정책 변경 사항을 확인한 경우에만 테넌트별 값 또는 더 좁은 지원 대상 그룹을 사용해야 합니다.

Nextcloud에 자격 증명을 저장하고 사서함을 연결하세요.

관리 설정 → 그룹웨어 로 돌아갑니다 . 공급자의 클라이언트 ID와 클라이언트 암호를 해당 Gmail 통합 또는 Microsoft 통합 섹션에 붙여넣고 저장합니다. 암호를 리디렉션 URI 필드에 입력하거나 스크린샷, 티켓 또는 버전 관리 시스템에 게시하지 마십시오.
해당 메일함 사용자 계정으로 로그인하고, 메일 앱을 열어 메일 계정 추가를 선택합니다. 이메일 주소를 입력하고, 먼저 자동 계정 구성을 선택한 다음 연결을 시작합니다. Nextcloud에서 제공하는 Microsoft 인증 절차에 따라 암호 입력란이 표시될 수 있지만, 공급자 OAuth가 구성되면 입력된 자리 표시자는 무시됩니다. 불필요하게 실제 계정 암호를 입력하지 마십시오.
제공업체의 팝업 창에서 올바른 Google 또는 Microsoft 계정을 선택하고, 요청된 액세스 권한을 검토한 후, 조직의 승인을 받은 경우 동의를 부여하십시오. 브라우저 팝업을 허용하고 제공업체에서 리디렉션이 완료되면 원래 Nextcloud 탭으로 돌아가십시오.
자동 구성에서 잘못된 서버가 선택된 경우, 해당 공급자의 IMAP 및 SMTP 호스트 이름과 암호화 옵션을 수동으로 확인하십시오. OAuth 버튼은 Gmail/Microsoft에서 인식하는 엔드포인트와 연결되어 있습니다. 수동으로 입력한 관련 없는 호스트 이름은 예상되는 로그인 흐름을 활성화하지 못할 수 있습니다.

Nextcloud 메일 계정 양식에서 OAuth가 구성된 Google 엔드포인트를 인식하면 'Google로 로그인'이 표시되고 , Microsoft 엔드포인트를 인식하면 ' Microsoft로 로그인'이 표시됩니다 . 실제 Nextcloud 메일 계정 양식 소스 코드에서 이러한 조건부 레이블을 확인할 수 있습니다. 공급자별 버튼이 표시되는 것은 Nextcloud가 의도된 통합을 인식했음을 나타내는 유용한 초기 신호이지만, 인증 또는 사서함 액세스가 완료되었음을 보장하는 것은 아닙니다.

실패는 발생 단계별로 해결하십시오.

관찰된 결과	다음으로 확인해야 할 사항
Google에서 보고 `redirect_uri_mismatch`하거나 Microsoft에서 회신 URL을 거부합니다.	공급자가 등록한 웹 리디렉션과 Nextcloud Groupware에 표시된 정확한 URI를 비교하십시오. 필요한 경우 HTTPS 출처, 역방향 프록시 URL, 경로 및 마지막 슬래시를 수정하십시오.
동의 화면에서 접근이 거부되었습니다.	Google OAuth 대상, 테스트 사용자 목록, 제한된 범위 확인 또는 Microsoft 테넌트 동의 및 조건부 액세스 정책을 확인하십시오. 설정을 완료하기 위해 조직 정책을 우회하지 마십시오.
제공업체 팝업 창에는 계정이 연결되었다고 표시되지만 메일은 표시되지 않거나 비어 있습니다.	메일로 돌아가서 계정을 새로 고치고 Nextcloud 로그를 확인하여 사용자가 연결된 계정이 있는지 확인하십시오. 콜백 메시지만으로는 충분한 증거가 되지 않습니다. 2026년 7월에 보고된 Nextcloud 이슈에서는 영향을 받는 버전에서 공급자 오류가 성공 화면에 정확하게 반영되지 않는 문제를 설명하고 있습니다.
메시지는 수신되지만 Microsoft 365에서 전송이 실패합니다.	사서함 및 테넌트 인증 SMTP 설정과 메일 전송 권한을 확인하십시오. Exchange Online은 OAuth 동의 성공 여부와 관계없이 SMTP 인증을 비활성화할 수 있습니다. 사서함 수준 예외를 요청하기 전에 보안 영향을 평가하십시오.
이전에 정상적으로 연결되었던 경우에도 다시 인증이 필요합니다.	클라이언트 시크릿 만료, 사용자 동의 취소, 새로 고침 토큰 상태, 그리고 Google의 경우 OAuth 앱이 테스트 중인지 확인하세요. 만료된 시크릿은 다시 연결하기 전에 공급자 및 Nextcloud 설정에서 주기적으로 갱신하세요.

Microsoft는 Exchange Online SMTP 인증 문서 에서 사서함별 재정의를 포함한 SMTP 인증 제어에 대해 설명합니다 . 특정 사서함 하나만을 위해 메일 보안을 전반적으로 약화시키지 마십시오. 정책상 해당 프로토콜 사용이 금지된 경우, 승인된 메일 클라이언트나 조직에서 지원하는 워크플로를 사용하십시오.

우편물의 양방향 흐름을 모두 확인하십시오.

Nextcloud 메일에서 받은 편지함을 열고 새로 고침하여 최근 수신한 메시지가 예상대로 발신자, 제목 및 내용과 함께 표시되는지 확인하십시오.
본인이 관리하는 다른 사서함으로 간단한 테스트 이메일을 보내세요. 해당 사서함에서 이메일이 제대로 전송되었는지 확인한 후, Nextcloud Mail의 보낸 편지함 폴더를 확인하세요. 이렇게 하면 SMTP 권한 문제와 IMAP 동기화 문제를 구분할 수 있습니다.
로그아웃 후 다시 로그인하고 메일 앱을 다시 여세요. 실제 운영 환경에서는 액세스 토큰이 갱신된 후에 다시 확인하십시오. 즉시 성공했다고 해서 장기적인 토큰 갱신이 보장되는 것은 아닙니다.

받은 편지함 동기화가 계속 실패하는 경우, Nextcloud는 occ mail:account:export메일 계정 ID를 찾고 occ mail:account:sync -vvv ACCOUNT_ID문제 해결을 위한 구체적인 방법을 안내하는 문서를 제공합니다. 또한 그룹웨어 문제 해결 설명서 에는 계정별 IMAP/SMTP 디버그 로깅에 대한 설명과 함께 로그에 민감한 정보가 포함될 수 있다는 경고가 포함되어 있습니다. 필요한 정보만 캡처하고, 공유하기 전에 토큰과 주소를 삭제한 후, 자세한 디버깅 모드를 해제하십시오.

공급자 동의가 완료되고, 메일이 현재 메시지를 가져올 수 있으며, 발신 메일이 목적지에 도달하고, 반복적인 인증 요청 없이 연결이 계속 사용 가능한 상태가 되면 설정이 완료된 것입니다. 이러한 검사 중 하나라도 실패하면 전체 OAuth 애플리케이션을 즉시 다시 만들지 말고 해당 단계의 문제를 해결하십시오.

예약 대기열을 사용하여 Nextcloud 미리보기의 CPU 사용량 급증을 제어하세요

썸네일 작업을 제어된 백그라운드 일정으로 이동하고, 사용하지 않는 미리보기 크기를 줄이고, Nextcloud 서버에 과부하를 주지 않고 대기열을 검증하세요.

Nextcloud 데스크톱 동기화, "파일 처리 중" 문제 해결

Nextcloud 동기화를 방해하는 파일, 제외 규칙, 연결 문제 또는 클라이언트 데이터베이스 상태를 찾은 다음 업로드 및 다운로드가 안전하게 진행되는지 확인하십시오.

Nextcloud OPcache 경고를 해결하려면 적정 한도를 조정하세요.

Nextcloud 경고를 유발하는 PHP OPcache 제한을 찾아 올바른 웹 PHP 구성을 업데이트하고 안전하게 재시작한 후 결과를 확인하십시오.

Nextcloud를 CODE Docker에 연결하기: 설정 및 장단점

내장 CODE와 Docker 기반 CODE를 비교한 다음, 안전한 HTTPS 역방향 프록시를 통해 Collabora Online을 Nextcloud에 연결합니다.

Galera를 사용하여 안정적인 Nextcloud 클러스터를 구축하세요

공유 스토리지, Redis 잠금, 쿼럼 인식 MariaDB 라우팅 및 실용적인 장애 조치 점검을 통해 안정적인 Nextcloud 고가용성(HA) 배포를 계획하십시오.

직접 미디어 연결이 실패할 경우 Nextcloud Talk 통화를 연결하세요

방화벽이나 제한적인 NAT로 인해 직접 통화 매체가 차단되는 경우, Nextcloud Talk에 연결 가능한 TURN 릴레이를 구성하고 확인하십시오.

올바른 파일을 복원하여 Nextcloud 무결성 경고를 해결하세요

잘못된 파일 보고서를 사용하여 변경되었거나 누락되었거나 추가된 Nextcloud 코드를 식별하고, 신뢰할 수 있는 파일을 안전하게 복원하고, 결과를 확인할 수 있습니다.