OAuth2 인증을 사용하여 Nextcloud 메일 앱을 구성하는 방법

OAuth2는 많은 호스팅 메일 계정을 Nextcloud Mail에 연결하는 데 선호되는 방식입니다. 메일 제공업체에서 토큰을 발급하기 때문에 Nextcloud가 사용자의 일반 사서함 암호를 계속 사용할 필요가 없기 때문입니다. 하지만 실제로는 OAuth 동의 창이 성공적으로 닫히는지 여부만으로 좋은 설정이 판단되는 것은 아닙니다. 진정으로 중요한 결과는 Nextcloud Mail이 IMAP을 통해 폴더를 불러오고, SMTP를 통해 메일을 보내고, 사용자에게 반복적인 메시지 표시 없이 인증을 갱신하고, 첫 번째 액세스 토큰이 만료된 후에도 이러한 기능을 계속 사용할 수 있도록 하는 것입니다.

이 가이드에서는 Nextcloud Mail에서 직접 지원하는 두 가지 OAuth 통합 방식인 Google 계정과 호스팅된 Microsoft Outlook/Microsoft 365 계정에 대해 설명합니다. 2026년 10월 6일 기준으로 Nextcloud 앱 스토어에는 Mail 5.12.3 버전이 Nextcloud 32~35 버전의 안정적인 릴리스로 등록되어 있으며, 최신 관리 설명서에는 Google OAuth 및 Microsoft XOAUTH2 구성에 대한 내용이 포함되어 있습니다. 이전 버전의 Mail을 사용 중인 경우, Nextcloud 서버에서 지원하는 호환성 범위 내에서 업데이트한 후, 변경된 동작에 대한 문제 해결을 진행하십시오.

여기에 사용된 공식 참조 자료에는 Nextcloud Mail 관리 설명서 , Nextcloud Mail 앱 스토어 페이지 , Google의 IMAP, POP 및 SMTP OAuth 문서 , Microsoft의 IMAP 및 SMTP용 OAuth 문서가 포함됩니다 .

성공적인 Nextcloud 메일 OAuth2 설정이 달성해야 할 목표

공급자 설정을 변경하기 전에 원하는 결과를 정의하십시오. 정상적인 구성은 다음 모든 검사를 통과해야 합니다.

• 제공업체는 사용자를 OAuth 클라이언트에 대해 구성된 정확한 Nextcloud 리디렉션 URI로 다시 리디렉션합니다.
• Nextcloud 메일은 평소처럼 사서함 비밀번호를 다시 묻지 않고 사서함과 폴더 목록을 엽니다.
• 새 메시지가 IMAP을 통해 수신되고 수동으로 새로 고침한 받은 편지함이 인증 오류 없이 업데이트됩니다.
• Nextcloud Mail에서 보낸 테스트 메시지가 SMTP를 통해 수신되어 보낸 편지함에 나타납니다.
• 짧은 유효 기간의 액세스 토큰이 만료될 만큼 충분한 시간이 지나면, 계정은 매번 새로 로그인하는 대신 갱신 토큰을 통해 계속 작동합니다.

설정 과정에서 동의 화면 단계는 통과했지만 IMAP 및 SMTP 테스트를 통과하지 못한 경우, 설정이 완료되지 않은 것으로 간주하십시오. OAuth 인증과 메일 프로토콜 접근은 서로 관련되어 있지만 별개의 단계입니다.

1단계: 제공업체가 지원되는 OAuth 경로와 일치하는지 확인합니다.

Nextcloud Mail은 현재 Google 및 Microsoft 계정에 대한 내장 OAuth 처리 기능을 제공합니다. Google의 메일 서버는 IMAP 및 SMTP에 대해 SASL XOAUTH2를 사용하는 OAuth 2.0을 지원합니다. Microsoft는 Microsoft 365 및 Outlook.com에서 IMAP, POP 및 SMTP에 대한 OAuth2 지원을 문서화하고 있습니다. Nextcloud는 이러한 공급자가 발급한 토큰을 사용하여 메일 프로토콜에 인증합니다.

OpenID Connect 또는 OAuth2를 지원하는 모든 메일 서버를 동일한 인터페이스에 사용할 수 있다고 가정하지 마십시오. 2026년에 제출된 Nextcloud Mail 개선 요청(일반적인 타사 OAuth/OpenID 제공업체 지원)은 공식적인 구성 경로로 문서화되지 않고 개선 사항으로만 남아 있습니다. 제공업체가 Google이나 Microsoft가 아닌 경우, OAuth2를 기반으로 프로덕션 환경을 구축하기 전에 해당 제공업체의 지원 여부를 반드시 확인하십시오. 관련 프로젝트 논의는 Nextcloud Mail 일반 OAuth2 개선 요청 이슈 에서 확인할 수 있습니다 .

OAuth2를 사용하여 Gmail 구성하기

2단계: Nextcloud에서 Gmail 리디렉션 URI를 복사합니다.

Nextcloud 관리자 계정으로 로그인하고 관리 설정으로 이동한 다음 , 그룹웨어 에서 Gmail 통합을 찾으세요 . Nextcloud 관리 설명서에 따르면 이 섹션에 Google 클라이언트 ID와 클라이언트 암호를 입력해야 합니다. Google을 구성할 때는 인스턴스에 표시되는 리디렉션 URI를 사용하세요. 역방향 프록시, 웹 루트 변경 및 배포 레이아웃에 따라 외부에서 보이는 URL이 달라질 수 있으므로 예시 경로를 그대로 사용하지 마세요.

품질 검사: 리디렉션 URI는 운영 환경의 HTTPS 호스트 이름을 사용해야 하며 사용자의 브라우저에서 접근 가능해야 합니다. 사용자가 공용 호스트 이름에 접근하는데 Nextcloud에 내부 호스트 이름이 표시되는 경우, 먼저 Nextcloud/프록시 URL 구성을 수정하십시오. OAuth는 공용 URL 불일치를 자동으로 보정하지 않습니다.

3단계: Google OAuth 클라이언트 생성

Google Cloud에서 프로젝트에 대한 Google 인증 플랫폼/동의 설정을 구성하고 웹 애플리케이션 용 OAuth 클라이언트를 생성합니다. Nextcloud에서 복사한 리디렉션 URI를 승인된 리디렉션 URI로 추가합니다. Google은 인증 요청의 리디렉션 URI가 승인된 값과 정확히 일치해야 한다고 요구합니다. 스키마, 대소문자, 경로 및 마지막 슬래시가 모두 중요합니다. Google은 웹 서버 애플리케이션에 OAuth 2.0 사용 문서에서 이 동작을 설명합니다 .

https://mail.google.com/Gmail 메일 접근은 규정 준수 측면에서 중요합니다. Google은 IMAP, SMTP, POP3 사용을 포함한 광범위한 접근 범위를 제한된 범위로 분류합니다 . 앱이 내부용인지, 테스트용인지, 아니면 더 광범위한 운영 환경에서 사용될 예정인지에 따라 Google 인증 요건이 적용될 수 있습니다. 대규모 사용자 그룹을 온보딩하기 전에 Google의 제한된 범위 관련 문서 와 OAuth 앱 인증 지침을 검토하십시오.

4단계: Google 클라이언트 ID와 비밀 키를 Nextcloud에 저장합니다.

관리 설정 > 그룹웨어 > Gmail 통합 으로 돌아가서 Google 클라이언트 ID와 클라이언트 암호를 붙여넣고 저장하세요. 암호는 스크린샷, 티켓, 셸 기록 또는 공유 메모에 노출하지 마세요. 나중에 OAuth 클라이언트 암호를 변경하는 경우 Nextcloud를 즉시 업데이트하고 기존 계정에 대한 통제된 검증을 예약하세요.

5단계: Gmail 계정을 추가하고 동의를 완료하세요.

Nextcloud 메일 앱을 사용자 계정으로 열고 Gmail 계정을 추가하세요. 현재 메일 코드는 표준 Gmail IMAP/SMTP 호스트를 통해 Gmail을 인식하고, 관리자가 Google OAuth를 구성한 경우 인증 방식을 XOAUTH2로 전환합니다. Google 문서는 지원되는 SMTP 포트에서 imap.gmail.com:993SSL 및 TLS를 사용하여 IMAP으로 액세스할 수 있습니다 .smtp.gmail.com

Google 로그인을 계속 진행하고 동의 화면을 검토하세요. OAuth 앱이 사용 중인 범위 및 대상에 대해 구성 또는 검증되지 않은 경우 제공업체에서 경고를 표시하거나 액세스를 제한할 수 있습니다.

"계정이 연결되었습니다"라는 메시지에서 멈추지 마세요. 받은 편지함을 불러와서 최소 하나 이상의 메시지를 열어보고, 본인이 관리하는 다른 사서함으로 메시지를 보내고, 답장을 보내고, 왕복 과정을 확인하세요. 이러한 테스트를 통해 OAuth 리디렉션만으로는 얻을 수 없는 훨씬 더 많은 것을 확인할 수 있습니다.

OAuth2를 사용하여 Microsoft 365 또는 Outlook을 구성합니다.

6단계: Microsoft Entra에 애플리케이션을 등록합니다.

Microsoft Entra 관리 센터를 열고 앱 등록을 생성합니다. Nextcloud 가이드에서는 일반적인 예시로 조직 및 개인 Microsoft 계정을 허용하는 계정 유형을 선택하고 Nextcloud에서 복사한 웹 리디렉션 URI를 구성하도록 관리자에게 안내합니다. 조직에서 단일 테넌트를 사용하는 경우 다중 테넌트 예시를 그대로 복사하지 말고 지원되는 계정 유형과 테넌트 설정을 조직의 ID 정책에 맞게 조정해야 합니다.

Microsoft는 애플리케이션에 리디렉션 URI를 등록하도록 요구합니다. URI가 일치하지 않으면 다음과 같은 오류가 발생할 수 있습니다 AADSTS50011. Microsoft의 최신 지침은 리디렉션 URI 모범 사례 및 제한 사항을 참조하십시오 .

7단계: 클라이언트 ID를 기록하고 클라이언트 암호를 생성합니다.

애플리케이션(클라이언트) ID를 복사합니다 . 그런 다음 [인증서 및 비밀]을 열고 새 클라이언트 비밀을 생성한 후 비밀 값을 즉시 복사합니다. Microsoft는 해당 페이지를 벗어나면 비밀 값이 다시 표시되지 않는다고 명시하고 있습니다. 또한 클라이언트 비밀의 유효 기간을 24개월 이하로 제한하고 있으며, 최신 앱 등록 문서에서는 더 짧은 만료 기간을 권장합니다.

해당 만료일은 일회성 설치 설정이 아니라 운영상의 필수 요소입니다. 조직의 자격 증명 순환 프로세스에 비밀 키 만료일을 포함시키세요. 그렇지 않으면 겉보기에는 안정적으로 작동하는 Nextcloud Mail 배포 환경이라도 토큰 갱신이 더 이상 완료되지 않아 나중에 오류가 발생할 수 있습니다.

8단계: Nextcloud에 Microsoft 자격 증명을 입력합니다.

Nextcloud 관리 설정에서 그룹웨어 및 Microsoft 통합 영역을 엽니다. 클라이언트 ID와 클라이언트 암호를 입력합니다. 공식 Nextcloud 가이드에서는 common일반적인 호스팅 Outlook 구성에 테넌트 값을 사용하며, 지원되는 계정 유형을 변경하지 않은 경우 사용자 지정 테넌트 ID는 기본 가이드에 포함되지 않으므로 사용하지 말 것을 명시적으로 경고합니다.

기본 프로토콜 권한과 관련하여 Microsoft는 https://outlook.office.com/IMAP.AccessAsUser.AllIMAP 및 https://outlook.office.com/SMTP.SendSMTP를 포함한 위임 범위와 offline_access새로 고침 토큰이 필요한 경우에 대한 문서를 제공합니다. Nextcloud는 공급자 흐름을 구성하지만, 테넌트 정책 및 조건부 액세스 규칙에서 요청된 위임된 액세스가 허용되는지 확인해야 합니다.

9단계: Microsoft 계정을 연결하고 사서함을 확인합니다.

Nextcloud 메일에 Outlook 또는 Microsoft 365 주소를 추가하고 Microsoft 로그인/동의 절차를 진행하세요. Nextcloud 관리 설명서에 따르면 OAuth가 구성되면 계정 설정 중에 입력한 암호는 폐기되고 사용자에게 Microsoft 동의를 요청하는 메시지가 표시됩니다.

다시 말씀드리지만, 표시되는 동의 결과는 중간 신호일 뿐입니다. 폴더 목록이 제대로 로드되는지, 테스트 메시지를 읽을 수 있는지, 메시지를 보낼 수 있는지, 그리고 보낸 편지함에 예상한 내용이 있는지 확인하십시오.

OAuth2가 실제로 정상인지 확인하는 방법

접근 방식을 바꿔야 할 시점

리디렉션 URI, 지원되는 계정 대상, 테넌트 설정 또는 동의 구성이 배포 환경과 일치하지 않는 경우 OAuth 애플리케이션 구성을 변경하십시오 . 반복적인 재시도는 구조적 불일치를 해결하지 못합니다.

Nextcloud에서 내부 HTTP 주소 또는 기타 잘못된 공개 콜백 주소를 생성하는 경우 배포 URL/프록시 구성을 변경하십시오 . 먼저 정규 외부 URL을 수정한 다음 공급자 리디렉션 URI를 다시 생성하거나 업데이트하십시오.

조건부 액세스, 관리자 동의 정책, Google 앱 인증 또는 제한된 범위로 인해 사용자가 인증을 완료할 수 없는 경우 일반적인 OAuth 가정을 사용하는 대신 공급자별 관리를 사용하세요 . 이러한 제어는 ID 공급자가 의도적으로 적용하는 것입니다.

제공업체와 보안 정책에서 명시적으로 허용하는 경우에만 다른 인증 방법을 고려하십시오. 예를 들어, Nextcloud 메일 인터페이스에서는 Google OAuth가 구성되어 있지 않고 Google 계정에서 2단계 인증을 사용하는 경우 Google 앱 암호를 대안으로 사용할 수 있다고 안내합니다. 하지만 이는 OAuth2와 동일한 인증 방식이 아니며, 설정이 더 간편하다는 이유만으로 조직 전체에서 권장하는 대체 방법으로 간주해서는 안 됩니다.

알려진 제한 사항 및 2026년 문제 해결 시 주의 사항

Nextcloud Mail 프로젝트 이력에는 중요한 진단 주의 사항이 있습니다. 2026년 7월, 관리자들은 공급자 측 OAuth 오류가 발생했을 때 "계정 연결됨" 리디렉션 페이지가 인증 성공으로 표시되는 버그 보고서를 확인했습니다. 이 보고서는 Microsoft를 직접적으로 다루었으며 Google에서도 동일한 컨트롤러 패턴이 나타나는 것을 확인했습니다. 또한 2026년에 제출된 또 다른 보고서에서는 계정 새로 고침 토큰을 사용할 수 없게 된 후 계정을 다시 연결하는 데 어려움을 겪는 문제를 설명했습니다. 이러한 보고서는 Mail 5.10.7 버전 코드를 대상으로 작성되었으므로 모든 버전에서 영구적으로 문제가 발생하는 것은 아니지만, 리디렉션 페이지 표시를 인증 성공의 유일한 증거로 사용해서는 안 됩니다.

프로젝트의 OAuth 리디렉션 오류 처리 문제 와 OAuth 재연결 문제를 검토해 보세요 . 현재 릴리스에서 문제를 해결하는 경우, 이전 브랜치용으로 작성된 해결 방법을 적용하기 전에 먼저 설치된 메일 버전과 최신 릴리스 노트를 확인하세요.

최종 검증 체크리스트

• 설치된 메일 앱 버전이 Nextcloud 서버 버전에서 지원되는지 확인하십시오.
• Nextcloud 인스턴스에서 표시되는 리디렉션 URI를 사용하여 해당 URI를 제공업체에 정확하게 등록하십시오.
• Google의 경우 OAuth 대상, 동의 구성, 제한 범위 요구 사항 및 프로덕션/테스트 상태를 확인하세요.
• Microsoft의 경우 지원되는 계정 유형, 테넌트 선택, 클라이언트 ID, 클라이언트 암호 유효성, 조건부 액세스 또는 관리자 동의 정책을 확인하십시오.
• 설정을 광범위하게 배포하기 전에 파일럿 계정 하나를 연결하십시오.
• 받은 편지함 로딩, 메시지 읽기, 메시지 전송, 보낸 편지함 저장, 그리고 이후 토큰 갱신 기능을 테스트합니다.
• 클라이언트 비밀 키의 만료일과 소유권을 기록하여 자격 증명 교체로 인한 예기치 않은 서비스 중단을 방지하십시오.

OAuth2는 Nextcloud Mail의 인증 모델을 개선하지만, 공급자 정책, 리디렉션 URI, 애플리케이션 자격 증명 및 메일 프로토콜 액세스 관리가 완전히 사라지는 것은 아닙니다. 공급자 인증, 토큰 갱신, IMAP 검색 및 SMTP 전송을 포함한 전체 경로가 사용자에게 적용되는 정책 하에서 예측 가능하게 작동하면 구성이 프로덕션 환경에 배포할 준비가 된 것입니다.