使用 Microsoft Entra ID 在 SharePoint Server 中設定 OIDC 驗證
適用於:Subscription Edition SharePoint in Microsoft 365
必要條件
當您使用 Microsoft Entra ID 設定 OpenID Connect (OIDC) 時,您需要下列資源:
SharePoint Server 訂閱版本 (SPSE) 伺服器陣列
Microsoft Entra M365 租使用者的全域管理員角色
本文使用下列範例值 Microsoft Entra OIDC 設定:
值 | 連結 |
---|---|
SharePoint 網站統一資源定位器 (URL) | https://spsites.contoso.local/ |
OIDC 網站 URL | https://sts.windows.net/<tenantid>/ |
Microsoft Entra OIDC 驗證端點 | https://login.microsoftonline.com/<tenantid>/oauth2/authorize |
Microsoft Entra OIDC RegisteredIssuerName URL | https://sts.windows.net/<tenantid>/ |
Microsoft Entra OIDC SignoutURL | https://login.microsoftonline.com/<tenantid>/oauth2/logout |
身分識別宣告類型 | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
Windows 網站集合管理員 | contoso\yvand |
Email 同盟網站集合管理員的值 | yvand@contoso.local |
重要事項
Microsoft 建議您使用權限最少的角色。 使用較低許可權的帳戶有助於改善組織的安全性。 全域系統管理員是高度特殊權限角色,應僅在無法使用現有角色的緊急案例下使用。
步驟 1:設定識別提供者
執行下列步驟來設定具有 Microsoft Entra ID 的 OIDC:
流覽至 Entra ID 系統管理入口網站,並使用具有全域管理員角色的帳戶登入。
在 [應用程式] 底下,選取 [應用程式註冊]。
選 取 [新增註冊]。
移至 [ 註冊應用程式] 頁面
https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
。在 [ 重新導向 URI] 區 段下,選擇 [Web] 作為 [平臺],然後輸入您的 SharePoint Server Web 應用程式 URL,例如:
https://spsites.contoso.local/
,然後選取 [ 註冊]。將 [目錄] 儲存 (租使用者) 標識 符值,因為後續步驟中會使用租用戶標識符。 另請將應用程式 (用戶端) 標識符儲存在 SharePoint 安裝程式中,做為 DefaultClientIdentifier 。
註冊應用程式之後,請移至 [ 驗證] 索引 標籤,選取 [ 標識符令牌] 複選框,然後選取 [ 儲存]。
移至 [ API 許可權] 索引標籤 ,然後選取 [新增許可權]。 依 序選擇 [Microsoft Graph] 和 [ 委派的許可權]。 選取 [新增 電子郵件 和 配置檔 ] 許可權,然後選取 [ 新增許可權]。
移至 [ 令牌組態] 索引 標籤,然後選取 [ 新增選擇性宣告]。 針對每個令牌輸入 (標識碼、Access、SAML) 、新增 電子郵件和 upn 宣告 。
此外,在 [ 令牌組態] 索引 標籤上,選取 [ 新增群組宣告]。 安全性 群組 是最常見的,但您選取的群組類型取決於您想要用來授與 SharePoint Web 應用程式存取權的群組類型。 如需詳細資訊,請參閱設定群組選擇性宣告和使用 Microsoft Entra ID 設定應用程式的群組宣告。
移至 [ 指令清單] 索引 標籤,然後在 [Microsoft圖形應用程式指令清單] 下,將 redirectUris 的 值從
https://spsites.contoso.local/
https://spsites.contoso.local/*
變更為 。 然後選取 [儲存]。 針對 redirectUriSettings 下所列的 “uri” 值執行相同的動作,然後再次選取 [ 儲存] 。
步驟 2:變更 SharePoint 伺服器陣列屬性
在此步驟中,您必須根據 SharePoint Server 伺服器陣列的版本來修改 SharePoint Server 伺服器陣列屬性。
- 如需設定 SharePoint Server 訂閱版本 版本 24H1 之 SharePoint 伺服器陣列屬性的詳細資訊,請參閱設定 SPSE 24H1 版或更新版本。
- 如需為 24H1 之前的 SharePoint Server 訂閱版本 版本設定 SharePoint 伺服器陣列屬性的詳細資訊,請參閱在 24H1 版之前設定 SPSE。
使用舊版功能喜好設定 SharePoint Server 訂閱版本 版本 24H1 或更新版本
從 2024 年 3 月 (SharePoint Server 訂閱版本 版 24H1 開始) ,如果 SharePoint 伺服器陣列設定為 [早期發行] 功能喜好設定,您可以使用 SharePoint 憑證管理來管理 Nonce Cookie 憑證,以設定 SharePoint Server 伺服器數組屬性。 nonce Cookie 憑證是基礎結構的一部分,以確保 OIDC 驗證令牌的安全。 執行下列 PowerShell 腳本來設定:
重要事項
若要使用此腳本,SharePoint 伺服器陣列必須設定為 [早期發行],如上所述。 如果不是,腳本將會完成,但不會發生錯誤,但會呼叫 $farm。UpdateNonceCertificate () 不會執行任何動作。 如果您不想要設定伺服器陣列以進行早期發行,則必須改用 [在版本 24H1 之前設定 SPSE] 步驟。
注意事項
以伺服器陣組管理員身分啟動SharePoint管理命令介面,以執行下列腳本。 請仔細閱讀下列 PowerShell 腳本中所述的指示。 您必須在特定位置輸入您自己的環境特定值。
# Set up farm properties to work with OIDC
# Create the Nonce certificate
$cert = New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider' -Subject "CN=SharePoint Cookie Cert"
# Import certificate to Certificate Management
$certPath = "<path and file name to save the exported cert. ex: c:\certs\nonce.pfx>"
$certPassword = ConvertTo-SecureString -String "<password>" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath $certPath -Password $certPassword
$nonceCert = Import-SPCertificate -Path $certPath -Password $certPassword -Store "EndEntity" -Exportable:$true
# Update farm property
$farm = Get-SPFarm
$farm.UpdateNonceCertificate($nonceCert,$true)
在版本 24H1 之前設定 SharePoint Server 訂閱版本
在 2024 年 3 月 24H1 () 更新之前,必須手動管理 nonce Cookie 憑證。 這包括在伺服陣列中的每個伺服器上手動安裝它,以及設定私鑰的許可權。 下列 PowerShell 腳本可用來完成此作業。
注意事項
以伺服器陣組管理員身分啟動SharePoint管理命令介面,以執行下列腳本。 請仔細閱讀下列 PowerShell 腳本中所述的指示。 您必須在特定位置輸入您自己的環境特定值。
# Set up farm properties to work with OIDC
$cert = New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider' -Subject "CN=SharePoint Cookie Cert"
$rsaCert = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$fileName = $rsaCert.key.UniqueName
# If you have multiple SharePoint servers in the farm, you need to export the certificate by Export-PfxCertificate and import the certificate to all other SharePoint servers in the farm by Import-PfxCertificate.
# After the certificate is successfully imported to SharePoint Server, we will need to grant access permission to the certificate's private key.
$path = "$env:ALLUSERSPROFILE\Microsoft\Crypto\RSA\MachineKeys\$fileName"
$permissions = Get-Acl -Path $path
# Replace the <web application pool account> with the real application pool account of your web application
$access_rule = New-Object System.Security.AccessControl.FileSystemAccessRule(<Web application pool account>, 'Read', 'None', 'None', 'Allow')
$permissions.AddAccessRule($access_rule)
Set-Acl -Path $path -AclObject $permissions
# Then update farm properties
$farm = Get-SPFarm
$farm.Properties['SP-NonceCookieCertificateThumbprint']=$cert.Thumbprint
$farm.Properties['SP-NonceCookieHMACSecretKey']='seed'
$farm.Update()
重要事項
具有私鑰的 Nonce Cookie 憑證必須安裝在伺服器數位中的所有 SharePoint 伺服器上。 此外,必須將私鑰的許可權授與每部伺服器上的 Web 應用程式集區服務帳戶。 若無法完成此步驟,將會導致 OIDC 驗證失敗。 建議使用上述 PowerShell 範例來設定私鑰檔案的許可權,以確保正確完成。
步驟 3:設定 SharePoint 以信任識別提供者
在此步驟中,您會建立 ,SPTrustedTokenIssuer
以儲存 SharePoint 需要信任 Microsoft Entra OIDC 作為 OIDC 提供者的組態。
您可以使用下列其中一種方式,將 SharePoint 設定為信任識別提供者:
- 使用元數據端點,將 SharePoint 設定為信任 Microsoft Entra ID 為 OIDC 提供者。
- 藉由使用元數據端點,您需要的數個參數會自動從元數據端點擷取。
- 將 SharePoint 設定為以手動方式信任 Microsoft Entra ID 為 OIDC 提供者。
注意事項
請遵循手動設定步驟或元數據端點步驟,但不要同時執行兩者。
建議使用元數據端點,因為它可簡化程式。
使用元數據端點將 SharePoint 設定為信任 Microsoft Entra ID
SharePoint Server 訂閱版本 現在支援在建立受信任的身分識別令牌簽發者時使用OIDC元數據探索功能。
在 Microsoft Entra ID 中,OIDC 探索端點有兩個版本:
- V1.0:
https://login.microsoftonline.com/<TenantID>/.well-known/openid-configuration
- V2.0:
https://login.microsoftonline.com/<TenantID>/v2.0/.well-known/openid-configuration
重要事項
目前,SharePoint Server 在用來建立受信任的身分識別令牌簽發者時,僅支援 v1.0 元數據端點。 下列範例 PowerShell 腳本使用 V1.0 端點。
當您使用 OIDC 識別提供者所提供的元數據端點時,會直接從 OIDC 提供者元數據端點擷取部分設定,包括:
- 認證
- 發行者
- 授權端點
- SignoutURL
這可以簡化 OIDC 令牌簽發者的設定。
在下列 PowerShell 範例中,我們可以使用來自 Microsoft Entra ID 的元數據端點,將 SharePoint 設定為信任 Microsoft Entra OIDC。
注意事項
請仔細閱讀下列 PowerShell 腳本中所述的指示。 您必須在特定位置輸入您自己的環境特定值。 例如,將tenantid>取代<為您自己的目錄 (租使用者) 識別碼。
# Define claim types
# In this example, we're using Email Address as the Identity claim.
$emailClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "Email" -SameAsIncoming
# Set the AAD metadata endpoint URL. Please replace <TenantID> with the value saved in step #3 in the Entra ID setup section
$metadataendpointurl = "https://login.microsoftonline.com/<TenantID>/.well-known/openid-configuration"
# Please replace <Application (Client) ID> with the value saved in step #3 in the Entra ID setup section
$clientIdentifier = "<Application (Client)ID>"
# Create a new SPTrustedIdentityTokenIssuer in SharePoint
New-SPTrustedIdentityTokenIssuer -Name "contoso.local" -Description "contoso.local" -ClaimsMappings $emailClaimMap -IdentifierClaim $emailClaimMap.InputClaimType -DefaultClientIdentifier $clientIdentifier -MetadataEndPoint $metadataendpointurl -Scope "openid profile"
參數 | 描述 |
---|---|
名稱 | 為新的令牌簽發者提供名稱。 |
描述 | 提供新令牌簽發者的描述。 |
ImportTrustCertificate | 用來從 OIDC 識別碼驗證 id_token 的憑證。 |
ClaimsMappings |
SPClaimTypeMapping 對象,用來識別中id_token 哪個宣告在 SharePoint 中視為標識碼。 |
IdentifierClaim | 指定標識碼的類型。 |
DefaultClientIdentifier | 指定 client_id SharePoint 伺服器的 ,由 OIDC 識別提供者指派。 這會針對 中的 id_token aud 宣告進行驗證。 |
MetadataEndPoint | 指定來自 OIDC 識別提供者的已知元數據端點,可用來擷取最新的憑證、簽發者、授權端點和註銷端點。 |
將 SharePoint 設定為以手動方式信任 Microsoft Entra ID 為 OIDC 提供者
手動設定時,必須指定數個額外的參數。 您可以從 OIDC 探索端點擷取值。
在 Microsoft Entra ID 中,有兩個版本的 OIDC 驗證端點。 因此,OIDC 探索端點分別有兩個版本:
- V1.0:
https://login.microsoftonline.com/<TenantID>/.well-known/openid-configuration
- V2.0:
https://login.microsoftonline.com/<TenantID>/v2.0/.well-known/openid-configuration
將 TenantID 取代為儲存在步驟 1:安裝識別提供者中的目錄 (租使用者) 標識符,並透過瀏覽器連線到端點。 然後,儲存下列資訊:
值 | 連結 |
---|---|
authorization_endpoint | https://login.microsoftonline.com/<tenantid>/oauth2/authorize |
end_session_endpoint | https://login.microsoftonline.com/<tenantid>/oauth2/logout |
發行 | https://sts.windows.net/<tenantid>/ |
jwks_uri | https://login.microsoftonline.com/common/discovery/keys |
開啟 jwks_uri (https://login.microsoftonline.com/common/discovery/keys
) 並儲存所有 x5c 憑證 字串,以供稍後在 SharePoint 安裝程式中使用。
以伺服器陣列管理員身分啟動 SharePoint 管理命令介面,並在輸入您在上面取得的值之後,執行下列腳本來建立受信任的身分識別令牌簽發者:
注意事項
請仔細閱讀下列 PowerShell 腳本中所述的指示。 您必須在特定位置輸入您自己的環境特定值。 例如,將tenantid>取代<為您自己的目錄 (租使用者) 識別碼。
# Define claim types
# In this example, we're using Email Address as the identity claim.
$emailClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "Email" -SameAsIncoming
# Public key of the AAD OIDC signing certificate. Please replace <x5c cert string> with the encoded cert string which you get from x5c certificate string of the keys of jwks_uri from Step #1
$encodedCertStrs = @()
$encodedCertStrs += <x5c cert string 1>
$encodedCertStrs += <x5c cert string 2>
...
$certificates = @()
foreach ($encodedCertStr in $encodedCertStrs) {
$certificates += New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 @(,[System.Convert]::FromBase64String($encodedCertStr))
}
# Set the AAD OIDC URL where users are redirected to authenticate. Please replace <tenantid> accordingly
$authendpointurl = "https://login.microsoftonline.com/<tenantid>/oauth2/authorize"
$registeredissuernameurl = "https://sts.windows.net/<tenantid>/"
$signouturl = "https://login.microsoftonline.com/<tenantid>/oauth2/logout"
# Please replace <Application (Client) ID> with the value saved in step #3 in AAD setup section
$clientIdentifier = "<Application (Client)ID>"
# Create a new SPTrustedIdentityTokenIssuer in SharePoint
New-SPTrustedIdentityTokenIssuer -Name "contoso.local" -Description "contoso.local" -ImportTrustCertificate $certificates -ClaimsMappings emailClaimMap -IdentifierClaim $emailClaimMap.InputClaimType -RegisteredIssuerName $registeredissuernameurl -AuthorizationEndPointUri $authendpointurl -SignOutUrl $signouturl -DefaultClientIdentifier $clientIdentifier -Scope "openid profile"
在這裡, New-SPTrustedIdentityTokenIssuer
PowerShell Cmdlet 會使用下列參數來擴充以支援 OIDC:
參數 | 描述 |
---|---|
名稱 | 為新的令牌簽發者提供名稱。 |
描述 | 提供新令牌簽發者的描述。 |
ImportTrustCertificate | 匯入 X509 憑證清單,用來從 OIDC 識別碼進行 id_token 驗證。 如果 OIDC 識別提供者 (IDP) 使用多個憑證來數字簽署 id_token ,請匯入這些憑證,並藉由比對使用這些憑證所產生的數位簽名來驗證 id_token SharePoint。 |
ClaimsMappings |
SPClaimTypeMapping 對象,用來識別中id_token 哪個宣告在 SharePoint 中視為標識碼。 |
IdentifierClaim | 指定標識碼的類型。 |
RegisteredIssuerName | 指定發出的簽發者標識 id_token 碼。 用來驗證 id_token 。 |
AuthorizationEndPointUrl | 指定 OIDC 識別提供者的授權端點。 |
SignoutUrl | 指定 OIDC 識別提供者的註銷端點。 |
DefaultClientIdentifier | 指定 client_id SharePoint 伺服器的 ,由 OIDC 識別提供者指派。 這會針對 中的 id_token aud 宣告進行驗證。 |
ResponseTypesSupported | 指定此令牌簽發者接受的IDP回應類型。 它可以接受兩個字串: id_token 和 code id_token 。 如果未提供此參數,則會使用 code id_token 作為預設值。 |
步驟 4:設定 SharePoint Web 應用程式
在此步驟中,您會使用SPTrustedIdentityTokenIssuer
在上一個步驟中建立的 ,將 SharePoint 中的 Web 應用程式設定為與 Microsoft Entra OIDC 同盟。
重要事項
- SharePoint Web 應用程式的預設區域必須啟用 Windows 驗證。 這是搜尋編目程式的必要專案。
- 將使用 Microsoft Entra OIDC 同盟的 SharePoint URL 必須使用超文本傳輸通訊協定安全 (HTTPS) 來設定。
您可以透過下列方式來完成此設定:
- 建立新的 Web 應用程式,並在預設區域中同時使用 Windows 和 Microsoft Entra OIDC 驗證。
- 擴充現有的 Web 應用程式,以在新區域上設定 Microsoft Entra OIDC 驗證。
若 要建立新的 Web 應用程式,請執行下列動作:
啟動 SharePoint 管理指令介面並執行下列腳本來建立新的
SPAuthenticationProvider
:# This script creates a trusted authentication provider for OIDC $sptrust = Get-SPTrustedIdentityTokenIssuer "contoso.local" $trustedAp = New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $sptrust
遵循 在 SharePoint Server 中建立 Web 應用程式 ,以建立新的 Web 應用程式,以啟用 HTTPS/安全套接字層 (SSL) contoso.local 上名為 SharePoint - OIDC。
開啟 SharePoint 管理中心網站。
選取您建立的 Web 應用程式,選擇功能區中的 [驗證提供者],按兩下 [預設] 區域的連結,然後挑選 contoso.local 作為 [信任的識別提供者]。
在 SharePoint 管理中心網站中,流覽至 [系統設定>] [設定替代存取對>應] [替代存取對應] [備用存取對應集合]。
使用新的 Web 應用程式篩選顯示器,並確認您看到下列資訊:
若要 擴充現有的 Web 應用程式 ,並將其設定為使用 「contoso.local」 信任的提供者,請執行下列動作:
啟動 SharePoint 管理命令介面並執行 PowerShell 以擴充 Web 應用程式。 下列範例會將 Web 應用程式延伸至內部網路區域,並將區域設定為使用 「Contoso.local」 信任的提供者進行驗證。
注意事項
若要讓此作業能夠運作,您必須將名為 『SharePoint OIDC Site』 的有效憑證匯入伺服器數位。 如需詳細資訊,請參閱 SSL 憑證管理作業 。
# Get the trusted provider $sptrust = Get-SPTrustedIdentityTokenIssuer "Contoso.local" $ap = New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $sptrust # Get the web app $wa = Get-SPWebApplication http://spsites # Extend the web app to the "Intranet" zone using trusted provider (OIDC) auth and a SharePoint managed certificate called "SharePoint OIDC Site" New-SPWebApplicationExtension -Identity $wa -Name "spsites" -port 443 -HostHeader 'spsites.contoso.local'-AuthenticationProvider $ap -SecureSocketsLayer -UseServerNameIndication -Certificate 'SharePoint OIDC Site' -Zone 'Intranet' -URL 'https://spsites.contoso.local'
在 SharePoint 管理中心網站中,流覽至 [系統設定>] [設定替代存取對>應] [替代存取對應] [備用存取對應集合]。
使用已擴充的 Web 應用程式篩選顯示器,並確認您看到下列資訊:
步驟 5:確定已使用 SSL 憑證設定 Web 應用程式
由於 OIDC 1.0 驗證只能與 HTTPS 通訊協定搭配使用,因此必須在對應的 Web 應用程式上設定憑證。 如果尚未設定,請執行下列步驟來設定憑證:
產生月臺憑證:
注意事項
如果您已經產生憑證,您可以略過此步驟。
開啟 SharePoint PowerShell 控制台。
執行下列腳本來產生自我簽署憑證,並將其新增至 SharePoint 伺服器陣列:
New-SPCertificate -FriendlyName "Contoso SharePoint (2021)" -KeySize 2048 -CommonName spsites.contoso.local -AlternativeNames extranet.contoso.local, onedrive.contoso.local -OrganizationalUnit "Contoso IT Department" -Organization "Contoso" -Locality "Redmond" -State "Washington" -Country "US" -Exportable -HashAlgorithm SHA256 -Path "\\server\fileshare\Contoso SharePoint 2021 Certificate Signing Request.txt" Move-SPCertificate -Identity "Contoso SharePoint (2021)" -NewStore EndEntity
重要事項
自我簽署憑證僅適用於測試用途。 在生產環境中,強烈建議您改用證書頒發機構單位所簽發的憑證。
設定憑證:
您可以使用下列 PowerShell Cmdlet 將憑證指派給 Web 應用程式:
Set-SPWebApplication -Identity https://spsites.contoso.local -Zone Default -SecureSocketsLayer -Certificate "Contoso SharePoint (2021)"
步驟 6:建立網站集合
在此步驟中,您會建立具有兩個系統管理員的小組網站集合:一位是 Windows 系統管理員,另一位是同盟 (Microsoft Entra ID) 系統管理員。
開啟 SharePoint 管理中心網站。
流覽至 [ 應用程式管理>] [建立網站集合>] [建立網站集合]。
輸入標題、URL,然後選取範本小組網站。
在 [主要網站集合管理員] 區段中,選取 (書籍) 圖示,以開啟 [人員 選擇器] 對話框。
在 [人員 選擇器] 對話框中,輸入 Windows 系統管理員帳戶,例如 yvand。
選取 [ 組織],以篩選左側的清單。 以下是範例輸出:
移至帳戶,然後選取 [ 確定]。
在 [次要網站集合管理員] 區段中,選取書籍圖示以開啟 [人員 選擇器] 對話框。
在 [人員 選擇器] 對話框中,輸入 Microsoft Entra 系統管理員帳戶的確切電子郵件值,例如 yvand@contoso.local。
選取 contoso.local 來篩選左側的清單。 以下是範例輸出:
移至帳戶,然後選取 [確定] 以關閉 [人員 選擇器] 對話框。
再次選取 [確定 ] 以建立網站集合。
建立網站集合之後,您應該能夠使用 Windows 或同盟網站集合系統管理員帳戶登入。
步驟 7:設定 人員 選擇器
在 OIDC 驗證中,人員 選擇器不會驗證輸入,這可能會導致拼字錯誤或使用者不小心選取錯誤的宣告類型。 您可以使用自定義宣告提供者,或使用包含在 SharePoint Server 訂閱版本 中的新UPA支援宣告提供者來解決此問題。 若要設定 UPA 支援的宣告提供者,請參閱增強 人員 選擇器以進行新式驗證。