Ротация ключа подписи AD FS

Процедуру выполняет администратор AD FS совместно с администратором BusinessProxy. Ключ Token-Signing относится ко всему издателю AD FS: переключение затрагивает другие OIDC- и SAML-приложения этой фермы. Проверьте готовность всех партнёров и сохраните независимый доступ администратора.

• Приведённый порядок проверен для стандартных автоматически создаваемых сертификатов AD FS на Windows Server 2019, farm behavior 4. Для сертификатов собственной CA или HSM используйте их процедуру выпуска и импорта.
• Проверьте время серверов, HTTPS discovery и JWKS, обычный вход сотрудника и доступ к разрешённому приложению. Существующие Client ID, client secret, callback, группы и связи пользователей для ротации подписи менять не требуется.
• Перед переключением подготовьте и проверьте откат на стороне сервера. В контролируемом испытании можно использовать временную задачу восстановления от SYSTEM; удалите её после успешного завершения. Проверка только со стороны рабочего компьютера не защищает от потери соединения.

На основном сервере AD FS откройте Windows PowerShell от администратора. Команды сохраняют отпечатки публичных сертификатов и исходный флаг автоматической ротации. Сохраните путь к checkpoint и выполняйте следующие шаги в той же сессии PowerShell. Экспорт приватных ключей не нужен.

$before = @(Get-AdfsCertificate -CertificateType 'Token-Signing')
$primary = @($before | Where-Object { $_.IsPrimary })
if ($primary.Count -ne 1) { throw 'Expected one primary signing certificate' }
$OldThumbprint = $primary[0].Certificate.Thumbprint
$OriginalAutoRollover = (Get-AdfsProperties).AutoCertificateRollover
$OldThumbprints = @($before | ForEach-Object { $_.Certificate.Thumbprint })
$Checkpoint = Join-Path $env:USERPROFILE ('adfs-signing-before-' + (Get-Date -Format 'yyyyMMdd-HHmmss') + '.json')
[ordered]@{
  primary = $OldThumbprint
  thumbprints = $OldThumbprints
  auto_rollover = $OriginalAutoRollover
} | ConvertTo-Json | Out-File -FilePath $Checkpoint -Encoding utf8 -NoClobber
$before | Select-Object IsPrimary, @{Name='Thumbprint';Expression={$_.Certificate.Thumbprint}}, @{Name='NotAfter';Expression={$_.Certificate.NotAfter}}

Для стандартного автоматического профиля используйте обычный Update-AdfsCertificate. Старый сертификат должен остаться основным, а новый — появиться вторичным. Если состояние отличается от ожидаемого, остановитесь и сверьте checkpoint.

if (-not $OriginalAutoRollover) { throw 'Use the procedure for your manually managed certificates' }
Update-AdfsCertificate -CertificateType 'Token-Signing'
$after = @(Get-AdfsCertificate -CertificateType 'Token-Signing')
$new = @($after | Where-Object { $_.Certificate.Thumbprint -notin $OldThumbprints })
if ($new.Count -ne 1 -or $new[0].IsPrimary) { throw 'Inspect the certificate state before continuing' }
$NewThumbprint = $new[0].Certificate.Thumbprint

• Не используйте -Urgent для плановой проверки: экстренная ротация сразу удаляет старые сертификаты и сокращает возможность совместной работы ключей.

Подставьте свой HTTPS Issuer. Получите JWKS URL через discovery и сопоставьте опубликованные сертификаты с сохранёнными отпечатками. В BusinessProxy выполните тест подключения и обычный вход сотрудника. До переключения все партнёры AD FS должны получить новый публичный ключ.

$Issuer = 'https://adfs.example.com/adfs'
$discovery = Invoke-RestMethod ($Issuer + '/.well-known/openid-configuration')
$jwks = Invoke-RestMethod $discovery.jwks_uri
$jwks.keys | ForEach-Object {
  $certificate = [Security.Cryptography.X509Certificates.X509Certificate2]::new([Convert]::FromBase64String($_.x5c[0]))
  try { [pscustomobject]@{ kid = $_.kid; thumbprint = $certificate.Thumbprint } }
  finally { $certificate.Dispose() }
}

• Кнопка «Тест» подтверждает доступность discovery/JWKS. Она не заменяет реальный вход, проверку групп и открытия приложения.

При штатной автоматической ротации AD FS повышает сертификат по своей политике. Следующие команды предназначены для согласованного ручного переключения или контрольного испытания после проверки публикации. Они временно отключают автоматическую ротацию; исходное значение нужно восстановить после проверки или при откате.

Set-AdfsProperties -AutoCertificateRollover $false
Set-AdfsCertificate -CertificateType 'Token-Signing' -Thumbprint $NewThumbprint -IsPrimary
Get-AdfsCertificate -CertificateType 'Token-Signing' | Select-Object IsPrimary, @{Name='Thumbprint';Expression={$_.Certificate.Thumbprint}}

Используйте новый браузерный контекст, чтобы проверить новый вход, а не уже действующую сессию. BusinessProxy выбирает ключ по kid из текущего JWKS и проверяет подпись, issuer, audience, nonce и срок токена.

• Сотрудник с разрешённой группой входит как обычный участник и открывает назначенное приложение. Ротация не должна назначать роль администратора.
• Проверьте оба выбранных режима: создание аккаунта при первом входе (JIT) и вход сотрудника из импортированного каталога. Старый ключ в период совместной публикации остаётся допустимым для ещё действующих токенов.
• После успешной проверки верните исходное значение: Set-AdfsProperties -AutoCertificateRollover $OriginalAutoRollover. Удалите временную задачу отката, только когда новый основной сертификат принят.
• Ротация ключа AD FS не отзывает уже выданные сессии BusinessProxy. Для прекращения доступа отзывайте нужные сессии или применяйте отключение сотрудника через каталог.

Если новый вход не проходит, используйте сохранённый отпечаток старого сертификата. После команд проверьте реальный вход и исходное значение AutoCertificateRollover. Не удаляйте новый вторичный ключ автоматически: его ещё могут использовать выданные токены. В тестовом испытании допустимо удалить только собственный тестовый ключ после завершения проверок.

Set-AdfsProperties -AutoCertificateRollover $false
Set-AdfsCertificate -CertificateType 'Token-Signing' -Thumbprint $OldThumbprint -IsPrimary
Set-AdfsProperties -AutoCertificateRollover $OriginalAutoRollover

Окно определяется сроками токенов, обновлением metadata/JWKS у всех партнёров и политикой вашей организации. Перед удалением убедитесь, что старый сертификат больше не основной. После удаления токены с его kid должны отклоняться при новой проверке. Сохраните журнал проверки и исходный checkpoint.

$current = @(Get-AdfsCertificate -CertificateType 'Token-Signing' | Where-Object { $_.IsPrimary })
if ($current.Count -ne 1 -or $current[0].Certificate.Thumbprint -eq $OldThumbprint) {
  throw 'Do not remove the primary certificate'
}
# Run only after the agreed overlap period and partner checks.
$RetirementAutoRollover = (Get-AdfsProperties).AutoCertificateRollover
try {
  Set-AdfsProperties -AutoCertificateRollover $false
  Remove-AdfsCertificate -CertificateType 'Token-Signing' -Thumbprint $OldThumbprint
} finally {
  Set-AdfsProperties -AutoCertificateRollover $RetirementAutoRollover
}