Obtener servicePrincipal

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Recupera las propiedades y relaciones de un objeto de servicePrincipal. Esta API también se puede usar para obtener objetos agentIdentityBlueprintPrincipal por su identificador.

Esta API está disponible en las siguientes implementaciones en la nube nacional.

Servicio global Administración pública de EE. UU. Gobierno de EE. UU. L5 (DOD) China operado por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Application.Read.All Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación Application.Read.All Application.ReadWrite.OwnedBy, Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Importante

Para el acceso delegado mediante cuentas profesionales o educativas en las que el usuario que ha iniciado sesión actúa sobre otro usuario, se le debe asignar un rol compatible de Microsoft Entra o un rol personalizado que conceda los permisos necesarios para esta operación. Esta operación admite los siguientes roles integrados, que proporcionan solo el privilegio mínimo necesario:

  • Un miembro no administrador o un usuario invitado con permisos de usuario predeterminados
  • Desarrollador de aplicaciones: lea las propiedades de las entidades de servicio de su propiedad
  • Lectores de directorios: leer propiedades estándar
  • Lector global
  • Escritores de directorios
  • Administrador de identidades híbridas
  • Administrador de seguridad
  • Administrador de aplicaciones en la nube
  • Administrador de la aplicación

Permisos para escenarios específicos

  • Una entidad de servicio puede recuperar sus propios detalles de aplicación y entidad de servicio sin que se le concedan permisos de aplicación.
  • El permiso Application.ReadWrite.OwnedBy permite a una aplicación llamar GET /applicationsGET /servicePrincipals a todas las aplicaciones y entidades de servicio del inquilino y enumerarlas. Este ámbito de acceso se ha permitido para el permiso.
  • Para leer la propiedad customSecurityAttributes :
    • En escenarios delegados, se debe asignar al administrador el rol de administrador de asignación de atributos y a la aplicación se le debe conceder el permiso delegado CustomSecAttributeAssignment.Read.All .
    • En escenarios de solo aplicación que usan permisos de Microsoft Graph, se debe conceder a la aplicación el permiso de aplicación CustomSecAttributeAssignment.Reade.All .

Solicitud HTTP

Puede dirigirse a la entidad de servicio mediante su id o appId. id y appId se conocen como Id. de objeto e Id. de aplicación (cliente), respectivamente, en los registros de aplicaciones en el Centro de administración de Microsoft Entra.

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

Parámetros de consulta opcionales

Este método admite los parámetros de consulta $select y $expandOData para ayudar a personalizar la respuesta.

La propiedad isHardDeleteProtectionEnabled se devuelve solo cuando se solicita explícitamente con $select.

Este método admite los parámetros de $countconsulta , $expand, $filter, $orderby$search, $selecty $topOData para ayudar a personalizar la respuesta. Algunas consultas solo se admiten cuando se usa el encabezado ConsistencyLevel establecido en eventual y $count. Para obtener más información, vea Funcionalidades avanzadas de consulta en objetos de directorio.

De forma predeterminada, esta API no devuelve el valor de la clave pública de la clave en la propiedad keyCredentials, a menos que keyCredentials esté especificada en una consulta $select. Por ejemplo, $select=id,appId,keyCredentials.

El uso de $select para obtener keyCredentials para las entidades de servicio tiene un límite de 150 solicitudes por minuto para cada espacio empresarial.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización.
Accept-Language Código de idioma. Opcional.

Proporcionar el encabezado Accept-Language con un código de idioma compatible, como es-ES o de-DE, devolverá valores localizados cuando esté disponible. Tenga en cuenta que el encabezado no es compatible con las operaciones de lista.

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud para este método.

Respuesta

Si se realiza correctamente, este método devuelve un 200 OK código de respuesta y un objeto servicePrincipal o agentIdentityBlueprintPrincipal en el cuerpo de la respuesta.

Ejemplos

Ejemplo 1: Obtener las propiedades de la entidad de servicio especificada

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

Ejemplo 2: Recuperar una entidad de servicio por su AppId y solo propiedades específicas

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

Ejemplo 3: Obtener las asignaciones de atributos de seguridad personalizados de la entidad de servicio especificada

En el ejemplo siguiente se obtienen los atributos de seguridad personalizados de la entidad de servicio especificada.

Atributo n.º 1

  • Conjunto de atributos: Engineering
  • Atributo: Project
  • Tipo de datos de atributo: colección de cadenas
  • Valor de atributo: ["Baker","Cascade"]

Atributo n.º 2

  • Conjunto de atributos: Engineering
  • Atributo: CostCenter
  • Tipo de datos de atributo: colección de enteros
  • Valor de atributo: [1001]

Atributo n.º 3

  • Conjunto de atributos: Engineering
  • Atributo: Certification
  • Tipo de datos de atributo: boolean
  • Valor de atributo: true

Atributo n.º 4

  • Conjunto de atributos: Marketing
  • Atributo: Level
  • Tipo de datos de atributo: Cadena
  • Valor de atributo: "Public"

Para obtener asignaciones de atributos de seguridad personalizadas, se debe asignar a la entidad de seguridad de llamada el rol Lector de asignación de atributos o Administrador de asignación de atributos y se le debe conceder el permiso CustomSecAttributeAssignment.Read.All o CustomSecAttributeAssignment.ReadWrite.All.

Solicitud

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

Respuesta

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

Si no hay atributos de seguridad personalizados asignados a la entidad de servicio o si la entidad de seguridad que llama no tiene acceso, la respuesta tendrá el siguiente aspecto:

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

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

Ejemplo 4: Obtener el estado de protección contra eliminaciones permanentes de una entidad de servicio

Solicitud

Se usa $select para recuperar isHardDeleteProtectionEnabled, que no se devuelve de forma predeterminada.

GET https://graph.microsoft.com/beta/servicePrincipals/c4ca17b7-4f3e-4c3a-b884-bfa4100c745d?$select=id,displayName,isHardDeleteProtectionEnabled

Respuesta

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(id,displayName,isHardDeleteProtectionEnabled)/$entity",
  "id": "c4ca17b7-4f3e-4c3a-b884-bfa4100c745d",
  "displayName": "Contoso Finance",
  "isHardDeleteProtectionEnabled": true
}