Freigeben über

Austauschen eines ablaufenden geheimen Clientschlüssels in einem Add-In für SharePoint

  • Artikel

Clientschlüssel für SharePoint-Add-Ins, die mithilfe der AppRegNew.aspx-Seite registriert wurden, laufen nach einem Jahr ab. In diesem Artikel wird erläutert, wie Sie einen neuen geheimen Schlüssel für das Add-In hinzufügen und wie Sie einen neuen, für drei Jahre gültigen geheimen Client-Schlüssel erstellen.

Hinweis

Dieser Artikel enthält Informationen zu SharePoint-Add-Ins, die über einen Organisationskatalog verteilt werden und bei der Seite "AppRegNew.aspx" registriert sind. Wenn das Add-In auf dem Verkäuferdashboard registriert ist, finden Sie weitere Informationen unter Erstellen oder Aktualisieren von Client-IDs und geheimen Clientschlüsseln im Verkäuferdashboard.

Wir empfehlen, neue Geheimnisse mindestens 30 Tage vor ihrem Ablauf zu erstellen. Dadurch erhalten Sie einen Monat Zeit, bevor die alten Anmeldeinformationen ablaufen.

Wir empfehlen, Geheimnisse frühestens 7 Tage nach Ablauf zu entfernen, sofern Sie diese aus der Anwendungskonfiguration entfernt haben.

Das Entfernen eines abgelaufenen Geheimnisses aus ACS vor dem Entfernen aus der Anwendungskonfiguration wird zu Fehlern führen.

Voraussetzungen

Stellen Sie vor Beginn Folgendes sicher:

  • Der Microsoft Online Services-Anmeldeassistent ist auf dem Entwicklungscomputer installiert.
  • Sie können eine Verbindung zu Office 365 mit PowerShell herstellen: Verbinden mit Office 365 PowerShell
  • Sie sind der Mandantenadministrator für den Office 365-Mandanten (oder ein Farmadministrator der Farm), in der das Add-In mit der AppRegNew.aspx-Seite registriert wurde.

Ermitteln der Ablaufdaten des auf dem Office 365-Mandanten installierten SharePoint-Add-Inss

  1. Öffnen Sie Windows PowerShell und führen Sie folgendes Cmdlet aus:

    Connect-MsolService

  2. Geben Sie bei der Anmeldeaufforderung die Mandantenadministrator-Anmeldeinformationen (oder Farmadministrator) für die Office 365-Mandantschaft oder die Farm ein, auf der das Add-In mit der AppRegNew.aspx-Seite registriert wurde.

  3. Generieren Sie einen Bericht mit den folgenden Zeilen, in denen das jeweilige Add-In und das Datum, an dem ihr geheimer Schlüssel abläuft, aufgeführt sind. Beachten Sie zu diesem Code Folgendes:

    • Zunächst werden eigene Anwendungen von Microsoft und Add-Ins, die noch entwickelt werden, herausgefiltert.
    • Aus dem Rest werden Nicht-SharePoint-Add.Ins und Add-Ins, die asymmetrische Schlüssel verwenden, z. B. Workflows, herausgefiltert.
    $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. Öffnen Sie die Datei C:\temp\appsec.csv, um den Bericht anzuzeigen. Lassen Sie das Windows PowerShell-Fenster für das nächste Verfahren offen, wenn Schlüssel vorhanden sind, die bald ablaufen.

Generieren eines neuen geheimen Schlüssels

  1. Erstellen Sie eine Client-ID-Variable mit folgender Zeile, und verwenden Sie dafür die Client-ID des SharePoint-Add-Ins als Parameter.

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

  2. Generieren Sie mit den folgenden Zeilen einen neuen geheimen Clientschlüssel:

    $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. Der neue geheime Clientschlüssel wird auf die Windows PowerShell-Konsole angezeigt. Kopieren Sie ihn in eine Textdatei. Sie verwenden ihn im nächsten Verfahren.

    Tipp

    Standardmäßig sind geheime Add-In-Schlüssel ein Jahr gültig. Sie können diesen Zeitraum mit dem Parameter -EndDate der drei Aufrufe des Cmdlets New-MsolServicePrincipalCredential verkürzen oder verlängern.

Aktualisieren der Remote-Webanwendung in Visual Studio zum Verwenden des neuen geheimen Schlüssels

Wichtig

Wenn das Add-In ursprünglich mit einer Vorabversion des Microsoft Office Developer Tools für Visual Studio erstellt wurde, kann es eine veraltete Version der Datei TokenHelper.cs (oder .vb) enthalten. Wenn die Datei nicht die Zeichenfolge "SecondaryClientSecret" enthält, ist sie veraltet und muss ersetzt werden, bevor Sie die Webanwendung mit einem neuen Schlüssel aktualisieren können. Sie benötigen Visual Studio 2012 oder höher, um eine Kopie der Veröffentlichungsversion der Datei erhalten zu können. Erstellen Sie ein neues SharePoint-Add-In-Projekt in Visual Studio. Kopieren Sie die TokenHelper-Datei in das Webanwendungsprojekt Ihres SharePoint-Add-Ins.

  1. Öffnen Sie das SharePoint-Add-In-Projekt in Visual Studio, und öffnen Sie die Datei web.config für das Webanwendungsprojekt. Im Abschnitt appSettings finden Sie Schlüssel für die Client-ID und den geheimen Clientschlüssel. Es folgt ein Beispiel:

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

  2. Ändern Sie den Namen des ClientSecret-Schlüssels in SecondaryClientSecret wie im folgenden Beispiel:

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

    Hinweis

    Wenn Sie dieses Verfahren zum ersten Mal durchführen, ist zu diesem Zeitpunkt in der Konfigurationsdatei kein SecondaryClientSecret-Eigenschaftseintrag vorhanden. Wenn Sie das Verfahren für einen nachfolgenden (zweiten oder dritten) Ablauf eines geheimen Clientschlüssels durchführen, ist die Eigenschaft SecondaryClientSecret bereits vorhanden und enthält den ursprünglichen oder abgelaufenen alten Schlüssel. Löschen Sie in diesem Fall zuerst die Eigenschaft SecondaryClientSecret, bevor Sie ClientSecret umbenennen.

  3. Fügen Sie einen neuen ClientSecret-Schlüssel hinzu und übergeben Sie den neuen geheimen Clientschlüssel. Ihr Markup sollte wie folgt aussehen:

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

    Wichtig

    Sie können den neu generierten geheimen Clientschlüssel erst verwenden, nachdem der aktuelle geheime Clientschlüssel abgelaufen ist. Daher ist es nicht möglich, den Client-ID-Schlüssel ohne den vorhandenen SecondaryClientSecret-Schlüssel in den neuen geheimen Clientschlüssel zu ändern. Sie müssen das Verfahren in diesem Artikel befolgen und warten, bis der vorherige geheime Clientschlüssel abläuft. Sie können dann den SecondaryClientSecret entfernen, wenn Sie möchten.

  4. Wenn Sie zu einer neuen „TokenHelper“-Datei gewechselt haben, müssen Sie das Projekt neu erstellen.

  5. Veröffentlichen Sie die Webanwendung erneut.

Erstellen eines Client-Schlüssels, der drei Jahre gültig ist

Für abgelaufene Clientschlüssel müssen Sie zunächst alle abgelaufenen Schlüssel für eine bestimmte ClientId löschen. Sie erstellen dann einen neuen mit MSOPowerShell, warten mindestens 24 Stunden, und testen die App mit der neuen ClientId und dem ClientSecret-Schlüssel.

  1. Stellen Sie eine Verbindung mit MSOnline anhand des Mandanten-Admininistratorbenutzers und dem folgenden Markup her, indem Sie SharePoint Windows PowerShell verwenden.

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

  2. Abrufen von ServicePrincipals und Schlüsseln. Durch das Drucken von $keys werden drei Datensätze zurückgegeben. Außerdem wird Ihnen das EndDate der einzelnen Schlüssel angezeigt. Vergewissern Sie sich, dass dort Ihre abgelaufenen Schlüssel angezeigt werden.

    Hinweis

    Die ClientId muss mit Ihrer abgelaufenen ClientId übereinstimmen. Es wird empfohlen, alle abgelaufenen und nicht abgelaufenen Schlüssel für diese ClientId zu löschen.

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

  3. Entfernen Sie alle Schlüssel, sobald Sie überprüft haben, dass sie tatsächlich abgelaufen sind.

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

  4. Generieren eines neuen ClientSecret für diese ClientID. Es wird die gleichen ClientId wie im vorherigen Schritt eingerichtet. Der neue ClientSecret ist 3 Jahre gültig.

    $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. Kopieren Sie die Ausgabe des $newClientSecret.

  6. Ersetzen Sie die Web.config durch diese ClientId und ClientSecret. Sie benötigen nicht die SecondaryClientSecret -App-Einstellungen.

  7. Warten Sie mindestens 24 Stunden mit dem Auffüllen des ClientSecret in SharePoint Office (SPO).

Weitere Artikel