Edit

Share via

Manage a Microsoft Entra application using Microsoft Graph

  • Article

Your app must be registered in Microsoft Entra ID before the Microsoft identity platform can authorize it to access data stored in the Microsoft cloud. This condition applies to apps that you develop yourself, that your tenant owns, or that you access through an active subscription.

Many settings for apps are recorded as objects that can be accessed, updated, or deleted using Microsoft Graph. In this article, you learn how to use Microsoft Graph to manage details of app and service principal objects including the properties, permissions, and role assignments.

Prerequisites

To test the API operations, you need the following resources and privileges:

  • A working Microsoft Entra tenant.
  • Sign in to Graph Explorer as a user with privileges allowed to create and manage applications in the tenant.
  • Grant yourself the least privilege delegated permission indicated for the operation.

Register an application with Microsoft Entra ID

The following request creates an app by specifying only the required displayName property. Other properties are assigned the default values.

Least privileged delegated permission: Application.ReadWrite.All.

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

{
  "displayName": "My application"
}

The request returns a 201 Created response with the application object in the response body. The application is assigned an id that's unique for apps in the tenant, and an appId that's globally unique in the Microsoft Entra ID ecosystem.

Create a service principal for an application

Least privileged delegated permission: Application.ReadWrite.All.

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

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

The request returns a 201 Created response with the service principal object in the response body.

Addressing an application or a service principal object

You can address an application or a service principal by its ID or by its appId, where ID is referred to as Object ID and appId is referred to as Application (client) ID on the Microsoft Entra admin center. These syntaxes are supported for all HTTP CRUD operations on applications and service principals.

To address an application or a service principal by its ID.

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

To address an application or a service principal by its appId.

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

In addition, you can address an application object unique its uniqueName. You can use this property to create an application with the unique name if it doesn't exist, or update it if it exists; an operation referred to as "Upsert".

Create an application with the specified uniqueName if it doesn't exist, otherwise, update it.

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

{
  "displayName": "Display name"
}

Configure other basic properties for your app

Least privileged delegated permission: Application.ReadWrite.All.

You configure the following basic properties for the app.

  • Add tags for categorization in the organization. Also, use the HideApp tag to hide the app from My Apps and the Microsoft 365 Launcher.
  • Add basic information including the logo, terms of service, and privacy statement.
  • Store contact information about the 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 @ [email protected]; The Phone Company HR consulting @ [email protected];"
}

Limit app sign-in to only assigned identities

The following operation limits the identities that can sign in to an app to only those that are assigned all roles on the app.

Least privileged delegated permission: Application.ReadWrite.All.

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

{
    "appRoleAssignmentRequired": true
}

Assign permissions to an app

While you can assign permissions to an app through the Microsoft Entra admin center, you also assign permissions through Microsoft Graph by updating the requiredResourceAccess property of the app object. You must pass in both existing and new permissions. Passing in only new permissions overwrites and removes the existing permissions that haven't yet been consented to.

Assigning permissions doesn't automatically grant them to the app. You must still grant admin consent using the Microsoft Entra admin center. To grant permissions without interactive consent, see Grant or revoke API permissions programmatically.

Least privileged delegated permission: 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"
                }
            ]
        }
    ]
}

Create app roles

Create app roles on an application object

To keep any existing app roles, include them in the request. Otherwise, they're replaced with the new object.

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"
        }
    ]
}

Manage owners

Identify ownerless service principals and service principals with one owner

Least privileged delegated permission: Application.ReadWrite.All.

This request requires the ConsistencyLevel header set to eventual because $count is in the request. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

This request also returns the count of the apps that match the filter condition.

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

Assign an owner to an app

Least privileged delegated permission: Application.ReadWrite.All.

In the following request, 8afc02cb-4d62-4dba-b536-9f6d73e9be26 is the object ID for a user or service principal.

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

Assign an owner to a service principal

Least privileged delegated permission: Application.ReadWrite.All.

The following request references the service principal using its appId. You can alternatively reference it using the object ID in the pattern ../servicePrincipals/{bject ID}/owners/$ref. 8afc02cb-4d62-4dba-b536-9f6d73e9be26 is the object ID for a user or service principal.

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

Lock sensitive properties for service principals

The app instance lock feature allows you to protect sensitive properties of your multitenant apps from unauthorized tampering. The following properties of the service principal object can be locked:

  • keyCredentials where the usage type is Sign or Verify.
  • passwordCredentials where the usage type is Sign or Verify.
  • tokenEncryptionKeyId property.

You manage the app instance lock feature through the servicePrincipalLockConfiguration property of the application object of the multitenant app.

To lock all sensitive properties of a service principal

When isEnabled and allProperties is set to true, even if other properties of the servicePrincipalLockConfiguration object are null, then all sensitive properties of the service principal are locked.

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

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

To lock specific sensitive properties of a service principal

The following example locks the keyCredentials and passwordCredentials properties of the service principal and enables the app instance lock feature.

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

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

Configure trusted certificate authorities for apps

You can restrict certificate credential usage for apps in your tenant to only the certificates issued by trusted certificate authorities. This policy is enforced when you add a certificate to an app and doesn't affect existing certificates unless they are rotated. When an app tries to rotate its certificate credentials, it goes through the policy evaluation to ensure the credentials being added comply with the trusted certificate authority restriction.

Step 1: Create a certificate chain of trust

Least privileged delegated permission: AppCertTrustConfiguration.Read.All Least privileged Microsoft Entra role: 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 …="
        }
    ]
}

The request returns a 200 OK response object. The response includes the ID of the certificate chain of trust object. Assume that the ID is eec5ba11-2fc0-4113-83a2-ed986ed13743.

Step 2: Assign the certificate chain of trust to an application management policy

The following sample sets up a policy to ensure that only certificates issued by the intermediate certificate authority defined in the previous step can be added to apps in the tenant. The applicationRestrictions > keyCredentials object defines a restrictionType with the value trustedCertificateAuthority, which references the ID that was created. Because this policy is applied to the default tenant-level app management policy, it's enforced for all apps created in the tenant and rejects attempts to add noncompliant certificates as part of an app's certificate credentials.

This policy ensures that only certificates from the specified intermediate certificate authority can be added to apps. The applicationRestrictions > keyCredentials object sets a restrictionType to trustedCertificateAuthority, referencing the created ID. This policy applies to all apps in the tenant, rejecting any noncompliant certificates.

Least privileged delegated permission: Policy.Read.ApplicationConfiguration Least privileged Microsoft Entra role: 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"
      }
    ]
  }
}

Related content