Partager via

Gérer une application Microsoft Entra à l’aide de Microsoft Graph

  • Article

Votre application doit être inscrite dans Microsoft Entra ID avant que le Plateforme d'identités Microsoft puisse l’autoriser à accéder aux données stockées dans le cloud Microsoft. Cette condition s’applique aux applications que vous développez vous-même, dont votre locataire est propriétaire ou auxquelles vous accédez via un abonnement actif.

De nombreux paramètres pour les applications sont enregistrés en tant qu’objets accessibles, mis à jour ou supprimés à l’aide de Microsoft Graph. Dans cet article, vous allez apprendre à utiliser Microsoft Graph pour gérer les détails des objets d’application et de principal de service, notamment les propriétés, les autorisations et les attributions de rôles.

Configuration requise

Pour tester les opérations de l’API, vous avez besoin des ressources et privilèges suivants :

  • Locataire Microsoft Entra opérationnel.
  • Connectez-vous à Graph Explorer en tant qu’utilisateur disposant des privilèges autorisés pour créer et gérer des applications dans le locataire.
  • Accordez-vous l’autorisation déléguée de privilège minimum indiquée pour l’opération.

Inscrire une application auprès de Microsoft Entra ID

La requête suivante crée une application en spécifiant uniquement la propriété displayName requise. Les valeurs par défaut sont affectées à d’autres propriétés.

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json

{
  "displayName": "My application"
}

La requête retourne une 201 Created réponse avec l’objet d’application dans le corps de la réponse. L’application reçoit un ID unique pour les applications dans le locataire et un appId globalement unique dans l’écosystème Microsoft Entra ID.

Créer un principal de service pour une application

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
  "appId": "fc876dd1-6bcb-4304-b9b6-18ddf1526b62"
}

La requête retourne une 201 Created réponse avec l’objet principal de service dans le corps de la réponse.

Traitement d’une application ou d’un objet principal de service

Vous pouvez adresser une application ou un principal de service par son ID ou par son appId, où ID est appelé ID d’objet et appId est appelé ID d’application (client) sur le centre d’administration Microsoft Entra. Ces syntaxes sont prises en charge pour toutes les opérations HTTP CRUD sur les applications et les principaux de service.

Pour adresser une application ou un principal de service par son ID.

https://graph.microsoft.com/v1.0/applications/{applicationObjectId}
https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalObjectId}

Pour adresser une application ou un principal de service par son appId.

https://graph.microsoft.com/v1.0/applications(appId='appId')
https://graph.microsoft.com/v1.0/servicePrincipals(appId='appId')

En outre, vous pouvez adresser un objet d’application unique à son uniqueName. Vous pouvez utiliser cette propriété pour créer une application avec le nom unique si elle n’existe pas, ou la mettre à jour si elle existe . une opération appelée « Upsert ».

Créez une application avec le uniqueName spécifié s’il n’existe pas ; sinon, mettez-la à jour.

PATCH https://graph.microsoft.com/v1.0/applications(uniqueName='{uniqueName}')
Content-Type: application/json
Prefer: create-if-missing

{
  "displayName": "Display name"
}

Configurer d’autres propriétés de base pour votre application

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

Vous configurez les propriétés de base suivantes pour l’application.

  • Ajoutez des balises pour la catégorisation dans le organization. Utilisez également la HideApp balise pour masquer l’application de Mes applications et du lanceur Microsoft 365.
  • Ajoutez des informations de base, notamment le logo, les conditions d’utilisation et la déclaration de confidentialité.
  • Stocker les informations de contact sur l’application
PATCH https://graph.microsoft.com/v1.0/applications/0d0021e2-eaab-4b9f-a5ad-38c55337d63e/
Content-type: application/json

{
    "tags": [
        "HR",
        "Payroll",
        "HideApp"
    ],
    "info": {
        "logoUrl": "https://cdn.pixabay.com/photo/2016/03/21/23/25/link-1271843_1280.png",
        "marketingUrl": "https://www.contoso.com/app/marketing",
        "privacyStatementUrl": "https://www.contoso.com/app/privacy",
        "supportUrl": "https://www.contoso.com/app/support",
        "termsOfServiceUrl": "https://www.contoso.com/app/termsofservice"
    },
    "web": {
        "homePageUrl": "https://www.contoso.com/",
        "logoutUrl": "https://www.contoso.com/frontchannel_logout",
        "redirectUris": [
            "https://localhost"
        ]
    },
    "serviceManagementReference": "Owners aliases: Finance @ contosofinance@contoso.com; The Phone Company HR consulting @ hronsite@thephone-company.com;"
}

Limiter la connexion de l’application aux identités affectées uniquement

L’opération suivante limite les identités qui peuvent se connecter à une application uniquement à celles qui sont affectées à tous les rôles sur l’application.

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/89473e09-0737-41a1-a0c3-1418d6908bcd

{
    "appRoleAssignmentRequired": true
}

Attribuer des autorisations à une application

Bien que vous puissiez attribuer des autorisations à une application via le centre d’administration Microsoft Entra, vous attribuez également des autorisations via Microsoft Graph en mettant à jour la propriété requiredResourceAccess de l’objet d’application. Vous devez transmettre les autorisations existantes et nouvelles. La transmission de nouvelles autorisations uniquement remplace et supprime les autorisations existantes qui n’ont pas encore été consentées.

L’attribution d’autorisations ne les accorde pas automatiquement à l’application. Vous devez toujours accorder le consentement de l’administrateur à l’aide de la centre d’administration Microsoft Entra. Pour accorder des autorisations sans consentement interactif, consultez Accorder ou révoquer des autorisations d’API par programmation.

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

PATCH https://graph.microsoft.com/v1.0/applications/581088ba-83c5-4975-b8af-11d2d7a76e98
Content-Type: application/json

{
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
                    "type": "Scope"
                },
                {
                    "id": "3afa6a7d-9b1a-42eb-948e-1650a849e176",
                    "type": "Role"
                }
            ]
        }
    ]
}

Créer des rôles d’application

Créer des rôles d’application sur un objet d’application

Pour conserver les rôles d’application existants, incluez-les dans la demande. Sinon, ils sont remplacés par le nouvel objet.

PATCH https://graph.microsoft.com/v1.0/applications/bbd46130-e957-4c38-a116-d4d02afd1057
Content-Type: application/json

{
    "appRoles": [
        {
            "allowedMemberTypes": [
                "User",
                "Application"
            ],
            "description": "Survey.Read",
            "displayName": "Survey.Read",
            "id": "7a9ddfc4-cc8a-48ea-8275-8ecbffffd5a0",
            "isEnabled": false,
            "origin": "Application",
            "value": "Survey.Read"
        }
    ]
}

Gérer les propriétaires

Identifier les principaux de service et les principaux de service sans propriétaire avec un seul propriétaire

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

Cette demande nécessite que l’en-tête ConsistencyLevel soit défini sur eventual, car $count figure dans la demande. Pour plus d’informations sur l’utilisation de ConsistencyLevel et $count, consultez Fonctionnalités de requête avancées sur les objets d’annuaire.

Cette requête retourne également le nombre d’applications qui correspondent à la condition de filtre.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=owners/$count eq 0 or owners/$count eq 1&$count=true
ConsistencyLevel: eventual

Affecter un propriétaire à une application

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

Dans la requête suivante, 8afc02cb-4d62-4dba-b536-9f6d73e9be26 est l’ID d’objet d’un utilisateur ou d’un principal de service.

POST https://graph.microsoft.com/v1.0/applications/7b45cf6d-9083-4eb2-92c4-a7e090f1fc40/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"
}

Affecter un propriétaire à un principal de service

Autorisation déléguée avec privilèges minimum : Application.ReadWrite.All.

La requête suivante fait référence au principal de service à l’aide de son appId. Vous pouvez également le référencer à l’aide de l’ID d’objet dans le modèle ../servicePrincipals/{bject ID}/owners/$ref. 8afc02cb-4d62-4dba-b536-9f6d73e9be26 est l’ID d’objet d’un utilisateur ou d’un principal de service.

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='46e6adf4-a9cf-4b60-9390-0ba6fb00bf6b')/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"
}

Verrouiller les propriétés sensibles pour les principaux de service

La fonctionnalité de verrouillage instance d’application vous permet de protéger les propriétés sensibles de vos applications multilocataires contre toute falsification non autorisée. Les propriétés suivantes de l’objet principal de service peuvent être verrouillées :

  • keyCredentials où le type d’utilisation est Sign ou Verify.
  • passwordCredentials où le type d’utilisation est Sign ou Verify.
  • propriété tokenEncryptionKeyId .

Vous gérez l’application instance fonctionnalité de verrouillage via la propriété servicePrincipalLockConfiguration de l’objet application de l’application multilocataire.

Pour verrouiller toutes les propriétés sensibles d’un principal de service

Quand isEnabled et allProperties a la valeur true, même si d’autres propriétés de l’objet servicePrincipalLockConfiguration sont null, toutes les propriétés sensibles du principal de service sont verrouillées.

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "allProperties": true
    }
}

Pour verrouiller des propriétés sensibles spécifiques d’un principal de service

L’exemple suivant verrouille les propriétés keyCredentials et passwordCredentials du principal de service et active l’application instance fonctionnalité de verrouillage.

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "credentialsWithUsageSign": true,
        "credentialsWithUsageVerify": true
    }
}

Configurer des autorités de certification approuvées pour les applications

Vous pouvez limiter l’utilisation des informations d’identification de certificat pour les applications de votre locataire aux certificats émis par les autorités de certification approuvées. Cette stratégie est appliquée lorsque vous ajoutez un certificat à une application et n’affecte pas les certificats existants, sauf s’ils sont pivotés. Lorsqu’une application tente de faire pivoter ses informations d’identification de certificat, elle passe par l’évaluation de la stratégie pour s’assurer que les informations d’identification ajoutées sont conformes à la restriction de l’autorité de certification approuvée.

Étape 1 : Créer une chaîne de certificats d’approbation

Autorisation déléguée avec privilèges minimum : AppCertTrustConfiguration.Read.All rôle de Microsoft Entra moins privilégié :Application Administrator

POST https://graph.microsoft.com/beta/certificateAuthorities/certificateBasedApplicationConfigurations

{
    "displayName": "Trusted Certificate Chain of Trust for Contoso",
    "description": "The Trusted Certificate Chain of Trust containing a certificate chain used by app policy, to only allow application certificates from selected issuer.",
    "trustedCertificateAuthorities": [
        {
            "isRootAuthority": true,
            "certificate": "MIIFVjCCAz6gAwIBAgIQJdrL...UyNDIyNTcwM1owPDE …="
        },
        {
            "isRootAuthority": false,
            "certificate": QAAAAAAWjABAQsFADA8M...UyNDIyNTcwM1o …="
        }
    ]
}

La requête retourne un objet de réponse 200 OK . La réponse inclut l’ID de la chaîne de certificats de l’objet d’approbation. Supposons que l’ID soit eec5ba11-2fc0-4113-83a2-ed986ed13743.

Étape 2 : Affecter la chaîne de certificats d’approbation à une stratégie de gestion des applications

L’exemple suivant configure une stratégie pour s’assurer que seuls les certificats émis par l’autorité de certification intermédiaire définie à l’étape précédente peuvent être ajoutés aux applications dans le locataire. L’objet applicationRestrictions>keyCredentials définit un restrictionType avec la valeur trustedCertificateAuthority, qui fait référence à l’ID créé. Étant donné que cette stratégie est appliquée à la stratégie de gestion des applications par défaut au niveau du locataire, elle est appliquée à toutes les applications créées dans le locataire et rejette les tentatives d’ajout de certificats non conformes dans le cadre des informations d’identification de certificat d’une application.

Cette stratégie garantit que seuls les certificats de l’autorité de certification intermédiaire spécifiée peuvent être ajoutés aux applications. L’objet applicationRestrictions>keyCredentials définit un restrictionType sur trustedCertificateAuthority, référençant l’ID créé. Cette stratégie s’applique à toutes les applications du locataire, rejetant tout certificat non conforme.

Autorisation déléguée avec privilèges minimum : Policy.Read.ApplicationConfiguration rôle de Microsoft Entra moins privilégié :Security Administrator

PATCH https://graph.microsoft.com/v1.0/policies/defaultAppManagementPolicy

{
  "id": "d015220e-9789-4e8e-bbcc-270fe419229d",
  "description": "Lorem ipsum",
  "displayName": "Credential management policy",
  "isEnabled": true,
  "applicationRestrictions": {
    "passwordCredentials": [
      {
        "restrictionType": "passwordLifetime",
        "maxLifetime": "P14D",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T07:00:00Z"
      }
    ],
    "keyCredentials": [
      {
        "restrictionType": "certificateLifetime",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T10:37:00Z",
        "maxLifetime": "P90D"
      },
      {
        "restrictionType": "trustedCertificateAuthority",
        "certificateBasedApplicationConfigurationIds": [
          "eec5ba11-2fc0-4113-83a2-ed986ed13743"
        ],
        "restrictForAppsCreatedAfterDateTime": "2019-10-19T10:37:00Z"
      }
    ]
  }
}

Contenu connexe