PnP PowerShell로 SharePoint Online에 연결하기: 로그인 옵션
By Mirko Peters · · Updated
PnP PowerShell로 SharePoint Online에 연결하기: 자체 Entra 앱을 등록한 뒤, 작업마다 대화형, 장치, 인증서 또는 관리 ID 로그인 중에서 선택하십시오.
Automatically translated with AI from the original post. Read the English original
오늘날 PnP PowerShell로 SharePoint Online에 연결하려면 먼저 Microsoft Entra ID에 자체 앱을 한 번 등록해야 합니다. 그런 다음 사이트 URL과 해당 앱의 클라이언트 ID, 그리고 대화형, 장치 로그인, 인증서, 관리 ID, 레거시 자격 증명 중 하나의 로그인 방법을 지정하여 Connect-PnPOnline을 호출합니다. 이 가이드는 스크립트를 직접 실행하거나 예약 실행하는 SharePoint 관리자를 위한 것입니다. 각 옵션의 동작, 사용 시기, 연결을 실패하게 만드는 실수를 설명합니다. 또한 스크립트가 작업에 필요한 것 이상의 권한을 갖지 않도록 작업마다 옵션을 하나씩 선택하는 방법도 보여 줍니다.
핵심 포인트
- 2024년 9월 9일부터 Connect-PnPOnline에는 -ClientId가 필요하므로, 모든 관리자는 먼저 모듈이 로그인에 사용할 수 있는 앱을 Microsoft Entra ID에 등록해야 합니다.
- 대화형 로그인은 키보드 앞에 있는 사람이 사용하기에 적합합니다. 다중 인증을 지원하고 저장된 비밀이 필요 없기 때문입니다.
- 무인 작업에는 입력한 암호나 스크립트에 저장된 클라이언트 비밀이 아니라, 인증서 로그인 또는 관리 ID를 사용해야 합니다.
- 레거시 클라이언트 비밀 방식은 SharePoint cmdlet에서만 작동하므로, Microsoft Graph를 호출하는 명령은 이 방식으로 실패합니다.
- 기본 등록은 AllSites.FullControl 같은 광범위한 권한을 요청하므로, 앱은 필요한 위임 권한만 가지도록 등록하십시오.
시작하기: 연결마다 자체 앱이 필요한 이유
PnP PowerShell은 커뮤니티에서 관리하는 모듈입니다. 모듈 자체에 특별한 권한이 있는 것은 아닙니다. 모든 로그인은 Microsoft Entra의 앱 등록을 거치며, 스크립트가 무엇을 할 수 있는지는 그 앱이 결정합니다.
Connect-PnPOnline 참조 문서에 따르면 2024년 9월 9일부터 -ClientId 매개 변수를 반드시 지정해야 합니다. 또한 먼저 자체 앱을 등록해야 한다고 명시되어 있습니다. 매번 ID를 입력하는 대신 ENTRAID_APP_ID 또는 ENTRAID_CLIENT_ID 환경 변수를 설정할 수도 있습니다.
이 변경으로 기존 스크립트에 영향이 생겼습니다. 2023년에 작성된 스크립트가 Connect-PnPOnline -Url ... -Interactive만 호출하는 경우, 이제는 실패하거나 누락된 클라이언트 ID를 묻는 메시지가 표시됩니다. 해결책은 스크립트의 로직에 있는 것이 아닙니다. 앱과 ID가 필요합니다.
모든 예제에 등장하는 값이 두 가지 더 있습니다.
-Url은 작업할 사이트의 주소이며, 예를 들어https://contoso.sharepoint.com/sites/finance와 같습니다. 대부분의 방식에서 필수입니다.-Tenant는 테넌트 이름이며, 예를 들어contoso.onmicrosoft.com과 같습니다. 참조 문서에서는 인증서 및 지문(thumbprint) 방식에 필수라고 설명합니다. 대화형 로그인과 장치 로그인에서는 선택 사항입니다.
명령에 SharePoint 관리 센터가 필요한 경우 -TenantAdminUrl을 전달할 수 있습니다. 생략하면 해당되는 경우 cmdlet이 https://[tenantname]-admin.sharepoint.com 형식을 사용하는 것으로 간주합니다.
1단계: Microsoft Entra에서 앱 등록 완료하기
이 시작 단계는 PnP.PowerShell 모듈이 이미 컴퓨터에 설치되어 있다고 가정합니다. PnP에는 최초 설정을 돕는 도우미 cmdlet이 있습니다. Register-PnPEntraIDAppForInteractiveLogin cmdlet 페이지에 가장 짧은 형식이 나와 있습니다.
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com
로그인할 수 있도록 브라우저 창이 열리고, cmdlet이 앱을 만듭니다. 또한 -ClientId로 사용할 애플리케이션 ID를 출력합니다. 컴퓨터에서 브라우저를 열 수 없다면 -DeviceLogin을 추가하십시오. 해당 페이지에 따르면 이 옵션은 다단계 인증을 지원하는 디바이스 로그인 흐름으로 전환됩니다.
권한을 주의해서 확인하십시오. 기본 예제에서 앱은 동의를 요청하는 위임된 권한으로 AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All, TermStore.ReadWrite.All을 요청합니다. 같은 페이지의 두 번째 예제는 -GraphDelegatePermissions "Group.Read.All"와 -SharePointDelegatePermissions "AllSites.FullControl"를 사용해 이 범위를 좁힙니다.
이는 최소 권한 원칙에서 중요합니다. 읽기만 하는 보고서 스크립트에는 사용자와 그룹에 대한 쓰기 권한이 필요하지 않습니다. 스크립트에 무엇이 필요한지 결정하고, 그것만 요청하십시오.
앱 등록마다 이름, 클라이언트 ID, 소유자, 보유한 권한을 기록해 두십시오. 앱 등록은 1년에 한 번 검토하고, 어떤 스크립트도 더 이상 사용하지 않으면 삭제하십시오.
알아두어야 할 두 가지 제한 사항이 있습니다. 참조 페이지에는 앱을 등록하는 데 필요한 Entra 역할이 명시되어 있지 않으므로, 시작하기 전에 ID 관리자에게 확인하십시오. 그리고 -SignInAudience 매개 변수는 앱이 지원하는 계정 유형을 제어하므로, 이 값이 테넌트와 일치하는지 확인하십시오.
PnP PowerShell로 SharePoint Online에 연결하는 방법: 다섯 가지 옵션
다섯 가지 예제는 모두 Connect-PnPOnline 참조를 출처로 합니다. 꺾쇠 괄호 안의 값은 실제 값으로 바꾸십시오.
대화형 로그인
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>
사용자가 직접 로그인할 때의 기본 선택입니다. 참조에 따르면 이 방식은 다단계 인증을 지원하도록 설계되었습니다. 저장된 인증 정보를 지우고 다른 계정으로 로그인하려면 -ForceAuthentication을 추가하십시오. 테스트 테넌트와 운영 테넌트를 오갈 때 사용합니다.
디바이스 로그인
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>
브라우저가 열리고 코드가 클립보드에 복사됩니다. 대화형 창이 잘 동작하지 않는 원격 세션에서 셸을 실행할 때 이 방식을 선택하십시오.
인증서 로그인(앱 전용)
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>
사용자가 로그인하지 않습니다. 앱이 부여받은 애플리케이션 권한으로 스스로 동작합니다. -CertificatePath와 -CertificatePassword, -CertificateBase64Encoded 값, 또는 -Thumbprint를 전달할 수 있습니다. 지문(Thumbprint) 방식은 인증서가 Windows 인증서 저장소에 있어야 합니다. 서버에서 무인 스크립트를 실행할 때 표준적으로 选择하는 방식입니다.
관리 ID
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity
참조에 따르면 이 방식은 Azure Functions, Automation 런북, Cloud Shell처럼 관리 ID를 지원하는 환경에서만 동작합니다. 비밀 정보를 전혀 저장하지 않습니다. 사용자 할당 ID를 사용하려면 -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId, -UserAssignedManagedIdentityAzureResourceId 중 하나를 추가하십시오. 이 방식에서는 -Url 매개 변수가 선택 사항입니다.
자격 증명과 클라이언트 비밀
오래된 방식 두 가지가 남아 있으며, 둘 다 주의가 필요합니다.
-Credentials은 PSCredential(예:(Get-Credential)) 또는 Windows 자격 증명 관리자에 저장된 일반 자격 증명의 이름을 받습니다. 참조에는 대화형 및 디바이스 로그인에 대한 다단계 인증 지원이 나열되어 있지만, 이 방식에 대해서는 그렇게 명시하지 않습니다. 프롬프트 없이 동작해야 하는 계정을 위한 옵션으로만 다루고, 의존하기 전에 반드시 테스트하십시오.-ClientSecret을-ClientId와 함께 사용하는 방식은 레거시 ACS 방식입니다. 참조 문서에는 이 방식을 사용하면 "only cmdlets that are connecting to SharePoint Online will work."라고 나와 있습니다. 즉, Microsoft Graph를 사용하는 cmdlet은 실패합니다.
새로 작업하는 경우에는 두 방식 모두 피하십시오. 스크립트에 비밀번호를 넣으면 위험하며, 클라이언트 암호는 예고 없이 만료됩니다.
예: 작업 네 개에 대한 로그인 옵션 선택
아래의 숫자와 이름은 설명을 위해 임의로 만든 것입니다.
가상의 회사에 있는 관리자 팀이 작업 네 개를 운영합니다. 이 팀은 모든 작업에 앱 하나를 쓰기보다 위험 수준별로 앱을 하나씩 두려고 합니다.
- 노트북에서 관리자가 수행하는 임시 점검. 범위가 좁은 위임 권한을 가진 앱과 함께
-Interactive를 사용합니다. 관리자는 MFA로 로그인합니다. 저장되는 항목은 없습니다. - 원격 점프 서버에서 실행하는 일회성 정리 작업.
-DeviceLogin을 사용합니다. 관리자가 휴대폰이나 노트북에서 로그인을 완료하면 작업이 시작됩니다. - Windows 서버에서 매일 밤 실행하는 인벤토리 작업.
-Thumbprint와 함께 인증서를 사용합니다. 앱에는 읽기 전용 애플리케이션 권한이 있습니다. 인증서의 유효 기간은 12개월이며, 팀은 갱신 날짜를 공유 캘린더에 기록합니다. - Automation 런북에서 실행하는 주간 작업.
-ManagedIdentity를 사용합니다. 교체해야 할 인증서나 암호가 없습니다.
결과적으로 작업 1과 작업 2만 사람에게 의존합니다. 작업 3과 4는 사람이 없어도 실행되며, 둘 다 비밀번호를 저장하지 않습니다. 작업 3의 서버가 도난당하더라도 팀은 인증서 하나만 취소하면 됩니다. 관리자 비밀번호를 재설정할 필요는 없습니다.
어떤 옵션을 선택하든 사이트 URL은 $siteUrl 같은 변수에 보관하십시오. 그러면 하나의 PowerShell 스크립트로 사이트 목록의 각 사이트를 순회하면서 각 SharePoint 사이트에서 필요한 데이터를 가져와 보고서를 업로드할 수 있습니다. Microsoft 365 테넌트 전체에 스크립트를 실행하기 전에 사이트 컬렉션 하나에서 먼저 테스트하십시오.
흔한 실수
-ClientId를 빠뜨리는 경우. 연결이 실패하거나 ID를 입력하라는 메시지가 나타납니다. 스크립트를 자주 실행하는 컴퓨터에서는ENTRAID_APP_ID환경 변수에 ID를 저장해 두십시오.- 모든 작업에 권한이 막강한 앱 하나를 사용하는 경우. 기본 등록은 AllSites.FullControl 권한과 사용자 및 그룹에 대한 쓰기 권한을 요청합니다. 보고서용으로 읽기 전용 앱을 별도로 등록하십시오.
- Graph 기반 cmdlet에 클라이언트 암호를 사용하는 경우. 레거시 방식은 SharePoint cmdlet에서만 동작합니다. 명령이 Graph를 호출하면 실패하며, 오류 메시지가 혼란스러울 수 있습니다.
- 스크립트 파일에 비밀번호나 암호를 넣는 경우. 파일을 읽을 수 있는 사람은 누구나 자격 증명을 알게 됩니다. 인증서 저장소나 관리 ID를 사용하십시오.
- 최종 환경에서 로그인을 테스트하지 않는 경우. 노트북에서
-Interactive로 잘 동작하는 스크립트도 브라우저가 없는 서버에서는 실패할 수 있습니다. 작업이 실제로 사용할 방식으로 테스트하십시오. - 잘못된 테넌트에 계속 로그인된 상태로 두는 경우. 계정을 바꿀 때는
-ForceAuthentication을 사용하고, 각 스크립트를 시작할 때 연결 정보를 출력하십시오.
소프트웨어가 도움이 되는 방식
이미 갖추고 있는 것부터 시작하십시오. PnP 모듈과 Microsoft Graph PowerShell SDK로 대부분의 관리 스크립트를 작성할 수 있습니다. Azure Automation은 관리 ID로 예약된 시간에 스크립트를 실행하며, SharePoint 관리 센터에서는 코드 없이 사이트와 설정을 확인할 수 있습니다. 비밀 정보는 스크립트 파일보다 인증서 저장소나 키 자격 증명 모음에 보관하는 것이 더 안전합니다.
그 위에 보고 기능을 더하십시오. 연결이 올바르게 되는 스크립트는 첫 단계일 뿐입니다. 팀에는 각 스크립트가 무엇을 변경했고 어떤 앱 ID를 사용했는지 명확히 기록한 로그도 필요합니다. 그래야 다음 관리자가 흐름을 따라갈 수 있습니다. 공유 목록이나 티켓 시스템처럼 모든 구성원이 읽을 수 있는 곳에 이 로그를 보관하십시오.
다음 단계
오늘 스크립트에 필요한 최소한의 위임 권한만 가진 앱을 하나 등록하십시오. 그다음 -Interactive를 사용해 PnP PowerShell로 SharePoint Online에 연결할 수 있는지 테스트하고, 예약된 각 작업이 어떤 로그인 옵션을 사용할지 적어 두십시오.