Skip to content

Latest commit

 

History

History
421 lines (331 loc) · 15.8 KB

serviceprincipal-get.md

File metadata and controls

421 lines (331 loc) · 15.8 KB
Raw
title description author ms.localizationpriority ms.subservice doc_type
Get servicePrincipal
Retrieve the properties and relationships of serviceprincipal object.
sureshja
high
entra-applications
apiPageType

Get servicePrincipal

Namespace: microsoft.graph

[!INCLUDE beta-disclaimer]

Retrieve the properties and relationships of a servicePrincipal object.

[!INCLUDE national-cloud-support]

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

[!INCLUDE permissions-table]

Note

A service principal can retrieve its own application and service principal details without being granted any application permissions. The Application.ReadWrite.OwnedBy permission allows an app to call GET /applications and GET /servicePrincipals to list all applications and service principals in the tenant. This scope of access has been allowed for the permission.

HTTP request

You can address the service principal using either its id or appId. id and appId are referred to as the Object ID and Application (Client) ID, respectively, in app registrations in the Microsoft Entra admin center.

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

Optional query parameters

This method supports the $select and $expand OData query parameters to help customize the response.

This method supports the $count, $expand, $filter, $orderby, $search, $select, and $top OData query parameters to help customize the response. Some queries are supported only when you use the ConsistencyLevel header set to eventual and $count. For more information, see Advanced query capabilities on directory objects.

By default, this API doesn't return the public key value of the key in the keyCredentials property unless keyCredentials is specified in a $select query. For example, $select=id,appId,keyCredentials.

The use of $select to get keyCredentials for service principals has a throttling limit of 150 requests per minute for every tenant.

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Accept-Language Language code. Optional.

Providing the Accept-Language header with a supported language code, such as es-ES or de-DE, will return localized values where available. Note that the header is not supported for list operations.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and a servicePrincipal object in the response body.

Examples

Example 1: Get the properties of the specified service principal

Request

The following example shows a request.

HTTP

GET https://graph.microsoft.com/beta/servicePrincipals/{id}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

CLI

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

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

{
        "id": "59e617e5-e447-4adc-8b88-00af644d7c92",
        "deletedDateTime": null,
        "accountEnabled": true,
        "appDisplayName": "My App",
        "appId": "65415bb1-9267-4313-bbf5-ae259732ee12",
        "applicationTemplateId": null,
        "appOwnerOrganizationId": "1bc1c026-2f7b-48a5-98da-afa2fd8bc7bc",
        "appRoleAssignmentRequired": false,
        "disabledByMicrosoftStatus": null,
        "displayName": "foo",
        "errorUrl": null,
        "homepage": null,
        "loginUrl": null,
        "logoutUrl": null,
        "notificationEmailAddresses": [],
        "preferredSingleSignOnMode": null,
        "preferredTokenSigningKeyEndDateTime": null,
        "preferredTokenSigningKeyThumbprint": null,
        "publisherName": "Contoso",
        "replyUrls": [],
        "samlMetadataUrl": null,
        "samlSingleSignOnSettings": null,
        "servicePrincipalNames": [
            "f1bd758f-4a1a-4b71-aa20-a248a22a8928"
        ],
        "signInAudience": "AzureADandPersonalMicrosoftAccount",
        "tags": [],
        "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
        },
        "addIns": [],
        "api": {
            "resourceSpecificApplicationPermissions": []
        },
        "appRoles": [],
        "info": {
            "termsOfServiceUrl": null,
            "supportUrl": null,
            "privacyStatementUrl": null,
            "marketingUrl": null,
            "logoUrl": null
        },
        "keyCredentials": [],
        "publishedPermissionScopes": [],
        "passwordCredentials": []
}

Example 2: Retrieve a service principal by its appId and only specific properties

Request

The following example shows a request.

HTTP

GET https://graph.microsoft.com/beta/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,publishedPermissionScopes,resourceSpecificApplicationPermissions

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

CLI

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

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"
        }
    ],
    "publishedPermissionScopes": [
        {
            "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"
        }
    ]
}

Example 3: Get the custom security attribute assignments of the specified service principal

The following example gets the custom security attributes of the specified service principal.

Attribute #1

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings
  • Attribute value: ["Baker","Cascade"]

Attribute #2

  • Attribute set: Engineering
  • Attribute: CostCenter
  • Attribute data type: Collection of Integers
  • Attribute value: [1001]

Attribute #3

  • Attribute set: Engineering
  • Attribute: Certification
  • Attribute data type: Boolean
  • Attribute value: true

Attribute #4

  • Attribute set: Marketing
  • Attribute: Level
  • Attribute data type: String
  • Attribute value: "Public"

To get custom security attribute assignments, the calling principal must be assigned the Attribute Assignment Reader or Attribute Assignment Administrator role and must be granted the CustomSecAttributeAssignment.Read.All or CustomSecAttributeAssignment.ReadWrite.All permission.

Request

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

CLI

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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"
        }
    }
}

If there are no custom security attributes assigned to the service principal or if the calling principal does not have access, the response will look like:

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

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