Terhubung ke SharePoint Online dengan PnP PowerShell: opsi masuk
By Mirko Peters · · Updated
Terhubung ke SharePoint Online dengan PnP PowerShell: daftarkan aplikasi Entra Anda sendiri, lalu pilih masuk interaktif, perangkat, sertifikat, atau identitas terkelola untuk setiap tugas.
Automatically translated with AI from the original post. Read the English original
Untuk terhubung ke SharePoint Online dengan PnP PowerShell saat ini, Anda mendaftarkan aplikasi sendiri di Microsoft Entra ID sekali saja. Kemudian Anda memanggil Connect-PnPOnline dengan URL situs dan ID klien aplikasi tersebut, serta satu metode masuk: interaktif, masuk perangkat, sertifikat, identitas terkelola, atau kredensial lama. Panduan ini ditujukan bagi admin SharePoint yang menjalankan skrip secara manual atau terjadwal. Panduan ini menjelaskan apa yang dilakukan setiap opsi, kapan menggunakannya, dan kesalahan apa yang menyebabkan koneksi gagal. Panduan ini juga menunjukkan cara memilih satu opsi per tugas agar sebuah skrip tidak memerlukan akses lebih dari yang dibutuhkan tugasnya.
Poin Penting
- Sejak 9 September 2024, Connect-PnPOnline memerlukan -ClientId, sehingga setiap admin harus lebih dulu mendaftarkan aplikasi di Microsoft Entra ID yang dapat digunakan modul untuk masuk.
- Masuk interaktif adalah pilihan tepat untuk orang yang duduk di depan keyboard, karena mendukung autentikasi multifaktor dan tidak memerlukan rahasia yang disimpan.
- Tugas tanpa pengawasan sebaiknya menggunakan masuk sertifikat atau identitas terkelola, bukan kata sandi yang diketik dan bukan rahasia klien yang disimpan di dalam skrip.
- Metode rahasia klien lama hanya berfungsi untuk cmdlet SharePoint, sehingga perintah apa pun yang memanggil Microsoft Graph akan gagal dengan metode ini.
- Daftarkan aplikasi hanya dengan izin delegasi yang Anda butuhkan, karena pendaftaran default meminta hak luas seperti AllSites.FullControl.
Memulai: mengapa setiap koneksi memerlukan aplikasi Anda sendiri
PnP PowerShell adalah modul yang dikelola komunitas. Modul ini tidak memiliki hak khusus sendiri. Setiap masuk melalui pendaftaran aplikasi di Microsoft Entra, dan aplikasi itulah yang menentukan apa yang boleh dilakukan skrip.
Referensi Connect-PnPOnline menyebutkan bahwa Anda wajib menyediakan parameter -ClientId mulai 9 September 2024. Referensi tersebut juga menyebutkan bahwa Anda harus mendaftarkan aplikasi sendiri terlebih dahulu. Anda dapat mengatur variabel lingkungan ENTRAID_APP_ID atau ENTRAID_CLIENT_ID sebagai pengganti mengetik ID setiap kali.
Perubahan ini berdampak pada skrip lama. Jika skrip dari 2023 memanggil Connect-PnPOnline -Url ... -Interactive tanpa parameter lain, skrip tersebut sekarang akan gagal atau meminta ID klien yang tidak ada. Perbaikannya tidak ada di logika skrip. Anda memerlukan aplikasi dan ID-nya.
Dua nilai lain muncul di setiap contoh:
-Urladalah alamat situs yang ingin Anda kerjakan, misalnyahttps://contoso.sharepoint.com/sites/finance. Parameter ini wajib untuk sebagian besar metode.-Tenantadalah nama penyewa, misalnyacontoso.onmicrosoft.com. Referensi mencantumkannya sebagai wajib untuk metode sertifikat dan sidik jari. Parameter ini bersifat opsional untuk masuk interaktif dan masuk perangkat.
Jika sebuah perintah memerlukan pusat admin SharePoint, Anda dapat meneruskan -TenantAdminUrl. Jika Anda tidak menyertakannya, cmdlet akan mengasumsikan bentuk https://[tenantname]-admin.sharepoint.com bila berlaku.
Langkah 1: selesaikan pendaftaran aplikasi di Microsoft Entra
Langkah memulai ini mengasumsikan modul PnP.PowerShell sudah terpasang di komputer Anda. PnP menyediakan helper untuk pengaturan awal. Halaman cmdlet untuk Register-PnPEntraIDAppForInteractiveLogin menunjukkan bentuk paling singkat:
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com
Jendela browser akan terbuka agar Anda bisa masuk, dan cmdlet tersebut membuat aplikasinya. Cmdlet ini juga menampilkan ID aplikasi yang akan Anda gunakan sebagai -ClientId. Tambahkan -DeviceLogin jika Anda tidak bisa membuka browser di komputer tersebut. Halaman tersebut menyebutkan bahwa opsi ini beralih ke alur login perangkat yang mendukung autentikasi multi-faktor.
Perhatikan izinnya. Dengan contoh dasar, aplikasi meminta izin delegasi berikut untuk persetujuan: AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All, dan TermStore.ReadWrite.All. Contoh kedua di halaman yang sama mempersempit izin ini dengan -GraphDelegatePermissions "Group.Read.All" dan -SharePointDelegatePermissions "AllSites.FullControl".
Ini penting untuk prinsip hak akses minimum. Skrip pelaporan yang hanya membaca data tidak memerlukan hak tulis pada pengguna dan grup. Tentukan apa yang dibutuhkan skrip Anda, dan minta hanya izin tersebut.
Catat setiap pendaftaran aplikasi: namanya, ID klien-nya, pemiliknya, dan izin yang dimilikinya. Tinjau pendaftaran aplikasi sekali setahun, dan hapus jika tidak ada skrip yang menggunakannya lagi.
Ada dua batasan yang perlu diketahui. Halaman referensi tidak menyebutkan peran Entra apa yang dibutuhkan untuk mendaftarkan aplikasi, jadi tanyakan kepada admin identitas Anda sebelum memulai. Parameter -SignInAudience mengatur jenis akun mana yang didukung aplikasi, jadi pastikan parameter ini sesuai dengan penyewa Anda.
Cara terhubung ke SharePoint Online dengan PnP PowerShell: lima opsi
Kelima contoh menggunakan referensi Connect-PnPOnline sebagai sumbernya. Ganti nilai yang berada dalam tanda kurung sudut.
Login interaktif
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>
Ini adalah pilihan default untuk pengguna perorangan. Referensi menyebutkan bahwa metode ini dirancang untuk mendukung autentikasi multi-faktor. Tambahkan -ForceAuthentication untuk menghapus autentikasi yang tersimpan dan masuk dengan akun yang berbeda. Gunakan opsi ini saat Anda berpindah antara penyewa uji dan penyewa produksi.
Login perangkat
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>
Browser akan terbuka dan kode akan disalin ke clipboard Anda. Pilih metode ini saat shell berjalan di sesi jarak jauh, di mana jendela interaktif tidak berfungsi dengan baik.
Login dengan sertifikat (app-only)
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>
Tidak ada orang yang masuk. Aplikasi bertindak sendiri, dengan izin aplikasi yang telah Anda berikan. Anda dapat menggunakan -CertificatePath bersama -CertificatePassword, nilai -CertificateBase64Encoded, atau -Thumbprint. Metode thumbprint memerlukan sertifikat yang tersimpan di Windows certificate store. Ini adalah pilihan standar untuk skrip tanpa pengawasan di server.
Managed identity
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity
Referensi menyebutkan bahwa metode ini hanya berfungsi di lingkungan yang mendukung managed identity, seperti Azure Functions, runbook Automation, dan Cloud Shell. Anda tidak perlu menyimpan secret sama sekali. Untuk user-assigned identity, tambahkan salah satu dari -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId, atau -UserAssignedManagedIdentityAzureResourceId. Parameter -Url bersifat opsional pada metode ini.
Kredensial dan client secret
Dua metode lama masih tersedia, dan keduanya disertai peringatan.
-Credentialsmenerima PSCredential, misalnya(Get-Credential), atau nama Generic Credential di Windows Credential Manager. Referensi mencantumkan dukungan multi-faktor untuk login interaktif dan login perangkat, tetapi tidak menyatakan hal tersebut untuk opsi ini. Anggap ini sebagai pilihan untuk akun tanpa prompt, dan uji terlebih dahulu sebelum Anda mengandalkannya.-ClientSecretbersama-ClientIdadalah metode ACS lama. Dokumentasi menyebutkan bahwa dengan metode ini, "hanya cmdlet yang terhubung ke SharePoint Online yang akan berfungsi." Cmdlet yang menggunakan Microsoft Graph akan gagal.
Hindari kedua metode tersebut untuk hal baru apa pun. Kata sandi di dalam skrip adalah risiko, dan client secret kedaluwarsa tanpa pemberitahuan.
Contoh: memilih opsi masuk untuk empat tugas
Angka dan nama di bawah ini bersifat fiktif dan hanya untuk ilustrasi.
Sebuah tim admin di perusahaan fiktif menjalankan empat tugas. Mereka menginginkan satu aplikasi per tingkat risiko, bukan satu aplikasi untuk semua hal.
- Pemeriksaan ad-hoc oleh admin di laptop. Gunakan
-Interactivedengan aplikasi yang memiliki izin delegasi yang terbatas. Admin masuk dengan MFA. Tidak ada yang disimpan. - Pembersihan satu kali di jump server jarak jauh. Gunakan
-DeviceLogin. Admin menyelesaikan proses masuk di ponsel atau laptop, lalu proses dimulai. - Inventaris harian di server Windows. Gunakan sertifikat dengan
-Thumbprint. Aplikasi memiliki izin aplikasi hanya-baca. Sertifikat berlaku selama 12 bulan, dan tim mencatat tanggal pembaruannya di kalender bersama. - Tugas mingguan di runbook Automation. Gunakan
-ManagedIdentity. Tidak ada sertifikat atau secret yang perlu dirotasi.
Hasilnya: hanya tugas 1 dan tugas 2 yang bergantung pada seseorang. Tugas 3 dan 4 berjalan tanpa ada orang yang hadir, dan keduanya tidak menyimpan kata sandi. Jika server untuk tugas 3 dicuri, tim cukup mencabut satu sertifikat. Mereka tidak perlu mengatur ulang kata sandi admin.
Apa pun opsi yang Anda pilih, simpan URL situs dalam variabel seperti $siteUrl, sehingga satu skrip PowerShell dapat melakukan iterasi pada setiap situs dalam daftar situs, mengambil data yang dibutuhkan dari setiap situs SharePoint, lalu mengunggah laporan. Uji coba menjalankan skrip pada satu koleksi situs sebelum menjalankannya di seluruh penyewa Microsoft 365 Anda.
Kesalahan umum
- Lupa menyertakan
-ClientId. Koneksi gagal atau meminta nilai tersebut. Simpan ID di variabel lingkunganENTRAID_APP_IDpada mesin yang sering Anda gunakan untuk menjalankan skrip. - Menggunakan satu aplikasi serba kuasa untuk semuanya. Pendaftaran default meminta AllSites.FullControl dan akses tulis ke pengguna dan grup. Daftarkan aplikasi kedua yang hanya-baca untuk laporan.
- Menggunakan client secret dengan cmdlet berbasis Graph. Metode lama hanya berfungsi untuk cmdlet SharePoint. Jika sebuah perintah memanggil Graph, perintah itu akan gagal, dan pesan kesalahannya bisa membingungkan.
- Menaruh kata sandi atau secret di dalam file skrip. Siapa pun yang memiliki akses baca ke file tersebut memiliki kredensialnya. Gunakan penyimpanan sertifikat atau identitas terkelola.
- Tidak menguji proses masuk di lingkungan akhir. Skrip yang berjalan di laptop dengan
-Interactivebisa gagal di server yang tidak memiliki browser. Uji dengan metode yang benar-benar akan digunakan oleh tugas tersebut. - Tetap masuk ke penyewa yang salah. Gunakan
-ForceAuthenticationsaat Anda berganti akun, dan tampilkan detail koneksi di awal setiap skrip.
Bagaimana perangkat lunak dapat membantu
Mulailah dari yang sudah Anda miliki. Modul PnP dan Microsoft Graph PowerShell SDK mencakup sebagian besar skrip admin. Azure Automation menjalankan skrip sesuai jadwal dengan identitas terkelola, dan pusat admin SharePoint menampilkan situs dan pengaturan tanpa perlu kode. Untuk secret, penyimpanan sertifikat atau key vault lebih aman daripada file skrip.
Tambahkan pelaporan di atasnya. Skrip yang berhasil terhubung hanyalah langkah pertama. Tim juga memerlukan log yang jelas tentang apa yang diubah setiap skrip dan identitas aplikasi mana yang digunakan, agar admin berikutnya dapat menelusurinya. Simpan log tersebut di tempat yang bisa dibaca semua orang, seperti daftar bersama atau sistem tiket.
Langkah berikutnya
Daftarkan satu aplikasi hari ini dengan kumpulan izin delegasi paling kecil yang dibutuhkan skrip Anda. Kemudian uji bahwa Anda dapat terhubung ke SharePoint Online dengan PnP PowerShell menggunakan -Interactive, dan catat opsi masuk mana yang akan digunakan oleh setiap tugas terjadwal Anda.