Использование модели предоставления доступа только для приложений в Azure AD
При использовании SharePoint Online можно определить приложения в Azure AD, и они смогут получить разрешения в SharePoint, а также во всех остальных службах Office 365. Эта модель является предпочтительной в случае, если вы используете SharePoint Online, если вы используете sharePoint в локальной среде, вам нужно использовать модель "Только SharePoint" через Azure ACS, как описано здесь.
Важно!
Использование Azure ACS (служб контроль доступа) для SharePoint Online прекращено с 27 ноября 2023 г. См. полное объявление о выходе из эксплуатации, чтобы узнать больше. Использование Azure ACS вне контекста SharePoint уже прекращено 7 ноября 2018 г. и сейчас заканчивается.
Прекращение использования означает, что эта функция не получит новых инвестиций, но она по-прежнему поддерживается. Окончание срока службы означает, что эта функция будет прекращена и больше не доступна для использования.
Настройка приложения Azure AD для доступа только для приложений
В Azure AD при выполнении действия только для приложения вы обычно используете сертификат для запроса доступа: любой пользователь, имеющий сертификат и его закрытый ключ, может использовать приложение и разрешения, предоставленные приложению. Ниже приведены инструкции по настройке этой модели.
Теперь вы можете настроить приложение Azure AD для вызова SharePoint Online с помощью маркера доступа только для приложений. Для этого необходимо создать и настроить самозаверяющий сертификат X.509, который будет использоваться для проверки подлинности приложения Azure AD при запросе маркера доступа только для приложений. Сначала необходимо создать самозаверяющий сертификат X.509, который можно создать с помощью средства makecert.exe, доступного в windows SDK, с помощью предоставленного скрипта PowerShell, который не имеет зависимости для создания сертификата или с помощью команды PowerShell PnP. Использование скрипта PowerShell является предпочтительным методом, который описывается в этой главе.
Важно!
Важно запустить приведенные ниже скрипты с правами администратора.
Чтобы создать самозаверяющий сертификат с помощью этого скрипта:
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate 2017-10-01 -EndDate 2019-10-01
Примечание.
Даты предоставляются в формате ISO: ГГГГ-ММ-дд
Алгоритм ключа сертификата должен быть RSA. В настоящее время это единственный поддерживаемый алгоритм.
Фактический скрипт можно скопировать здесь:
#Requires -RunAsAdministrator
<#
.SYNOPSIS
Creates a Self Signed Certificate for use in server to server authentication
.DESCRIPTION
.EXAMPLE
PS C:\> .\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21
This will create a new self signed certificate with the common name "CN=MyCert". During creation you will be asked to provide a password to protect the private key.
.EXAMPLE
PS C:\> .\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Password (ConvertTo-SecureString -String "MyPassword" -AsPlainText -Force)
This will create a new self signed certificate with the common name "CN=MyCert". The password as specified in the Password parameter will be used to protect the private key
.EXAMPLE
PS C:\> .\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Force
This will create a new self signed certificate with the common name "CN=MyCert". During creation you will be asked to provide a password to protect the private key. If there is already a certificate with the common name you specified, it will be removed first.
#>
Param(
[Parameter(Mandatory=$true)]
[string]$CommonName,
[Parameter(Mandatory=$true)]
[DateTime]$StartDate,
[Parameter(Mandatory=$true)]
[DateTime]$EndDate,
[Parameter(Mandatory=$false, HelpMessage="Will overwrite existing certificates")]
[Switch]$Force,
[Parameter(Mandatory=$false)]
[SecureString]$Password
)
# DO NOT MODIFY BELOW
function CreateSelfSignedCertificate(){
#Remove and existing certificates with the same common name from personal and root stores
#Need to be very wary of this as could break something
if($CommonName.ToLower().StartsWith("cn="))
{
# Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
$certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
if($certs -ne $null -and $certs.Length -gt 0)
{
if($Force)
{
foreach($c in $certs)
{
remove-item $c.PSPath
}
} else {
Write-Host -ForegroundColor Red "One or more certificates with the same common name (CN=$CommonName) are already located in the local certificate store. Use -Force to remove them";
return $false
}
}
$name = new-object -com "X509Enrollment.CX500DistinguishedName.1"
$name.Encode("CN=$CommonName", 0)
$key = new-object -com "X509Enrollment.CX509PrivateKey.1"
$key.ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
$key.KeySpec = 1
$key.Length = 2048
$key.SecurityDescriptor = "D:PAI(A;;0xd01f01ff;;;SY)(A;;0xd01f01ff;;;BA)(A;;0x80120089;;;NS)"
$key.MachineContext = 1
$key.ExportPolicy = 1 # This is required to allow the private key to be exported
$key.Create()
$serverauthoid = new-object -com "X509Enrollment.CObjectId.1"
$serverauthoid.InitializeFromValue("1.3.6.1.5.5.7.3.1") # Server Authentication
$ekuoids = new-object -com "X509Enrollment.CObjectIds.1"
$ekuoids.add($serverauthoid)
$ekuext = new-object -com "X509Enrollment.CX509ExtensionEnhancedKeyUsage.1"
$ekuext.InitializeEncode($ekuoids)
$cert = new-object -com "X509Enrollment.CX509CertificateRequestCertificate.1"
$cert.InitializeFromPrivateKey(2, $key, "")
$cert.Subject = $name
$cert.Issuer = $cert.Subject
$cert.NotBefore = $StartDate
$cert.NotAfter = $EndDate
$cert.X509Extensions.Add($ekuext)
$cert.Encode()
$enrollment = new-object -com "X509Enrollment.CX509Enrollment.1"
$enrollment.InitializeFromRequest($cert)
$certdata = $enrollment.CreateRequest(0)
$enrollment.InstallResponse(2, $certdata, 0, "")
return $true
}
function ExportPFXFile()
{
if($CommonName.ToLower().StartsWith("cn="))
{
# Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
if($Password -eq $null)
{
$Password = Read-Host -Prompt "Enter Password to protect private key" -AsSecureString
}
$cert = Get-ChildItem -Path Cert:\LocalMachine\my | where-object{$_.Subject -eq "CN=$CommonName"}
Export-PfxCertificate -Cert $cert -Password $Password -FilePath "$($CommonName).pfx"
Export-Certificate -Cert $cert -Type CERT -FilePath "$CommonName.cer"
}
function RemoveCertsFromStore()
{
# Once the certificates have been been exported we can safely remove them from the store
if($CommonName.ToLower().StartsWith("cn="))
{
# Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
$certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
foreach($c in $certs)
{
remove-item $c.PSPath
}
}
if(CreateSelfSignedCertificate)
{
ExportPFXFile
RemoveCertsFromStore
}
Вам будет предложено ввести пароль для шифрования закрытого ключа и обоих . PFX-файл и . CER-файл будет экспортирован в текущую папку.
Примечание.
Самозаверяющий сертификат также можно создать с помощью команды New-PnPAzureCertificate .
Следующий шаг — регистрация приложения Azure AD в клиенте Azure Active Directory, связанном с клиентом Office 365. Для этого откройте центр Администратор Office 365 (https://admin.microsoft.com), используя учетную запись участника группы глобальных администраторов клиента. Щелкните ссылку "Azure Active Directory", которая доступна в группе "центры Администратор" в левом представлении дерева центра Администратор Office 365. На открывшейся вкладке нового браузера вы найдете портал Azure Майкрософт. Если вы впервые обращаетесь к портал Azure с помощью учетной записи, вам потребуется зарегистрировать новую подписку Azure, предоставив некоторые сведения и кредитную карта для любых платежей. Но не волнуйтесь, чтобы играть с Azure AD и регистрировать Office 365 приложение вы ничего не платите. На самом деле это бесплатные возможности. Получив доступ к портал Azure, выберите раздел "Azure Active Directory" и выберите параметр "Регистрация приложений". Дополнительные сведения см. на следующем рисунке.
На вкладке "Регистрация приложений" вы найдете список Azure AD приложений, зарегистрированных в клиенте. Нажмите кнопку "Новая регистрация" в левой верхней части колонки. Затем укажите имя приложения и щелкните "Зарегистрировать" в нижней части колонки.
Важно!
После создания приложения скопируйте идентификатор приложения (клиента), который вам понадобится позже.
Теперь щелкните "Разрешения API" в левой строке меню и нажмите кнопку "Добавить разрешение". Появится новая колонка. Здесь вы выбираете разрешения, которые будут предоставлены этому приложению. Выберите, например:
- SharePoint
- Разрешения приложений
- Сайты
- Sites.FullControl.All
- Сайты
- Разрешения приложений
Нажмите синюю кнопку "Добавить разрешения" внизу, чтобы добавить разрешения в приложение. "Разрешения приложения" — это разрешения, предоставляемые приложению при запуске только от имени приложения.
Последний шаг — подключение сертификата, созданного ранее, к приложению. Щелкните "Сертификаты & секреты" в левой строке меню. Нажмите кнопку "Отправить сертификат" и выберите . CER-файл, созданный ранее, и нажмите кнопку "Добавить", чтобы отправить его.
Чтобы убедиться, что сертификат успешно зарегистрирован, щелкните "Манифест" в левой строке меню. Найдите свойство keyCredentials . Он должен выглядеть следующим образом:
"keyCredentials": [
{
"customKeyIdentifier": "<$base64CertHash>",
"endDate": "2021-05-01T00:00:00Z",
"keyId": "<$guid>",
"startDate": "2019-05-01T00:00:00Z",
"type": "AsymmetricX509Cert",
"usage": "Verify",
"value": "<$base64Cert>",
"displayName": "CN=<$name of your cert>"
}
],
Если вы видите раздел, похожий на этот, сертификат успешно добавлен.
В этом примере для разрешения приложения Sites.FullControl.All требуется согласие администратора в клиенте, прежде чем его можно будет использовать. Для этого снова щелкните "Разрешения API" в меню слева. В нижней части вы увидите раздел "Предоставление согласия". Нажмите кнопку "Предоставить согласие администратора для {{название организации}}" и подтвердите действие, нажав кнопку "Да" в верхней части окна.
Использование этого субъекта с PnP PowerShell
Если вы хотите использовать этот субъект "Только приложение AAD" с PnP PowerShell, после установки модуля PowerShell PnP вы можете подключиться к среде SharePoint Online с помощью следующих средств:
Connect-PnPOnline -ClientId <$application client id as copied over from the AAD app registration above> -CertificatePath '<$path to the PFX file generated by the PowerShell script above>' -CertificatePassword (ConvertTo-SecureString -AsPlainText "<$password assigned to the generated certificate pair above>" -Force) -Url https://<$yourtenant>.sharepoint.com -Tenant "<$tenantname>.onmicrosoft.com"
Теперь вы можете выполнять операции с помощью PnP PowerShell в среде SharePoint Online с помощью этого сертификата только доверие приложений.
Примечание.
PnP PowerShell — это решение с открытым исходным кодом, поддержка которого предоставляется активным сообществом. Для инструментов с открытым исходным кодом не существует соглашения об уровне обслуживания в отношении поддержки корпорацией Майкрософт.
Использование этого субъекта в приложении с помощью библиотеки SharePoint PnP Framework
На первом шаге добавьте пакет NuGet библиотеки PnP Framework: https://www.nuget.org/packages/PnP.Framework.
После этого можно использовать приведенную ниже конструкцию кода:
using PnP.Framework;
using System;
namespace AzureADCertAuth
{
class Program
{
static void Main(string[] args)
{
var authManager = new AuthenticationManager("<application id>", "c:\\temp\\mycert.pfx", "<password>", "contoso.onmicrosoft.com");
using (var cc = authManager.GetContext("https://contoso.sharepoint.com/sites/demo"))
{
cc.Load(cc.Web, p => p.Title);
cc.ExecuteQuery();
Console.WriteLine(cc.Web.Title);
};
}
}
}
Примечание.
PnP Framework — это решение с открытым кодом с активным сообществом, поддерживающим его. SLA для поддержки инструмента с открытым исходным кодом со стороны Майкрософт отсутствует.
Использование этого субъекта в скрипте PowerShell с помощью библиотеки PnP Framework
При использовании модулей Runbook служба автоматизации Azure сначала добавьте сертификат (PFX-файл), используя параметр Сертификаты (в разделе Общие ресурсы), а затем используйте командлет Get-AutomationCertificate, чтобы получить сертификат, который будет использоваться в скрипте.
Примечание.
Сначала необходимо добавить модуль PnP.Framework в учетную запись службы автоматизации. Этот модуль содержит все необходимое для выполнения вызова проверки подлинности.
# path to installed modules
$path = "C:\Modules\User\SharePointPnPPowerShellOnline"
# reference to needed assemblies
Add-Type -Path "$path\Microsoft.SharePoint.Client.dll"
Add-Type -Path "$path\Microsoft.SharePoint.Client.Runtime.dll"
Add-Type -Path "$path\PnP.Framework.dll"
Add-Type -Path "$path\PnP.Core.dll"
Add-Type -Path "$path\Microsoft.Identity.Client.dll"
# reference to the certificate
$cert = Get-AutomationCertificate -Name 'NameOfCertificate'
# set the variables
$siteUrl = "https://<tenant>.sharepoint.com"
$appId = "<guid of the App>"
$domain = "<tenant>.onmicrosoft.com"
$azureEnv = [PnP.Framework.AzureEnvironment]::Production
try {
# instantiate the object
$clientContext = $null
$authManager = new-object PnP.Framework.AuthenticationManager($appId, $cert, $domain, $null, $azureEnv)
# configure the object
$clientContext = $authManager.GetContext($siteUrl)
# do some stuff
$clientContext.Load($clientContext.Web)
$clientContext.ExecuteQuery()
$clientContext.Web.Title
}
catch {
# catch error if needed
}
finally {
$clientContext.Dispose()
}
Использование этого субъекта в приложении и использование Azure KeyVault для хранения сертификата и его получения с помощью функции Azure
Добавьте управляемое удостоверение в функцию Azure и предоставьте этому удостоверению доступ (разрешение GET на секреты) к KeyVault.
Ниже приведен немного другой вызов того же метода AuthenticationManager, в котором мы передаём фактический сертификат вместо пути к сертификату. Для получения сертификата из KeyVault с помощью управляемого удостоверения функции Azure добавляется дополнительная функция. Это простое и прозрачное извлечение, так как "магия" происходит в DefaultAzureCredential.
В этом примере используются две библиотеки для доступа к Key Vault:
- Azure.Identity для проверки подлинности в Key Vault
- Azure.Security.KeyVault.Secrets для получения сертификата
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Microsoft.SharePoint.Client;
using System.Security.Cryptography.X509Certificates;
using (var cc = new PnP.Framework.AuthenticationManager(
"<application id>",
GetKeyVaultCertificate("kv-spo", "AzureAutomationSPOAccess"),
"contoso.onmicrosoft.com").GetContext("https://contoso.sharepoint.com/sites/demo"))
{
cc.Load(cc.Web, p => p.Title);
cc.ExecuteQuery();
log.Info("Via PnP, we have site: " + cc.Web.Title);
};
static X509Certificate2 GetKeyVaultCertificate(string keyvaultName, string name)
{
// Some steps need to be taken to make this work
// 1. Create a KeyVault and upload the certificate
// 2. Give the Function App the permission to GET certificates via Access Policies in the KeyVault
// 3. Call an explicit access token request to the management resource to https://vault.azure.net and use the URL of our Keyvault in the GetSecret method
Uri keyVaultUri = new Uri($"https://{keyvaultName}.vault.azure.net/");
var client = new SecretClient(keyVaultUri, new DefaultAzureCredential());
KeyVaultSecret secret = client.GetSecret(name);
return new X509Certificate2(Convert.FromBase64String(secret.Value), string.Empty, X509KeyStorageFlags.MachineKeySet);
}
Использование этого субъекта со сканером модернизации Pnp
Теперь вы создали регистрацию приложений Azure Active Directory. Выполните приведенные здесь действия , чтобы использовать этот субъект со средством.
Вопросы и ответы
Можно ли использовать другие средства, помимо сертификатов, для реализации доступа только к приложению для моего приложения Azure AD?
Нет, все остальные параметры блокируются SharePoint Online и приводят к сообщению о запрете доступа.