Freigeben über

Gewähren des Nur-App-Zugriffs über Azure AD

  • Artikel

Bei Verwendung von SharePoint Online können Sie Anwendungen in Azure AD definieren. Diesen Anwendungen können Berechtigungen für SharePoint gewährt werden, aber auch für alle anderen Dienste in Office 365. Dieses Modell ist das bevorzugte Modell für den Fall, dass Sie SharePoint Online verwenden. Wenn Sie SharePoint lokal verwenden, müssen Sie das nur SharePoint-Modell über basierendes Azure ACS verwenden, wie hier beschrieben.

Wichtig

Die Verwendung von Azure ACS (Access Control Services) für SharePoint Online wurde am 27. November 2023 eingestellt. Weitere Informationen finden Sie in der Ankündigung zur vollständigen Einstellung. Die Verwendung von Azure ACS außerhalb des SharePoint-Kontexts wurde bereits am 7. November 2018 eingestellt und endet jetzt.

Die Einstellung bedeutet, dass das Feature keine neuen Investitionen erhält, aber weiterhin unterstützt wird. Ende der Lebensdauer bedeutet, dass das Feature nicht mehr zur Verfügung steht.

Einrichten einer Azure AD-App für den reinen App-Zugriff

In Azure AD verwenden Sie in der Regel ein Zertifikat, um Den Zugriff anzufordern: Jeder Benutzer, der über das Zertifikat und seinen privaten Schlüssel verfügt, kann die App und die der App gewährten Berechtigungen verwenden. Die folgenden Schritte führen Sie durch die Einrichtung dieses Modells.

Sie können jetzt die Azure AD-Anwendung für den Aufruf von SharePoint Online mit einem Zugriffstoken nur app konfigurieren. Dazu müssen Sie ein selbstsigniertes X.509-Zertifikat erstellen und konfigurieren, das zur Authentifizierung Ihrer Anwendung bei Azure AD verwendet wird, während sie das Zugriffstoken nur app anfordern. Zuerst müssen Sie das selbstsignierte X.509-Zertifikat erstellen, das mit dem im Windows SDK verfügbaren makecert.exe Tool erstellt werden kann, über ein bereitgestelltes PowerShell-Skript, das keine Abhängigkeit von makecert aufweist, oder mit einem PnP PowerShell-Befehl. Die Verwendung des PowerShell-Skripts ist die bevorzugte Methode und wird in diesem Kapitel erläutert.

Wichtig

Es ist wichtig, dass Sie die folgenden Skripts mit Administratorrechten ausführen.

So erstellen Sie ein selbstsigniertes Zertifikat mit diesem Skript:

.\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate 2017-10-01 -EndDate 2019-10-01

Hinweis

Die Datumsangaben werden im ISO-Datumsformat angegeben: JJJJ-MM-tt

Die Zertifikatschlüsselalgoritm muss RSA sein. Dies ist derzeit der einzige unterstützte Algorithmus.

Das eigentliche Skript kann hier kopiert werden:

#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
}

Sie werden aufgefordert, ein Kennwort zum Verschlüsseln Ihres privaten Schlüssels und sowohl den - als auch den - zu geben. PFX-Datei und . Die CER-Datei wird in den aktuellen Ordner exportiert.

Hinweis

Das selbstsignierte Zertifikat kann auch über den Befehl New-PnPAzureCertificate generiert werden.

Der nächste Schritt ist die Registrierung einer Azure AD-Anwendung im Azure Active Directory-Mandanten, die mit Ihrem Office 365 Mandanten verknüpft ist. Öffnen Sie dazu das Office 365 Admin Center (https://admin.microsoft.com) mithilfe des Kontos eines Benutzermitglieds der Gruppe "Globale Mandantenadministratoren". Klicken Sie auf den Link "Azure Active Directory", der unter der Gruppe "Admin Center" in der linken Strukturansicht des Office 365 Admin Center verfügbar ist. Auf der Registerkarte des neuen Browsers, die geöffnet wird, finden Sie die Microsoft-Azure-Portal. Wenn Sie zum ersten Mal mit Ihrem Konto auf die Azure-Portal zugreifen, müssen Sie ein neues Azure-Abonnement registrieren und einige Informationen und eine Gutschrift Karte für alle Zahlungsanforderung bereitstellen. Aber keine Sorge, um mit Azure AD zu spielen und eine Office 365-Anwendung zu registrieren, zahlen Sie nichts. Tatsächlich handelt es sich dabei um kostenlose Funktionen. Nachdem Sie Zugriff auf die Azure-Portal haben, wählen Sie den Abschnitt "Azure Active Directory" und dann die Option "App-Registrierungen" aus. Weitere Details finden Sie in der nächsten Abbildung.

Zeigt das Azure Ad-Portal an

Auf der Registerkarte "App-Registrierungen" finden Sie die Liste der in Ihrem Mandanten registrierten Azure AD-Anwendungen. Klicken Sie oben links auf dem Blatt auf die Schaltfläche "Neue Registrierung". Geben Sie als Nächstes einen Namen für Ihre Anwendung an, und klicken Sie unten auf dem Blatt auf "Registrieren".

erstellt eine neue Azure AD-Anwendung.

Wichtig

Nachdem die Anwendung erstellt wurde, kopieren Sie die "Anwendungs-ID (Client)", da Sie sie später benötigen.

Klicken Sie nun in der linken Menüleiste auf "API-Berechtigungen" und dann auf die Schaltfläche "Berechtigung hinzufügen". Ein neues Blatt wird angezeigt. Hier wählen Sie die Berechtigungen aus, die Sie dieser Anwendung gewähren. Wählen Sie z. B.:

  • SharePoint
    • Anwendungsberechtigungen
      • Websites
        • Sites.FullControl.All

Klicken Sie unten auf die blaue Schaltfläche "Berechtigungen hinzufügen", um die Berechtigungen zu Ihrer Anwendung hinzuzufügen. Die "Anwendungsberechtigungen" sind diejenigen, die der Anwendung gewährt werden, wenn sie nur als App ausgeführt wird.

Erteilen von Berechtigungen für die Azure AD-Anwendung

Der letzte Schritt besteht darin, das zuvor erstellte Zertifikat mit der Anwendung zu verbinden. Klicken Sie in der linken Menüleiste auf "Zertifikate & Geheimnisse". Klicken Sie auf die Schaltfläche "Zertifikat hochladen", und wählen Sie aus. CER-Datei, die Sie zuvor generiert haben, und klicken Sie auf "Hinzufügen", um sie hochzuladen.

Um zu bestätigen, dass das Zertifikat erfolgreich registriert wurde, klicken Sie in der linken Menüleiste auf "Manifest". Suchen Sie nach der keyCredentials-Eigenschaft . Sie sollte wie folgt aussehen:

  "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>"
     }
  ],

Wenn ein Abschnitt ähnlich aussieht, wurde das Zertifikat erfolgreich hinzugefügt.

In diesem Beispiel erfordert die Anwendungsberechtigung Sites.FullControl.All die Administratoreinwilligung in einem Mandanten, bevor sie verwendet werden kann. Klicken Sie dazu im linken Menü erneut auf "API-Berechtigungen". Unten sehen Sie den Abschnitt "Einwilligung erteilen". Klicken Sie auf die Schaltfläche "Erteilen der Administratoreinwilligung für {{organization name}}", und bestätigen Sie die Aktion, indem Sie oben auf die Schaltfläche "Ja" klicken.

Erteilen von API-Berechtigungen für die Azure AD-Anwendung

Verwenden dieses Prinzipals mit PnP PowerShell

Wenn Sie diesen AAD-App-Prinzipal mit PnP PowerShell verwenden möchten, können Sie nach der Installation des PnP PowerShell-Moduls eine Verbindung mit Ihrer SharePoint Online-Umgebung herstellen:

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"

Sie können jetzt Vorgänge über PnP PowerShell für Ihre SharePoint Online-Umgebung ausführen, indem Sie diese Zertifikatvertrauensstellung nur app verwenden.

Hinweis

PnP PowerShell ist eine Open Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Verwenden dieses Prinzips in Ihrer Anwendung mithilfe der SharePoint PnP Framework-Bibliothek

In einem ersten Schritt fügen Sie das NuGet-Paket der PnP Framework-Bibliothek hinzu: https://www.nuget.org/packages/PnP.Framework.

Anschließend können Sie das folgende Codekonstrukt verwenden:

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);
            };
        }
    }
}

Hinweis

PnP Framework ist eine Open-Source-Lösung mit aktiver Community, die Unterstützung dafür bereitstellt. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Verwenden dieses Prinzipals in Ihrem PowerShell-Skript mithilfe der PnP Framework-Bibliothek

Wenn Sie Azure Automation Runbooks verwenden, fügen Sie zuerst das Zertifikat (PFX) mithilfe der Option Zertifikate (unter Freigegebene Ressourcen) hinzu, und verwenden Sie dann das Cmdlet Get-AutomationCertificate, um das Zertifikat abzurufen, das im Skript verwendet werden soll.

Hinweis

Sie müssen das Modul PnP.Framework zuerst Ihrem Automation-Konto hinzufügen. Dieses Modul enthält alles, was zum Durchführen des Authentifizierungsaufrufs erforderlich ist.

# 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()
}

Verwenden dieses Prinzipals in Ihrer Anwendung und Verwenden von Azure KeyVault zum Speichern des Zertifikats und Abrufen des Zertifikats mithilfe einer Azure-Funktion

Fügen Sie der Azure-Funktion eine verwaltete Identität hinzu, und gewähren Sie dieser Identität Zugriff (GET-Berechtigung für Geheimnisse) auf KeyVault.

Unten befindet sich ein etwas anderer Aufruf der gleichen AuthenticationManager-Methode, bei der anstelle eines Pfads zum Zertifikat ein tatsächliches Zertifikat übergeben wird. Eine zusätzliche Funktion wird hinzugefügt, um das Zertifikat aus dem KeyVault mithilfe der verwalteten Identität der Azure-Funktion abzurufen. Dieser Abruf ist nahtlos und transparent, da die "Magic" in DefaultAzureCredential erfolgt.

In diesem Beispiel werden zwei Bibliotheken verwendet, um auf die Key Vault zuzugreifen:

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);
}

Verwenden dieses Prinzips mit dem Pnp-Modernisierungsscanner

Nachdem Sie die Azure Active Directory-Anwendungsregistrierung erstellt haben, fahren Sie mit den hier beschriebenen Schritten fort, um diesen Prinzipal mit dem Tool zu verwenden.

Häufig gestellte Fragen

Kann ich neben Zertifikaten auch andere Mittel verwenden, um den Zugriff nur auf Apps für meine Azure AD-App zu realisieren?

Nein, alle anderen Optionen werden von SharePoint Online blockiert und führen zu einer Meldung Zugriff verweigert.