Manage a Microsoft Entra application using Microsoft Graph
Articolo
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 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.
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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Application application = new Application();
application.setDisplayName("My application");
Application result = graphClient.applications().post(application);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Application;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Application();
$requestBody->setDisplayName('My application');
$result = $graphServiceClient->applications()->post($requestBody)->wait();
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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppId("fc876dd1-6bcb-4304-b9b6-18ddf1526b62");
ServicePrincipal result = graphClient.servicePrincipals().post(servicePrincipal);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setAppId('fc876dd1-6bcb-4304-b9b6-18ddf1526b62');
$result = $graphServiceClient->servicePrincipals()->post($requestBody)->wait();
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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Application application = new Application();
LinkedList<String> tags = new LinkedList<String>();
tags.add("HR");
tags.add("Payroll");
tags.add("HideApp");
application.setTags(tags);
InformationalUrl 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");
application.setInfo(info);
WebApplication web = new WebApplication();
web.setHomePageUrl("https://www.contoso.com/");
web.setLogoutUrl("https://www.contoso.com/frontchannel_logout");
LinkedList<String> redirectUris = new LinkedList<String>();
redirectUris.add("https://localhost");
web.setRedirectUris(redirectUris);
application.setWeb(web);
application.setServiceManagementReference("Owners aliases: Finance @ contosofinance@contoso.com; The Phone Company HR consulting @ hronsite@thephone-company.com;");
Application result = graphClient.applications().byApplicationId("{application-id}").patch(application);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppRoleAssignmentRequired(true);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setAppRoleAssignmentRequired(true);
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();
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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Application application = new Application();
LinkedList<RequiredResourceAccess> requiredResourceAccess = new LinkedList<RequiredResourceAccess>();
RequiredResourceAccess requiredResourceAccess1 = new RequiredResourceAccess();
requiredResourceAccess1.setResourceAppId("00000002-0000-0000-c000-000000000000");
LinkedList<ResourceAccess> resourceAccess = new LinkedList<ResourceAccess>();
ResourceAccess resourceAccess1 = new ResourceAccess();
resourceAccess1.setId(UUID.fromString("311a71cc-e848-46a1-bdf8-97ff7156d8e6"));
resourceAccess1.setType("Scope");
resourceAccess.add(resourceAccess1);
ResourceAccess resourceAccess2 = new ResourceAccess();
resourceAccess2.setId(UUID.fromString("3afa6a7d-9b1a-42eb-948e-1650a849e176"));
resourceAccess2.setType("Role");
resourceAccess.add(resourceAccess2);
requiredResourceAccess1.setResourceAccess(resourceAccess);
requiredResourceAccess.add(requiredResourceAccess1);
application.setRequiredResourceAccess(requiredResourceAccess);
Application result = graphClient.applications().byApplicationId("{application-id}").patch(application);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Application application = new Application();
LinkedList<AppRole> appRoles = new LinkedList<AppRole>();
AppRole appRole = new AppRole();
LinkedList<String> allowedMemberTypes = new LinkedList<String>();
allowedMemberTypes.add("User");
allowedMemberTypes.add("Application");
appRole.setAllowedMemberTypes(allowedMemberTypes);
appRole.setDescription("Survey.Read");
appRole.setDisplayName("Survey.Read");
appRole.setId(UUID.fromString("7a9ddfc4-cc8a-48ea-8275-8ecbffffd5a0"));
appRole.setIsEnabled(false);
appRole.setOrigin("Application");
appRole.setValue("Survey.Read");
appRoles.add(appRole);
application.setAppRoles(appRoles);
Application result = graphClient.applications().byApplicationId("{application-id}").patch(application);
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"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipalCollectionResponse result = graphClient.servicePrincipals().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "owners/$count eq 0 or owners/$count eq 1";
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
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"\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.models.ReferenceCreate referenceCreate = new com.microsoft.graph.models.ReferenceCreate();
referenceCreate.setOdataId("https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26");
graphClient.applications().byApplicationId("{application-id}").owners().ref().post(referenceCreate);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ReferenceCreate;
$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();
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.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.