Замена секрета клиента с истекающим сроком действия в надстройке SharePoint

  • Статья

Срок действия секретов клиента для надстроек SharePoint, зарегистрированных на странице AppRegNew.aspx, завершается спустя год. В этой статье описано, как добавить новый секрет клиента для надстройки и создать секрет клиента, действительный в течение трех лет.

Примечание.

Эта статья посвящена надстройкам SharePoint, распространяемым через каталог организации и зарегистрированным на странице AppRegNew.aspx. Если надстройка зарегистрирована на Панели мониторинга продаж, см. статью Создание или обновление идентификаторов и секретов клиентов на Панели мониторинга продаж.

Рекомендуется создавать новые секреты не менее чем за 30 дней до истечения срока их действия. Это обеспечит вам месяц до истечения срока действия старых учетных данных.

Рекомендуется удалять секреты минимум через 7 дней после истечения срока действия при условии, что они удалены из конфигурации приложения.

Удаление просроченного секрета из ACS перед его удалением из конфигурации приложения приведет к ошибкам.

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

Прежде чем приступать к работе, убедитесь в следующем:

  • На компьютере разработчика установлен Помощник по входу в Microsoft Online Services.
  • Можно подключиться к Office 365 с помощью PowerShell: Подключение к Office 365 PowerShell
  • Вы администратор фермы или клиента Office 365, для которого зарегистрирована надстройка на странице AppRegNew.aspx.

Просмотр дат истечения срока Надстройки SharePoint, установленных на клиенте Office 365

  1. Откройте Windows PowerShell и запустите следующий командлет:

    Connect-MsolService

  2. Когда вам будет предложено войти, введите учетные данные администратора клиента или администратора фермы для той области клиентов Office 365 или фермы, где надстройка зарегистрирована с помощью страницы AppRegNew.aspx.

  3. Создайте отчет со списком всех надстроек и датами истечения срока действия их секретов с помощью указанных ниже строк. Обратите внимание на особенности этого кода:

    • Сначала он применяет фильтр к приложениям Майкрософт и надстройкам, находящимся на стадии разработки (а теперь и к надстройкам устаревшего типа — размещаемым автоматически).
    • Из оставшихся результатов он исключает надстройки не для SharePoint и надстройки, для которых используются асимметричные ключи (например, рабочие процессы).
    $applist = Get-MsolServicePrincipal -all  |Where-Object -FilterScript { ($_.DisplayName -notlike "*Microsoft*") -and ($_.DisplayName -notlike "autohost*") -and  ($_.ServicePrincipalNames -notlike "*localhost*") }

foreach ($appentry in $applist) {
    $principalId = $appentry.AppPrincipalId

    Get-MsolServicePrincipalCredential -AppPrincipalId $principalId -ReturnKeyValues $false | Where-Object { $_.Type -eq "Password" } | ForEach-Object {
        [PSCustomObject][Ordered]@{
            PrincipalName = $appentry.DisplayName
            PrincipalId = $principalId
            KeyID = $_.KeyId
            StartDate = $_.StartDate
            EndDate = $_.EndDate
        } | Export-Csv -Path C:\temp\appsec.csv -NoTypeInformation -Delimiter ';' -Append
    }
}

  4. Откройте файл C:\temp\appsec.csv, чтобы просмотреть отчет. Если у каких-либо секретов заканчивается срок действия, оставьте окно Windows PowerShell открытым в ходе следующей процедуры.

Создание секрета клиента

  1. Создайте переменную ИД клиента со следующем строкой, используя ИД клиента, которое имеет Надстройка SharePoint, в качестве параметра.

    $clientId = 'client id of the add-in'

  2. Создайте секрет клиента со следующими строками:

    $bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$dtStart = [System.DateTime]::Now
$dtEnd = $dtStart.AddYears(1)
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Sign -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Verify -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Password -Usage Verify -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd
$newClientSecret

  3. В консоли Windows PowerShell появится новый секрет клиента. Скопируйте его в текстовый файл. Он потребуется в следующей процедуре.

    Совет

    По умолчанию срок действия секрета клиента составляет один год. Его можно сделать короче или дольше с помощью параметра -EndDate в трех вызовах командлета New-MsolServicePrincipalCredential.

Обновление удаленного веб-приложения в Visual Studio для использования нового секрета

Важно!

Если надстройка изначально создавалась в предварительной версии Microsoft Visual Studio Office Developer Tools, то она может содержать устаревшую версию файла TokenHelper.cs (или TokenHelper.vb). Если файл не содержит строку secondaryClientSecret, то он устарел и его следует заменить, прежде чем задавать для веб-приложения новый секрет. Чтобы получить копию полной версии этого файла, вам потребуется Visual Studio 2012 или более поздней версии. Создайте проект надстройки SharePoint в Visual Studio. Скопируйте файл TokenHelper в проект веб-приложения для своей надстройки SharePoint.

  1. Откройте проект для решения Надстройка SharePoint в Visual Studio и откройте файл web.config для проекта веб-приложения. В разделе appSettings находятся ключи для ИД клиента и секрет клиента. Ниже приведен пример.

    <appSettings>
  <add key="ClientId" value="your client id here" />
  <add key="ClientSecret" value="your old secret here" />
    ... other settings may be here ...
</appSettings>

  2. Измените имя ключа ClientSecret на SecondaryClientSecret, как показано в приведенном ниже примере.

    <add key="SecondaryClientSecret" value="your old secret here" />

    Примечание.

    Если вы делаете это впервые, то файл конфигурации еще не содержит свойство SecondaryClientSecret. Однако если это не первый раз, когда истек срок действия секрета клиента, то свойство SecondaryClientSecret уже присутствует и содержит исходный либо просроченный секрет. В таком случае сначала удалите свойство SecondaryClientSecret, прежде чем переименовывать ClientSecret.

  3. Добавьте новый ключ ClientSecret и включите в него новый секрет клиента. Результат должен выглядеть следующим образом:

    <appSettings>
  <add key="ClientId" value="your client id here" />
  <add key="ClientSecret" value="your new secret here" />
  <add key="SecondaryClientSecret" value="your old secret here" />
    ... other settings may be here ...
</appSettings>

    Важно!

    Новый секрет клиента невозможно использовать, пока не истечет срок действия текущего. Если вы замените ключ ClientId новым секретом клиента, когда отсутствует ключ SecondaryClientSecret, нужного результата не будет. Необходимо выполнить процедуру, описанную в этой статье, и дождаться истечения срока действия предыдущего секрета клиента. После этого можно будет при необходимости удалить SecondaryClientSecret.

  4. Если вы использовали новый файл TokenHelper, выполните повторную сборку проекта.

  5. Опубликуйте веб-приложение повторно.

Создание секрета клиента, действительного на протяжении трех лет

Для начала необходимо удалить все просроченные секреты клиентов для соответствующего ключа clientId. Затем создайте новый секрет с помощью MSO PowerShell, подождите хотя бы 24 часа и протестируйте приложение с новыми ключами clientId и ClientSecret.

  1. Подключитесь к Microsoft Office Online от имени администратора клиента с помощью приведенной ниже разметки, используя Windows PowerShell для SharePoint.

    import-module MSOnline
$msolcred = get-credential
connect-msolservice -credential $msolcred

  2. Получите ServicePrincipals и ключи. Команда $keys возвращает три записи. Вы также увидите значение EndDate для каждого ключа. Убедитесь, что там отображается просроченный ключ.

    Примечание.

    Значение clientId должно соответствовать просроченному clientId. Рекомендуем удалить все ключи для этого clientId — и просроченные, и действительные.

    $clientId = "27c5b286-62a6-45c7-beda-abbaea6eecf2"
$keys = Get-MsolServicePrincipalCredential -AppPrincipalId $clientId
$keys

  3. Удалите все ключи после подтверждения того, что сроки их действия истекли.

    Remove-MsolServicePrincipalCredential -KeyIds $keys.KeyId -AppPrincipalId $clientId

  4. Создайте новое значение ClientSecret для этого clientID. Используется тот же clientId, что и на предыдущем этапе. Новый ключ ClientSecret будет действителен в течение трех лет.

    $bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$dtStart = [System.DateTime]::Now
$dtEnd = $dtStart.AddYears(3)
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Sign -Value $newClientSecret -StartDate $dtStart  -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Verify -Value $newClientSecret   -StartDate $dtStart  -EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Password -Usage Verify -Value $newClientSecret   -StartDate $dtStart  -EndDate $dtEnd
$newClientSecret

  5. Скопируйте выходные данные команды $newClientSecret.

  6. Замените Web.config этими значениями ClientId и ClientSecret. Параметры приложения SecondaryClientSecret не нужны.

  7. Подождите хотя бы 24 часа, пока ClientSecret распространится в SharePoint Online (SPO).

См. также