Obtenir servicePrincipal

  • Article

Espace de noms: microsoft.graph

Récupérer les propriétés et les relations de l’objetservicePrincipal.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet
✅ ✅ ✅ ✅

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) Application.Read.All Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Application.Read.All Application.ReadWrite.OwnedBy, Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Remarque

Un principal de service peut récupérer les détails de sa propre application et de son principal de service sans qu'aucune autorisation d'application ne lui soit accordée. L’autorisation Application.ReadWrite.OwnedBy permet à une application d’appeler GET /applications et GET /servicePrincipals de répertorier toutes les applications et principaux de service dans le locataire. Cette étendue d’accès a été autorisée pour l’autorisation.

Requête HTTP

Vous pouvez adresser le principal de service à l’aide de son id ou de son appId. id et appId sont respectivement appelés ID d’objet et ID d’application (client) dans les inscriptions d’applications dans le centre d'administration Microsoft Entra.

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

Paramètres facultatifs de la requête

Cette méthode prend en charge les paramètres de requête $select et $expandOData pour aider à personnaliser la réponse.

Par défaut, cette API ne retourne la valeur de clé publique de la clé dans la propriété keyCredentials, sauf si keyCredentials est spécifié dans une $select requête. Par exemple, $select=id,appId,keyCredentials.

L’utilisation de $select pour obtenir keyCredentials pour les principaux de service a une limite de limitation de 150 demandes par minute pour chaque client.

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Accept-Language Code langue Facultatif.

Si vous fournissez un code de langue pris en charge, tel quees-ES ou de-DE, dans l'en-tête Accept-Language, vous obtiendrez des valeurs localisées si elles sont disponibles. Notez que l’en-tête n’est pas pris en charge pour les opérations de liste.

Corps de la demande

N’indiquez pas le corps de la demande pour cette méthode.

Réponse

En cas de réussite, cette méthode renvoie un 200 OKcode de réponse et l’objet serviceprincipal dans le corps de la réponse.

Exemples

Exemple 1 : Récupérer un principal de service par son ID

Demande

L’exemple suivant illustre une demande.

GET https://graph.microsoft.com/v1.0/servicePrincipals/00063ffc-54e9-405d-b8f3-56124728e051

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
  "accountEnabled": true,
  "addIns": [],
  "alternativeNames": ["http://contoso/a7770d29-4321-41a6-b863-ca11d6639448"],
  "appDisplayName": "My app",
  "appId": "appId-value",
  "appOwnerOrganizationId": "65415bb1-9267-4313-bbf5-ae259732ee12",
  "appRoleAssignmentRequired":true,
  "appRoles": [],
  "disabledByMicrosoftStatus": null,
  "displayName": "My app instance in tenant",
  "endpoints": [],
  "homepage": null,
  "id": "00af5dfb-85da-4b41-a677-0c6b86dd34f8",
  "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
    },
  "info": {
    "termsOfServiceUrl": null,
    "supportUrl": null,
    "privacyStatementUrl": null,
    "marketingUrl": null,
    "logoUrl": null
  },
  "keyCredentials": [],
  "logoutUrl": null,
  "oauth2PermissionScopes": [],
  "passwordCredentials": [],
  "publisherName": null,
  "replyUrls": [],
  "resourceSpecificApplicationPermissions": [],
  "servicePrincipalNames": [],
  "servicePrincipalType": null,
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "tags": [],
  "tokenEncryptionKeyId": null
}

Exemple 2 : Récupérer les propriétés spécifiques d’un principal de service

Demande

L’exemple suivant illustre une demande.

GET https://graph.microsoft.com/v1.0/servicePrincipals/7408235b-7540-4850-82fe-a5f15ed019e2?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(id,appId,displayName,appRoles,publishedPermissionScopes)/$entity",
    "id": "7408235b-7540-4850-82fe-a5f15ed019e2",
    "appId": "00000003-0000-0000-c000-000000000000",
    "displayName": "Microsoft Graph",
    "appRoles": [
        {
            "allowedMemberTypes": [
                "Application"
            ],
            "description": "Allows the app to read all class assignments without grades for all users without a signed-in user.",
            "displayName": "Read all class assignments without grades",
            "id": "6e0a958b-b7fc-4348-b7c4-a6ab9fd3dd0e",
            "isEnabled": true,
            "origin": "Application",
            "value": "EduAssignments.ReadBasic.All"
        }
    ],
    "oauth2PermissionScopes": [
        {
            "adminConsentDescription": "Allows the app to see your users' basic profile (e.g., name, picture, user name, email address)",
            "adminConsentDisplayName": "View users' basic profile",
            "id": "14dad69e-099b-42c9-810b-d002981feec1",
            "isEnabled": true,
            "type": "User",
            "userConsentDescription": "Allows the app to see your basic profile (e.g., name, picture, user name, email address)",
            "userConsentDisplayName": "View your basic profile",
            "value": "profile"
        }
    ]
}

Exemple 3 : Obtenir les attributions d’attributs de sécurité personnalisées du principal de service spécifié

L’exemple suivant obtient les attributs de sécurité personnalisés du principal du service spécifié.

Attribut #1

  • Jeu d’attributs : Engineering
  • Attribut : Project
  • Type de données d’attribut : collection de chaînes
  • Valeur d’attribut : ["Baker","Cascade"]

Attribut #2

  • Jeu d’attributs : Engineering
  • Attribut : CostCenter
  • Type de données d’attribut : collection de nombres entiers
  • Valeur d’attribut : [1001]

Attribut #3

  • Jeu d’attributs : Engineering
  • Attribut : Certification
  • Type de données d’attribut : booléen
  • Valeur d’attribut : true

Attribut #4

  • Jeu d’attributs : Marketing
  • Attribut : Level
  • Type de données d’attribut : chaîne
  • Valeur d’attribut : "Public"

Pour obtenir des affectations d’attributs de sécurité personnalisées, le principal appelant doit avoir le rôle de Lecteur d’affectation d’attributs ou le rôle d’Administrateur d’affectations d’attributs et doit avoir l’autorisation CustomSecAttributeAssignment.Read.All ou CustomSecAttributeAssignment.ReadWrite.All.

Demande

L’exemple suivant illustre une demande.

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

Réponse

L’exemple suivant illustre la réponse.

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

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

Si aucun attribut de sécurité personnalisé n’est attribué au principal du service ou si le principal appelant n’a pas d’accès, la réponse ressemble à :

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

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