Freigeben über


Update servicePrincipal

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Aktualisieren Sie die Eigenschaften des servicePrincipal-Objekts.

Wichtig

Die Verwendung von PATCH zum Festlegen vob passwordCredential wird nicht unterstützt. Verwenden Sie die addPassword- und removePassword-Methoden zum Aktualisieren des Kennworts für einen servicePrincipal.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Application.ReadWrite.All Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Application.ReadWrite.OwnedBy Application.ReadWrite.All, Directory.ReadWrite.All

Hinweis

  • So aktualisieren Sie die customSecurityAttributes-Eigenschaft :
    • In delegierten Szenarien muss dem Administrator die Rolle Attributzuweisungsadministrator zugewiesen werden, und der App muss die delegierte Berechtigung CustomSecAttributeAssignment.ReadWrite.All gewährt werden.
    • In reinen App-Szenarien, die Microsoft Graph-Berechtigungen verwenden, muss der App die Anwendungsberechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden.

HTTP-Anforderung

Sie können den Dienstprinzipal entweder mit seiner ID oder appId adressieren. id und appId werden in App-Registrierungen im Microsoft Entra Admin Center als Objekt-ID bzw. Anwendungs-ID (Client-ID) bezeichnet.

PATCH /servicePrincipals/{id}
PATCH /servicePrincipals(appId='{appId}')

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
Content-Type application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext die Werte für die relevanten Felder an, die aktualisiert werden sollen. Vorhandene Eigenschaften, die nicht im Anforderungstext enthalten sind, behalten ihre vorherigen Werte bei oder werden basierend auf Änderungen an anderen Eigenschaftswerten neu berechnet. Aus Gründen der Leistung sollten Sie vorhandene Werte, die nicht geändert wurden, nicht angeben.

Eigenschaft Typ Beschreibung
accountEnabled Boolescher Wert True, wenn das Dienstprinzipalkonto aktiviert ist; andernfalls false.
addIns addIn Definiert benutzerdefiniertes Verhalten, das von einem Verbraucherdienst verwendet werden kann, um eine App in bestimmten Kontexten aufzurufen. Beispielsweise können Anwendungen, die Datei-Streams rendern können, die addIns-Eigenschaft für deren "FileHandler"-Funktionalität festlegen. Dadurch können Dienste wie Microsoft 365 die Anwendung im Kontext eines Dokuments aufrufen, an dem der Benutzer arbeitet.
alternativeNames Zeichenfolgenauflistung Wird zum Abrufen von Dienstprinzipalen nach Abonnement und zum Identifizieren von Ressourcengruppen und vollständigen Ressourcen-IDs für verwaltete Identitäten verwendet.
appRoleAssignmentRequired Boolesch Gibt an, ob ein appRoleAssignment für einen Benutzer oder eine Gruppe erforderlich ist, bevor Microsoft Entra ID einen Benutzer oder ein Zugriffstoken für die Anwendung ausgibt. Lässt keine Nullwerte zu.
appRoles appRole-Auflistung Die von der verknüpften Anwendung verfügbar gemachten Anwendungsrollen. Weitere Informationen finden Sie in der AppRoles-Eigenschaftsdefinition für die Anwendungsressource . Lässt keine NULL-Werte zu.
customSecurityAttributes customSecurityAttributeValue Ein offener komplexer Typ, der den Wert eines benutzerdefinierten Sicherheitsattributs enthält, das einem Verzeichnisobjekt zugewiesen ist.
  • Um diese Eigenschaft in delegierten Szenarien zu aktualisieren, muss dem aufrufenden Prinzipal die Rolle Attributzuweisungsadministrator zugewiesen werden, und der App muss die delegierte Berechtigung CustomSecAttributeAssignment.ReadWrite.All gewährt werden.
  • Um diese Eigenschaft in reinen App-Szenarien mit Microsoft Graph-Berechtigungen zu aktualisieren, muss der App die Anwendungsberechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden.
  • displayName Zeichenfolge Der Anzeigename für den Dienstprinzipal.
    homepage String Startseite der Anwendung.
    keyCredentials keyCredential-Auflistung Die Auflistung der wichtigsten Anmeldeinformationen, die mit dem Dienstprinzipal verknüpft sind. Lässt keine Nullwerte zu.
    loginUrl Zeichenfolge Gibt die URL an, unter der der Dienstanbieter den Benutzer an Microsoft Entra ID umleitet, um sich zu authentifizieren. Microsoft Entra ID verwendet die URL, um die Anwendung aus Microsoft 365 oder dem Microsoft Entra Meine Apps zu starten. Wenn leer, führt Microsoft Entra ID idP-initiierte Anmeldung für Anwendungen aus, die mit SAML-basiertem einmaligem Anmelden konfiguriert sind. Der Benutzer startet die Anwendung über Microsoft 365, die Microsoft Entra Meine Apps oder die Microsoft Entra SSO-URL.
    logoutUrl Zeichenfolge Gibt die URL an, die vom Autorisierungsdienst von Microsoft verwendet wird, um einen Benutzer mithilfe von Front-Channel-, Back-Channel- oder SAML-Abmeldungsprotokollen abzumelden.
    notificationEmailAddresses Zeichenfolgenauflistung Gibt die Liste der E-Mail-Adressen an, an die Microsoft Entra ID eine Benachrichtigung sendet, wenn sich das aktive Zertifikat dem Ablaufdatum nähert. Dies gilt nur für die Zertifikate, die zum Signieren des SAML-Tokens verwendet werden, das für Microsoft Entra Gallery-Anwendungen ausgestellt wurde.
    publishedPermissionScopes permissionScope-Sammlung Die von der verknüpften Anwendung verfügbar gemachten OAuth 2.0-Berechtigungen. Weitere Informationen finden Sie in der oauth2PermissionScopes-Eigenschaftsdefinition für die Anwendungsressource . Lässt keine NULL-Werte zu.
    preferredSingleSignOnMode Zeichenfolge Gibt den Modus für einmaliges Anmelden an, der für diese Anwendung konfiguriert ist. Microsoft Entra ID verwendet den bevorzugten Modus für einmaliges Anmelden, um die Anwendung über Microsoft 365 oder die Microsoft Entra Meine Apps zu starten. Die unterstützten Werte sind Kennwort, SAML, extern und oidc.
    preferredTokenSigningKeyEndDateTime DateTimeOffset Gibt das Ablaufdatum für die „keyCredentials“ an, die für die Tokensignatur verwendet werden, gekennzeichnet durch preferredTokenSigningKeyThumbprint.
    preferredTokenSigningKeyThumbprint Zeichenfolge Nur für die interne Verwendung reserviert. Schreiben Sie diese Eigenschaft nicht oder verlassen Sie sich anderweitig auf diese Eigenschaft. Sie kann in zukünftigen Versionen möglicherweise entfernt werden.
    publisherName Zeichenfolge Der Anzeigename des Mandanten, in dem verknüpfte Anwendung angegeben wird.
    replyUrls Zeichenfolgenauflistung Die URLs, an die Benutzertoken zur Anmeldung bei der verknüpften Anwendung gesendet werden, oder die Umleitungs-URIs, an die die OAuth 2.0-Autorisierungscodes und Zugriffstoken für die verknüpfte Anwendung gesendet werden. Lässt keine Nullwerte zu.
    samlSingleSignOnSettings samlSingleSignOnSettings Die Sammlung für Einstellungen im Zusammenhang mit der einmaligen SAML-Anmeldung.
    servicePrincipalNames Zeichenfolgenauflistung Enthält die Liste der identifiersUris-, die aus der zugehörigen Anwendung kopiert werden. Hybridanwendungen können zusätzliche Werte hinzugefügt werden. Diese Werte können verwendet werden, um die Berechtigungen zu identifizieren, die von dieser App innerhalb Microsoft Entra ID verfügbar gemacht werden. Beispiel:
    • Client-Apps, die Berechtigungen für diese Ressource anfordern, können diese URIs verwenden, um die erforderlichen Berechtigungen in der requiredResourceAccess-Eigenschaft des Anwendungsmanifests oder im Blatt „API-Berechtigungen“ in der App-Registrierungsoberfläche anzugeben.
    • Client-Apps können einen Ressourcen-URI angeben, der auf den Werten dieser Eigenschaft basiert, um ein Zugriffstoken abzurufen. Dabei handelt es sich um den URI, der im Anspruch "aud" zurückgegeben wird.

    Der "any"-Operator ist für Filterausdrücke für mehrwertige Eigenschaften erforderlich. Lässt keine NULL-Werte zu.
    tags Zeichenfolgenauflistung Lässt keine NULL-Werte zu.
    tokenEncryptionKeyId Zeichenfolge Gibt die keyId eines öffentlichen Schlüssels aus der keyCredentials-Sammlung an. Nach der Konfiguration gibt Microsoft Entra ID Token für diese Anwendung aus, die mit dem von dieser Eigenschaft angegebenen Schlüssel verschlüsselt wurden. Der Anwendungscode, der das verschlüsselte Token erhält, muss das Token mit dem zugehörigen privaten Schlüssel entschlüsseln, bevor es für den angemeldeten Benutzer verwendet werden kann.

    Antwort

    Wenn die Methode erfolgreich verläuft, werden der Antwortcode 204 No Content und ein aktualisiertes servicePrincipal-Objekt im Antworttext zurückgegeben.

    Beispiele

    Beispiel 1: Aktualisieren der Eigenschaften des angegebenen Dienstprinzipals

    Anforderung

    Das folgende Beispiel zeigt eine Anfrage.

    PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
    Content-type: application/json
    
    {
      "appRoleAssignmentRequired": true
    }
    

    Antwort

    Das folgende Beispiel zeigt die Antwort. Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt sein.

    HTTP/1.1 204 No Content
    

    Beispiel 2: Zuweisen eines benutzerdefinierten Sicherheitsattributs mit einem Zeichenfolgenwert zu einem Dienstprinzipal

    Das folgende Beispiel zeigt, wie einem Dienstprinzipal ein benutzerdefiniertes Sicherheitsattribut mit einem Zeichenfolgenwert zugewiesen wird.

    • Attributsatz: Engineering
    • Attribut: ProjectDate
    • Attributdatentyp: Zeichenfolge
    • Attributwert: "2022-10-01"

    Um benutzerdefinierte Sicherheitsattribute zuzuweisen, muss dem aufrufenden Prinzipal die Rolle "Attributzuweisungsadministrator" zugewiesen werden, und dem aufrufenden Prinzipal muss die Berechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden.

    Weitere ähnliche Beispiele für Benutzer finden Sie unter Beispiele: Zuweisen, Aktualisieren, Auflisten oder Entfernen von benutzerdefinierten Sicherheitsattributen mithilfe des Microsoft Graph-API.

    Anforderung

    PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
    Content-type: application/json
    
    {
        "customSecurityAttributes":
        {
            "Engineering":
            {
                "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
                "ProjectDate":"2022-10-01"
            }
        }
    }
    

    Antwort

    HTTP/1.1 204 No Content