Verwalten von benutzerdefinierten Sicherheitsattributen

Benutzerdefinierte Sicherheitsattribute in Microsoft Entra ID sind geschäftsspezifische Attribute (Schlüssel-Wert-Paare), die Sie definieren und Microsoft Entra Objekten zuweisen können. Diese Attribute können verwendet werden, um Informationen zu speichern, Objekte zu kategorisieren oder eine differenzierte Zugriffssteuerung für bestimmte Azure-Ressourcen über azure attribute-based access control (Azure ABAC) zu erzwingen.

Benutzerdefinierte Sicherheitsattribute werden nur für Benutzer und Dienstprinzipale unterstützt. Dieser Artikel enthält Beispiele zum Zuweisen, Aktualisieren, Auflisten oder Entfernen verschiedener Typen von benutzerdefinierten Sicherheitsattributen für Benutzer und Anwendungen mit Microsoft Graph.

Voraussetzungen

  • Erstellen benutzerdefinierter Sicherheitsattribute. Weitere Informationen zum Definieren und Verwalten von benutzerdefinierten Sicherheitsattributen finden Sie unter Übersicht über benutzerdefinierte Sicherheitsattribute mit Microsoft Graph.
  • In delegierten Szenarien müssen dem Aufruf die folgenden Berechtigungen und Administratorrollen zugewiesen werden.
    • So weisen Sie zu, aktualisieren oder entfernen:
      • Microsoft Entra Rollen: Attributzuweisungsadministrator
      • Microsoft Graph-Berechtigungen:
        • Benutzer: CustomSecAttributeAssignment.ReadWrite.All und User.Read.All
        • Dienstprinzipale: CustomSecAttributeAssignment.ReadWrite.All und Application.Read.All
    • in:

Zuweisen benutzerdefinierter Sicherheitsattribute

Beispiel 1: Zuweisen eines benutzerdefinierten Sicherheitsattributes mit einem Zeichenfolgenwert zu einem Benutzer

Das folgende Beispiel zeigt, wie Sie die Update-Benutzer-API verwenden, um einem Benutzer ein benutzerdefiniertes Sicherheitssattribut mit einem Zeichenfolgenwert zuzuweisen.

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

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

Antwort

HTTP/1.1 204 No Content

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

Das folgende Beispiel zeigt, wie Sie die Update servicePrincipal-API verwenden, um einem Dienstprinzipal ein benutzerdefiniertes Sicherheitssattribut mit einem Zeichenfolgenwert zuzuweisen.

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

Anforderung

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Beispiel 3: Zuweisen eines benutzerdefinierten Sicherheitsattributes mit einem Wert mit mehreren Zeichenfolgen zu einem Benutzer

Das folgende Beispiel zeigt, wie Sie die Benutzeraktualisierungs-API verwenden, um einem Benutzer ein benutzerdefiniertes Sicherheitssattribut mit einem Multizeichenfolgenwert zuzuweisen.

  • Attributsatz: Engineering
  • Attribut: Project
  • Attributdatentyp: Auflistung von Zeichenfolgen
  • Attributwert: ["Baker","Cascade"]

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Project@odata.type":"#Collection(String)",
            "Project":["Baker","Cascade"]
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Beispiel 4: Zuweisen eines benutzerdefinierten Sicherheitsattributes mit einem ganzzahligen Wert zu einem Benutzer

Das folgende Beispiel zeigt, wie Sie die Benutzeraktualisierungs-API verwenden, um einem Benutzer ein benutzerdefiniertes Sicherheitssattribut mit einem ganzzahligen Wert zuzuweisen.

  • Attributsatz: Engineering
  • Attribut: NumVendors
  • Attributdatentyp: Integer
  • Attributwert: 4

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "NumVendors@odata.type":"#Int32",
            "NumVendors":4
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Beispiel 5: Zuweisen eines benutzerdefinierten Sicherheitsattributes mit einem Multi-Integer-Wert zu einem Benutzer

Das folgende Beispiel zeigt, wie Sie die Benutzeraktualisierungs-API verwenden, um einem Benutzer ein benutzerdefiniertes Sicherheitssattribut mit einem Multi-Integer-Wert zuzuweisen.

  • Attributsatz: Engineering
  • Attribut: CostCenter
  • Attributdatentyp: Sammlung von ganzzahligen Zahlen
  • Attributwert: [1001,1003]

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "CostCenter@odata.type":"#Collection(Int32)",
            "CostCenter":[1001,1003]
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Beispiel 6: Zuweisen eines benutzerdefinierten Sicherheitsattributes mit einem booleschen Wert zu einem Benutzer

Das folgende Beispiel zeigt, wie Sie die Benutzeraktualisierungs-API verwenden, um einem Benutzer ein benutzerdefiniertes Sicherheitsattribute mit einem booleschen Wert zuzuweisen.

  • Attributsatz: Engineering
  • Attribut: Certification
  • Attributdatentyp: Boolesch
  • Attributwert: true

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Certification":true
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Aktualisieren von benutzerdefinierten Sicherheitsattributen

Beispiel 1: Aktualisieren einer benutzerdefinierten Sicherheitsattributezuweisung mit einem ganzzahligen Wert für einen Benutzer

Das folgende Beispiel zeigt, wie Sie mithilfe der Benutzeraktualisierungs-API eine benutzerdefinierte Sicherheitsattributezuweisung mit einem ganzzahligen Wert für einen Benutzer aktualisieren.

  • Attributsatz: Engineering
  • Attribut: NumVendors
  • Attributdatentyp: Integer
  • Attributwert: 8

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "NumVendors@odata.type":"#Int32",
            "NumVendors":8
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Beispiel 2: Aktualisieren einer benutzerdefinierten Sicherheitsattributezuweisung mit einem booleschen Wert für einen Benutzer

Das folgende Beispiel zeigt, wie Sie die Benutzeraktualisierungs-API verwenden, um eine benutzerdefinierte Sicherheitsattributezuweisung mit einem booleschen Wert für einen Benutzer zu aktualisieren.

  • Attributsatz: Engineering
  • Attribut: Certification
  • Attributdatentyp: Boolesch
  • Attributwert: false

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Certification":false
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Auflisten von benutzerdefinierten Sicherheitsattributen

Beispiel 1: Abrufen der benutzerdefinierten Sicherheitsattribute für einen Benutzer

Im folgenden Beispiel wird gezeigt, wie sie die GET USER-API verwenden, um die benutzerdefinierten Sicherheitsattribute für einen Benutzer abzurufen.

Attribut Nr. 1

  • Attributsatz: Engineering
  • Attribut: Project
  • Attributdatentyp: Auflistung von Zeichenfolgen
  • Attributwert: ["Baker","Cascade"]

Attribut Nr. 2

  • Attributsatz: Engineering
  • Attribut: CostCenter
  • Attributdatentyp: Sammlung von ganzzahligen Zahlen
  • Attributwert: [1001]

Attribut Nr. 3

  • Attributsatz: Engineering
  • Attribut: Certification
  • Attributdatentyp: Boolesch
  • Attributwert: true

Attribut Nr. 4

  • Attributsatz: Marketing
  • Attribut: EmployeeId
  • Attributdatentyp: Zeichenfolge
  • Attributwert: "QN26904"

Anforderung

GET https://graph.microsoft.com/v1.0/users/{id}?$select=customSecurityAttributes

Antwort

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "EmployeeId": "QN26904"
        },
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        }
    }
}

Wenn dem Benutzer keine benutzerdefinierten Sicherheitsattribute zugewiesen sind oder der aufrufende Prinzipal keinen Zugriff hat, lautet die Antwort wie folgt:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}

Beispiel 2: Auflisten aller Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung, die einem Wert entspricht

Im folgenden Beispiel wird gezeigt, wie Sie die API zum Auflisten von Benutzern verwenden, um alle Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung aufzulisten, die einem Wert entspricht. Im Beispiel werden Benutzer mit einem benutzerdefinierten Sicherheitsattribute namens AppCountry mit einem Wert abgerufen, der gleich ist Canada. Beim Filterwert wird die Groß-/Kleinschreibung beachtet. Sie müssen in der Anforderung oder im Header hinzufügen ConsistencyLevel=eventual . Sie müssen auch einschließen $count=true , um sicherzustellen, dass die Anforderung ordnungsgemäß weitergeleitet wird.

Benutzer Nr. 1

  • Attributsatz: Marketing
  • Attribut: AppCountry
  • Attributdatentyp: Auflistung von Zeichenfolgen
  • Attributwert: ["India","Canada"]

Benutzer 2

  • Attributsatz: Marketing
  • Attribut: AppCountry
  • Attributdatentyp: Auflistung von Zeichenfolgen
  • Attributwert: ["Canada","Mexico"]

Anforderung

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry eq 'Canada'
ConsistencyLevel: eventual

Antwort

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 2,
    "value": [
        {
            "id": "dbaf3778-4f81-4ea0-ac1c-502a293c12ac",
            "displayName": "Jiya",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Datacenter@odata.type": "#Collection(String)",
                    "Datacenter": [
                        "India"
                    ]
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "India",
                        "Canada"
                    ],
                    "EmployeeId": "KX19476"
                }
            }
        },
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Beispiel 3: Auflisten aller Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung, die mit einem Wert beginnt

Das folgende Beispiel zeigt, wie Sie die API zum Auflisten von Benutzern verwenden, um alle Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung aufzulisten, die mit einem Wert beginnt. Im Beispiel werden Benutzer mit einem benutzerdefinierten Sicherheitsattribute namens EmployeeId mit einem Wert abgerufen, der mit GSbeginnt. Beim Filterwert wird die Groß-/Kleinschreibung beachtet. Sie müssen in der Anforderung oder im Header hinzufügen ConsistencyLevel=eventual . Sie müssen auch einschließen $count=true , um sicherzustellen, dass die Anforderung ordnungsgemäß weitergeleitet wird.

Benutzer Nr. 1

  • Attributsatz: Marketing
  • Attribut: EmployeeId
  • Attributdatentyp: Zeichenfolge
  • Attributwert: "KX19476"

Benutzer 2

  • Attributsatz: Marketing
  • Attribut: EmployeeId
  • Attributdatentyp: Zeichenfolge
  • Attributwert: "GS46982"

Anforderung

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')
ConsistencyLevel: eventual

Antwort

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 1,
    "value": [
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Beispiel 4: Auflisten aller Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung, die nicht einem Wert entspricht

Im folgenden Beispiel wird gezeigt, wie Sie die API zum Auflisten von Benutzern verwenden, um alle Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung aufzulisten, die nicht einem Wert entspricht. Im Beispiel werden Benutzer mit einem benutzerdefinierten Sicherheitsattribute namens AppCountry mit einem Wert abgerufen, der ungleich ist Canada. Beim Filterwert wird die Groß-/Kleinschreibung beachtet. Sie müssen in der Anforderung oder im Header hinzufügen ConsistencyLevel=eventual . Sie müssen auch einschließen $count=true , um sicherzustellen, dass die Anforderung ordnungsgemäß weitergeleitet wird.

Benutzer Nr. 1

  • Attributsatz: Marketing
  • Attribut: AppCountry
  • Attributdatentyp: Auflistung von Zeichenfolgen
  • Attributwert: ["France"]

Alle anderen Benutzer

  • AppCountry Attribut nicht hinzugefügt

Anforderung

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry ne 'Canada'
ConsistencyLevel: eventual

Antwort

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 32,
    "value": [
        {
            "id": "c4f9ecd3-d3c1-4544-b49a-bc9bb62beb67",
            "displayName": "Alain",
            "customSecurityAttributes": null
        },
        {
            "id": "de4f1218-b0fb-4449-b3a0-1e1dd193e6e7",
            "displayName": "Joe",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Project3@odata.type": "#Collection(String)",
                    "Project3": [
                        "Baker",
                        "Cascade"
                    ],
                    "CostCenter@odata.type": "#Collection(Int32)",
                    "CostCenter": [
                        1001
                    ],
                    "Certification": true
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "EmployeeId": "QN26904"
                }
            }
        },
        {
            "id": "f24d1474-ded5-432d-be08-8abd39921aac",
            "displayName": "Isabella",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "France"
                    ]
                }
            }
        },
        {
            "id": "849e81fe-1109-4d57-9536-a25d537eec1f",
            "displayName": "Dara",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "ProjectDate": "2023-04-12"
                }
            }
        },
        {
            "id": "42c88239-db99-45f0-85af-cbb6c8acb2a3",
            "displayName": "Chandra",
            "customSecurityAttributes": null
        }
    ]
}

Entfernen von benutzerdefinierten Sicherheitsattributen

Beispiel 1: Entfernen einer einwertigen benutzerdefinierten Sicherheitsattributezuweisung für einen Benutzer

Das folgende Beispiel zeigt, wie Sie mithilfe der Benutzeraktualisierungs-API eine benutzerdefinierte Sicherheitsattributezuweisung entfernen, die einen einzelnen Wert von einem Benutzer unterstützt.

  • Attributsatz: Engineering
  • Attribut: ProjectDate
  • Attributwert: null

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":null
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Beispiel 2: Entfernen einer mehrwertigen benutzerdefinierten Sicherheitsattributezuweisung für einen Benutzer

Im folgenden Beispiel wird gezeigt, wie Sie mithilfe der Benutzeraktualisierungs-API eine benutzerdefinierte Sicherheitsattributezuweisung entfernen, die mehrere Werte von einem Benutzer unterstützt.

  • Attributsatz: Engineering
  • Attribut: Project
  • Attributwert: []

Anforderung

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Project":[]
        }
    }
}

Antwort

HTTP/1.1 204 No Content

Nächster Schritt