Настройка проверки подлинности OIDC в SharePoint Server с помощью Microsoft Entra ID

ОБЛАСТЬ ПРИМЕНЕНИЯ:2013 2016 2019 Subscription Edition SharePoint в Microsoft 365

Предварительные условия

При настройке OpenID Connect (OIDC) с Microsoft Entra ID вам потребуются следующие ресурсы:

1. Ферма SharePoint Server по подписке (SPSE)

2. Microsoft Entra роль глобального администратора клиента M365

В этой статье используются следующие примеры значений для Microsoft Entra установки OIDC:

Значение	Ссылка
Универсальный указатель ресурсов сайта SharePoint (URL-адрес)	https://spsites.contoso.local/
URL-адрес сайта OIDC	https://sts.windows.net/<tenantid>/
конечная точка проверки подлинности OIDC Microsoft Entra	https://login.microsoftonline.com/<tenantid>/oauth2/authorize
URL-адрес Microsoft Entra OIDC RegisteredIssuerName	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

Шаг 1. Настройка поставщика удостоверений

Чтобы настроить OIDC с Microsoft Entra ID, выполните следующие действия.

1. Перейдите на портал администрирования Entra ID и войдите с учетной записью с ролью глобального администратора.

2. В разделе Приложения выберите Регистрация приложений.

3. Выберите Новая регистрация.

4. Перейдите на страницу https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredAppsРегистрация приложения .

5. В разделе URI перенаправления выберите "Веб" в качестве платформы и введите URL-адрес веб-приложения SharePoint Server, например: https://spsites.contoso.local/ и нажмите кнопку Зарегистрировать.

   

6. Сохраните значение идентификатора каталога (клиента), так как идентификатор клиента используется на последующих шагах. Кроме того, сохраните идентификатор приложения (клиента), который мы используем в качестве DefaultClientIdentifier в настройке SharePoint.

   

7. После регистрации приложения перейдите на вкладку Проверка подлинности, выберите поле Маркеры идентификации проверка и нажмите кнопку Сохранить.

   

8. Перейдите на вкладку Разрешения API и выберите Добавить разрешение. Выберите Microsoft Graph, а затем — Делегированные разрешения. Выберите добавить разрешения электронной почты и профиля и выберите Добавить разрешения.

   

9. Перейдите на вкладку Конфигурация токена и выберите Добавить необязательное утверждение. Для каждого типа маркера (ID, Access, SAML) добавьте сообщения электронной почты и утверждения upn .

10. Также на вкладке Конфигурация маркера выберите Добавить утверждение групп. Группы безопасности являются наиболее распространенными, но выбираемые типы групп зависят от типов групп, которые вы хотите использовать для предоставления доступа к веб-приложению SharePoint. Дополнительные сведения см. в разделах Настройка необязательных утверждений групп и Настройка утверждений группы для приложений с помощью Microsoft Entra ID.

    

11. Перейдите на вкладку Манифест и вручную измените replyUrlsWithType с https://spsites.contoso.local/ на https://spsites.contoso.local/*. Нажмите Сохранить.

    

Шаг 2. Изменение свойств фермы SharePoint

На этом шаге необходимо изменить свойства фермы SharePoint Server в зависимости от версии фермы SharePoint Server.

• Дополнительные сведения о настройке свойств фермы SharePoint для SharePoint Server по подписке версии 24H1 см. в разделе Настройка SPSE версии 24H1 или более поздней версии.
• Дополнительные сведения о настройке свойств фермы SharePoint для SharePoint Server по подписке версии до 24H1 см. в разделе Настройка SPSE до версии 24H1.

Настройка SharePoint Server по подписке версии 24H1 или более поздней

Начиная с SharePoint Server по подписке версии 24H1 (март 2024 г.), вы можете настроить свойства фермы SharePoint Server, используя управление сертификатами SharePoint для управления сертификатами nonce. Сертификат cookie nonce является частью инфраструктуры для обеспечения безопасности маркеров проверки подлинности OIDC. Выполните следующий скрипт, чтобы настроить:

Примечание.

Запустите командную консоль 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 to save the exported cert>
$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)

Настройка SharePoint Server по подписке до версии 24H1

До обновления 24H1 (март 2024 г.) сертификатом файла cookie nonce необходимо управлять вручную. Это включает установку вручную на каждом сервере фермы и настройку разрешений для закрытого ключа. Для этого можно использовать следующий скрипт 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()

Важно!

Сертификат файла cookie nonce с закрытым ключом должен быть установлен на всех серверах SharePoint в ферме. Кроме того, разрешение на закрытый ключ должно быть предоставлено учетной записи службы пула веб-приложений на каждом сервере. Сбой выполнения этого шага приведет к сбою проверки подлинности OIDC. Рекомендуется использовать приведенный выше пример PowerShell, чтобы задать разрешение на файл закрытого ключа, чтобы убедиться, что он выполнен правильно.

Шаг 3. Настройка SharePoint для доверия поставщику удостоверений

На этом шаге вы создадите объект , в котором SPTrustedTokenIssuer хранится конфигурация, необходимая SharePoint для доверия Microsoft Entra OIDC в качестве поставщика OIDC.

Вы можете настроить SharePoint так, чтобы он доверял поставщику удостоверений, используя один из следующих способов:

• Настройте SharePoint для доверия Microsoft Entra ID в качестве поставщика OIDC с помощью конечной точки метаданных.
  • С помощью конечной точки метаданных из конечной точки метаданных автоматически извлекаются несколько необходимых параметров.
• Настройте SharePoint, чтобы доверять Microsoft Entra ID в качестве поставщика OIDC вручную.

Примечание.

Выполните действия по настройке вручную или конечную точку метаданных, но не обе.
Рекомендуется использовать конечную точку метаданных, так как это упрощает процесс.

Настройка SharePoint для доверия Microsoft Entra OIDC с помощью конечной точки метаданных

SharePoint Server по подписке теперь поддерживает использование возможности обнаружения метаданных OIDC при создании издателя доверенного маркера удостоверения.

В Microsoft Entra ID существует две версии конечных точек обнаружения OIDC:

• Версия 1.0: https://login.microsoftonline.com/<TenantID>/.well-known/openid-configuration
• Версия 2.0: https://login.microsoftonline.com/<TenantID>/v2.0/.well-known/openid-configuration

Важно!

В настоящее время SharePoint Server поддерживает только конечную точку метаданных версии 1.0, если используется для создания издателя доверенного маркера удостоверения. В примере скрипта PowerShell ниже используется конечная точка версии 1.0.

При использовании конечной точки метаданных, предоставляемой поставщиком удостоверений OIDC, часть конфигурации извлекается непосредственно из конечной точки метаданных поставщика OIDC, в том числе:

1. Сертификат
2. Издатель
3. Конечная точка авторизации
4. 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	Сертификат, используемый для проверки id_token из идентификатора OIDC.
ClaimsMappings	Объект SPClaimTypeMapping , который используется для определения того, какое утверждение в id_token считается идентификатором в SharePoint.
IdentifierClaim	Указывает тип идентификатора.
DefaultClientIdentifier	Указывает client_id сервер SharePoint, назначенный поставщиком удостоверений OIDC. Это проверяется на соответствие утверждению aud в id_token.
МетаданныеEndPoint	Указывает известную конечную точку метаданных от поставщика удостоверений OIDC, которую можно использовать для получения последнего сертификата, издателя, конечной точки авторизации и конечной точки выхода.

Настройка SharePoint для доверия Microsoft Entra ID в качестве поставщика OIDC вручную

При настройке вручную необходимо указать несколько дополнительных параметров. Значения можно получить из конечной точки обнаружения OIDC.

В Microsoft Entra ID существует две версии конечных точек проверки подлинности OIDC. Таким образом, существует две версии конечных точек обнаружения OIDC соответственно:

• Версия 1.0: https://login.microsoftonline.com/<TenantID>/.well-known/openid-configuration
• Версия 2.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 расширен для поддержки OIDC с помощью следующих параметров:

Параметр	Описание
Имя	Предоставляет имя новому издателю маркера.
Описание	Предоставляет описание новому издателю маркера.
ImportTrustCertificate	Импортирует список сертификатов X509, который используется для проверки id_token из идентификатора OIDC. Если поставщик удостоверений OIDC (IDP) использует несколько сертификатов для цифровой id_tokenподписи , импортируйте эти сертификаты, и SharePoint проверяет id_token , сопоставляя цифровую подпись, созданную с помощью этих сертификатов.
ClaimsMappings	Объект SPClaimTypeMapping , который используется для определения того, какое утверждение в id_token считается идентификатором в SharePoint.
IdentifierClaim	Указывает тип идентификатора.
RegisteredIssuerName	Указывает идентификатор издателя, который выдает id_token. Он используется для проверки id_token.
AuthorizationEndPointUrl	Указывает конечную точку авторизации поставщика удостоверений OIDC.
SignoutUrl	Указывает конечную точку выхода поставщика удостоверений OIDC.
DefaultClientIdentifier	Указывает client_id сервер SharePoint, назначенный поставщиком удостоверений OIDC. Это проверяется на соответствие утверждению aud в id_token.
ResponseTypesSupported	Указывает тип ответа поставщика удостоверений, который принимается этим издателем маркера. Он может принимать две строки: id_token и code id_token. Если этот параметр не указан, он использует по code id_token умолчанию.

Шаг 4. Настройка веб-приложения SharePoint

На этом шаге вы настраиваете веб-приложение в SharePoint для федерации с Microsoft Entra OIDC с помощью созданного SPTrustedIdentityTokenIssuer на предыдущем шаге.

Важно!

• Для зоны по умолчанию веб-приложения SharePoint должна быть включена проверка подлинности Windows. Это необходимо для средства обхода Поиск.
• URL-адрес SharePoint, который будет использовать Microsoft Entra федерации OIDC, должен быть настроен с использованием протокола HTTPS.

Эту настройку можно выполнить следующим образом:

• Создание веб-приложения и использование Windows и Microsoft Entra проверки подлинности OIDC в зоне по умолчанию.
• Расширение существующего веб-приложения для установки Microsoft Entra проверки подлинности OIDC в новой зоне.

Чтобы создать веб-приложение, сделайте следующее:

1. Запустите командную консоль SharePoint и запустите следующий скрипт, чтобы создать новый SPAuthenticationProvider:

   # This script creates a trusted authentication provider for OIDC
   
   $sptrust = Get-SPTrustedIdentityTokenIssuer "contoso.local"
   $trustedAp = New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $sptrust
   

2. Выполните Create веб-приложение в SharePoint Server, чтобы создать новое веб-приложение с поддержкой ПРОТОКОЛА HTTPS/SSL с именем SharePoint — OIDC в contoso.local.

3. Откройте сайт центра администрирования SharePoint.

4. Выберите созданное веб-приложение, выберите "Поставщики проверки подлинности" на ленте, щелкните ссылку для зоны по умолчанию и выберите contoso.local в качестве доверенного поставщика удостоверений.

   

5. На сайте центра администрирования SharePoint перейдите в раздел Параметры системы Настройка альтернативных сопоставлений>доступа Коллекция альтернативных сопоставлений>доступа.

6. Отфильтруйте отображение с помощью нового веб-приложения и убедитесь, что отображается следующая информация:

   

Чтобы расширить существующее веб-приложение и настроить его для использования доверенного поставщика contoso.local, сделайте следующее:

1. Запустите командную консоль SharePoint и запустите PowerShell, чтобы расширить веб-приложение. В следующем примере веб-приложение расширяется до зоны интрасети и настраивается зона для использования доверенного поставщика Contoso.local для проверки подлинности.

Примечание.

Для этого необходимо иметь действительный сертификат с именем "Сайт SharePoint OIDC", импортированный в ферму. Дополнительные сведения см. в разделе Операции управления 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' 

2. На сайте центра администрирования SharePoint перейдите в раздел Параметры системы Настройка альтернативных сопоставлений>доступа Коллекция альтернативных сопоставлений>доступа.

3. Отфильтруйте отображение с помощью расширенного веб-приложения и убедитесь, что отображается следующая информация:

   

Шаг 5. Убедитесь, что веб-приложение настроено с помощью SSL-сертификата

Так как проверка подлинности OIDC 1.0 может работать только с протоколом HTTPS, необходимо задать сертификат в соответствующем веб-приложении. Если он еще не настроен, выполните следующие действия, чтобы задать сертификат.

1. Создайте сертификат сайта:

   Примечание.

   Этот шаг можно пропустить, если сертификат уже создан.

   1. Откройте консоль SharePoint PowerShell.

   2. Выполните следующий скрипт, чтобы создать самозаверяющий сертификат и добавить его в ферму 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
      

      Важно!

      Самозаверяемые сертификаты подходят только для тестовых целей. В рабочих средах настоятельно рекомендуется использовать сертификаты, выданные центром сертификации.

2. Задайте сертификат:

   Чтобы назначить сертификат веб-приложению, можно использовать следующий командлет PowerShell:

   Set-SPWebApplication -Identity https://spsites.contoso.local -Zone Default -SecureSocketsLayer -Certificate "Contoso SharePoint (2021)"
   

Шаг 6. Create семейства веб-сайтов

На этом шаге вы создадите семейство веб-сайтов группы с двумя администраторами: один — как администратор Windows, а второй — как федеративный (Microsoft Entra ID) администратор.

1. Откройте сайт центра администрирования SharePoint.

2. Перейдите в раздел Управление приложениями>Create семейства веб-сайтов>Create семейства веб-сайтов.

3. Введите заголовок, URL-адрес и выберите шаблон Сайт группы.

4. В разделе Основной администратор семейства веб-сайтов выберите (книга), чтобы открыть диалоговое окно средства выбора Люди.

5. В диалоговом окне выбора Люди введите учетную запись администратора Windows, например yvand.

6. Отфильтруйте список слева, выбрав Организации. Ниже приведен пример выходных данных:

   

7. Перейдите к учетной записи и нажмите кнопку ОК.

8. В разделе Дополнительный администратор семейства веб-сайтов щелкните значок книги, чтобы открыть диалоговое окно средства выбора Люди.

9. В диалоговом окне средства выбора Люди введите точное значение электронной почты учетной записи Microsoft Entra администратора, например yvand@contoso.local.

10. Отфильтруйте список слева, выбрав contoso.local. Ниже приведен пример выходных данных:

    

11. Перейдите к учетной записи и нажмите кнопку ОК, чтобы закрыть диалоговое окно выбора Люди.

12. Нажмите кнопку ОК еще раз, чтобы создать семейство веб-сайтов.

После создания семейства веб-сайтов вы сможете войти в систему с помощью учетной записи администратора семейства веб-сайтов Windows или федеративного семейства веб-сайтов.

Шаг 7. Настройка средства выбора Люди

При проверке подлинности OIDC средство выбора Люди не проверяет входные данные, что может привести к ошибкам или случайному выбору неправильного типа утверждения. Это можно решить с помощью пользовательского поставщика утверждений или с помощью нового поставщика утверждений с поддержкой UPA, включенного в SharePoint Server по подписке. Сведения о настройке поставщика утверждений с поддержкой UPA см. в статье Расширенный выбор Люди для современной проверки подлинности.