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 Microsoft Entra or Microsoft 365 tenants. 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 app and service principal objects including the properties, permissions, and role assignments.
Prerequisites
To complete this tutorial, 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.
Register an application with Microsoft Entra ID
The following request creates an app by specifying only the required displayName property.
Least privilege delegated permission: Application.ReadWrite.All.
POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json
{
"displayName": "My application"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Application
{
DisplayName = "My application",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$requestBody->setDisplayName('My application');
$result = $graphServiceClient->applications()->post($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = Application(
display_name = "My application",
)
result = await graph_client.applications.post(request_body)
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 privilege delegated permission: Application.ReadWrite.All.
POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
{
"appId": "fc876dd1-6bcb-4304-b9b6-18ddf1526b62"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ServicePrincipal
{
AppId = "fc876dd1-6bcb-4304-b9b6-18ddf1526b62",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setAppId('fc876dd1-6bcb-4304-b9b6-18ddf1526b62');
$result = $graphServiceClient->servicePrincipals()->post($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = ServicePrincipal(
app_id = "fc876dd1-6bcb-4304-b9b6-18ddf1526b62",
)
result = await graph_client.service_principals.post(request_body)
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.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Application
{
Tags = new List<string>
{
"HR",
"Payroll",
"HideApp",
},
Info = new InformationalUrl
{
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 = new WebApplication
{
HomePageUrl = "https://www.contoso.com/",
LogoutUrl = "https://www.contoso.com/frontchannel_logout",
RedirectUris = new List<string>
{
"https://localhost",
},
},
ServiceManagementReference = "Owners aliases: Finance @ contosofinance@contoso.com; The Phone Company HR consulting @ hronsite@thephone-company.com;",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$requestBody->setTags(['HR', 'Payroll', 'HideApp', ]);
$info = new InformationalUrl();
$info->setLogoUrl('https://cdn.pixabay.com/photo/2016/03/21/23/25/link-1271843_1280.png');
$info->setMarketingUrl('https://www.contoso.com/app/marketing');
$info->setPrivacyStatementUrl('https://www.contoso.com/app/privacy');
$info->setSupportUrl('https://www.contoso.com/app/support');
$info->setTermsOfServiceUrl('https://www.contoso.com/app/termsofservice');
$requestBody->setInfo($info);
$web = new WebApplication();
$web->setHomePageUrl('https://www.contoso.com/');
$web->setLogoutUrl('https://www.contoso.com/frontchannel_logout');
$web->setRedirectUris(['https://localhost', ]);
$requestBody->setWeb($web);
$requestBody->setServiceManagementReference('Owners aliases: Finance @ contosofinance@contoso.com; The Phone Company HR consulting @ hronsite@thephone-company.com;');
$result = $graphServiceClient->applications()->byApplicationId('application-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ServicePrincipal
{
AppRoleAssignmentRequired = true,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setAppRoleAssignmentRequired(true);
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = ServicePrincipal(
app_role_assignment_required = True,
)
result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)
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 privilege delegated permission: Application.ReadWrite.All.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Application
{
RequiredResourceAccess = new List<RequiredResourceAccess>
{
new RequiredResourceAccess
{
ResourceAppId = "00000002-0000-0000-c000-000000000000",
ResourceAccess = new List<ResourceAccess>
{
new ResourceAccess
{
Id = Guid.Parse("311a71cc-e848-46a1-bdf8-97ff7156d8e6"),
Type = "Scope",
},
new ResourceAccess
{
Id = Guid.Parse("3afa6a7d-9b1a-42eb-948e-1650a849e176"),
Type = "Role",
},
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$requiredResourceAccessRequiredResourceAccess1 = new RequiredResourceAccess();
$requiredResourceAccessRequiredResourceAccess1->setResourceAppId('00000002-0000-0000-c000-000000000000');
$resourceAccessResourceAccess1 = new ResourceAccess();
$resourceAccessResourceAccess1->setId('311a71cc-e848-46a1-bdf8-97ff7156d8e6');
$resourceAccessResourceAccess1->setType('Scope');
$resourceAccessArray []= $resourceAccessResourceAccess1;
$resourceAccessResourceAccess2 = new ResourceAccess();
$resourceAccessResourceAccess2->setId('3afa6a7d-9b1a-42eb-948e-1650a849e176');
$resourceAccessResourceAccess2->setType('Role');
$resourceAccessArray []= $resourceAccessResourceAccess2;
$requiredResourceAccessRequiredResourceAccess1->setResourceAccess($resourceAccessArray);
$requiredResourceAccessArray []= $requiredResourceAccessRequiredResourceAccess1;
$requestBody->setRequiredResourceAccess($requiredResourceAccessArray);
$result = $graphServiceClient->applications()->byApplicationId('application-id')->patch($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = Application(
required_resource_access = [
RequiredResourceAccess(
resource_app_id = "00000002-0000-0000-c000-000000000000",
resource_access = [
ResourceAccess(
id = UUID("311a71cc-e848-46a1-bdf8-97ff7156d8e6"),
type = "Scope",
),
ResourceAccess(
id = UUID("3afa6a7d-9b1a-42eb-948e-1650a849e176"),
type = "Role",
),
],
),
],
)
result = await graph_client.applications.by_application_id('application-id').patch(request_body)
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Application
{
AppRoles = new List<AppRole>
{
new AppRole
{
AllowedMemberTypes = new List<string>
{
"User",
"Application",
},
Description = "Survey.Read",
DisplayName = "Survey.Read",
Id = Guid.Parse("7a9ddfc4-cc8a-48ea-8275-8ecbffffd5a0"),
IsEnabled = false,
Origin = "Application",
Value = "Survey.Read",
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$appRolesAppRole1 = new AppRole();
$appRolesAppRole1->setAllowedMemberTypes(['User', 'Application', ]);
$appRolesAppRole1->setDescription('Survey.Read');
$appRolesAppRole1->setDisplayName('Survey.Read');
$appRolesAppRole1->setId('7a9ddfc4-cc8a-48ea-8275-8ecbffffd5a0');
$appRolesAppRole1->setIsEnabled(false);
$appRolesAppRole1->setOrigin('Application');
$appRolesAppRole1->setValue('Survey.Read');
$appRolesArray []= $appRolesAppRole1;
$requestBody->setAppRoles($appRolesArray);
$result = $graphServiceClient->applications()->byApplicationId('application-id')->patch($requestBody)->wait();
Identify ownerless service principals and service principals with one owner
Least privilege 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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "owners/$count eq 0 or owners/$count eq 1";
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals list --filter "owners/$count eq 0 or owners/$count eq 1" --count "true" --consistency-level "eventual"
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new ServicePrincipalsRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = ServicePrincipalsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "owners/\$count eq 0 or owners/\$count eq 1";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->servicePrincipals()->get($requestConfiguration)->wait();
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"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ReferenceCreate
{
OdataId = "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Applications["{application-id}"].Owners.Ref.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc applications owners ref post --application-id {application-id} --body '{\
"@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"\
}\
'
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ReferenceCreate();
$requestBody->setOdataId('https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26');
$graphServiceClient->applications()->byApplicationId('application-id')->owners()->ref()->post($requestBody)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
request_body = ReferenceCreate(
odata_id = "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26",
)
await graph_client.applications.by_application_id('application-id').owners.ref.post(request_body)
Least privilege delegated permission: Application.ReadWrite.All.
The following request references the service principal using its appId. 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 multi-tenant 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 multi-tenant 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.