Tipo de recurso servicePrincipal

Espacio de nombres: microsoft.graph

Representa una instancia de una aplicación en un directorio. Se hereda de directoryObject.

De este objeto hereda el recurso agentIdentityBlueprintPrincipal .

Este recurso es compatible con el uso de una consulta delta para realizar un seguimiento de las adiciones incrementales, las eliminaciones y las actualizaciones proporcionando una función delta. Este recurso es un tipo abierto que permite propiedades adicionales además de las documentadas aquí.

Métodos

Método	Tipo de valor devuelto	Descripción
List	Colección servicePrincipal	Recupera una lista de objetos servicePrincipal.
Crear	servicePrincipal	Crea un nuevo objeto servicePrincipal.
Get	servicePrincipal	Lee las propiedades y las relaciones de un objeto de serviceprincipal.
Update	servicePrincipal	Actualiza el objeto servicePrincipal.
Upsert	servicePrincipal	Cree una nueva entidad de servicio si no existe, o actualice las propiedades de una entidad de servicio existente.
Delete	Ninguno	Elimina el objeto servicePrincipal.
Obtener delta	colección servicePrincipal	Obtiene los cambios incrementales de las entidades de servicio.
Enumerar objetos creados	Colección directoryObject	Obtiene una colección de objetos createdObject.
Enumerar objetos en propiedad	Colección directoryObject	Obtiene una colección de objetos ownedObject.
Elementos eliminados
Lista	Colección directoryObject	Recuperar una lista de objetos servicePrincipal eliminados recientemente.
Get	directoryObject	Recuperar las propiedades de un objeto servicePrincipal eliminado recientemente.
Restaurar	directoryObject	Restaurar un objeto servicePrincipal eliminado recientemente.
Eliminar permanentemente	Ninguno	Eliminar permanentemente un objeto servicePrincipal.
Asignaciones de roles de aplicación
Enumerar appRoleAssignments	Colección appRoleAssignment	Obtenga los roles de aplicación asignados a esta entidad de servicio.
Agregar appRoleAssignment	appRoleAssignment	Asigna un rol de aplicación a esta entidad de servicio.
Eliminar appRoleAssignment	Ninguna	Quita una asignación de roles de aplicación de esta entidad de servicio.
Enumerar appRoleAssignedTo	Colección appRoleAssignment	Obtiene los roles de aplicación asignados de usuarios, grupos y entidades de servicio para esta entidad de servicio.
Agregar appRoleAssignedTo	appRoleAssignment	Asigna un rol de aplicación para esta entidad de servicio a un usuario, grupo o entidad de servicio.
Quitar appRoleAssignedTo	Ninguna	Quita una asignación de roles de aplicación para esta entidad de servicio de un usuario, un grupo o una entidad de servicio.
Certificados y secretos
Add password	passwordCredential	Agregar una contraseña segura o un secreto a servicePrincipal.
Remove password	passwordCredential	Quitar una contraseña o un secreto de servicePrincipal.
Agregar clave	keyCredential	Agrega una credencial de clave a un servicePrincipal.
Quitar clave	Ninguna	Quita una credencial de clave de una servicePrincipal.
Agregar certificado de firma de token	selfSignedCertificate	Agregue un certificado autofirmado a la entidad de servicio. Se usa principalmente para configurar aplicaciones SSO basadas en SAML desde la galería de Microsoft Entra.
Clasificaciones de permisos delegados
Lista	Colección delegatedPermissionClassification	Obtener las clasificaciones de permisos para los permisos delegados expuestos por esta entidad de servicio.
Add	delegatedPermissionClassification	Agregar una clasificación de permisos para un permiso delegado expuesto por esta entidad de servicio.
Remove	Ninguno	Quitar una clasificación de permisos para un permiso delegado expuesto por esta entidad de servicio.
Concesión de permisos delegados (OAuth2)
Lista	Colección oAuth2PermissionGrant	Obtiene las concesiones de permisos delegados que autorizan a esta entidad de servicio a acceder a una API en nombre de un usuario que ha iniciado sesión.
Membership
Enumerar memberOf	Colección directoryObject	Obtiene los grupos de los que esta entidad de servicio es miembro directo desde la propiedad de navegación memberOf.
Lista de miembros transitivos de	Colección directoryObject	Enumera los grupos a los que pertenece esta entidad de servicio. Esta operación es transitiva e incluye los grupos de los que esta entidad de servicio es un miembro anidado.
Comprobar grupos de miembro	Colección de cadenas	Comprueba la pertenencia en una lista especificada de grupos.
Comprobar objetos miembro	Colección de cadenas	Comprobar la pertenencia en una lista específica de objetos de grupo, rol de directorio o unidad administrativa.
Obtener grupos de miembro	Colección de cadenas	Obtener la lista de los grupos a los que pertenece esta entidad de servicio.
Obtener objetos de miembro	Colección string	Obtener la lista de grupos, unidades administrativas y roles de directorio de los que esta entidad de servicio es miembro.
Propietarios
Lista	Colección directoryObject	Obtenga los propietarios de una entidad de servicio.
Add	directoryObject	Asignar un propietario a una entidad de servicio. Los propietarios de la entidad de servicio pueden ser usuarios u otras entidades de servicio.
Remove	Ninguno	Quitar un propietario de una entidad de servicio. Como práctica recomendada, las entidades de servicio deben tener al menos dos propietarios.

Propiedades

Importante

El uso específico de $filter y el parámetro de consulta $search solo se admite 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.

Propiedad	Tipo	Descripción
accountEnabled	Boolean	true si la entidad de servicio está habilitada; en caso contrario, false. Si se establece en false, ningún usuario podrá iniciar sesión en esta aplicación, incluso si están asignados a ella. Admite $filter (eq, ne, not y in).
addIns	Colección addIn	Permite definir el comportamiento personalizado que un servicio que consume puede usar para llamar a una aplicación en contextos específicos. Por ejemplo, las aplicaciones que pueden representar secuencias de archivo pueden establecer la propiedad addIns para su funcionalidad "FileHandler". Esto permite que servicios como Microsoft 365 llamen a la aplicación en el contexto de un documento en el que está trabajando el usuario.
alternativeNames	Colección de cadenas	Se usa para recuperar las entidades de servicio por suscripción, identificar el grupo de recursos e identificadores de recursos completos para las identidades administradas. Admite $filter (eq, not, ge, le y startsWith).
appDescription	Cadena	La descripción expuesta por la aplicación asociada.
appDisplayName	Cadena	El nombre para mostrar expuesto por la aplicación asociada. La longitud máxima es de 256 caracteres.
appId	Cadena	El identificador único para la aplicación asociada (su propiedad appId). Tecla alternativa. Admite $filter (eq, ne, not, in y startsWith).
applicationTemplateId	Cadena	Identificador único de applicationTemplate. Admite $filter (eq, not y ne). Solo lectura. null Si la entidad de servicio no se creó a partir de una plantilla de aplicación.
appOwnerOrganizationId	Guid	Contiene el ID. del inquilino en el que está registrada la aplicación. Esto solo se aplica a las entidades de servicio respaldadas por aplicaciones. Admite $filter (eq, ne, NOT, ge y le).
appRoleAssignmentRequired	Boolean	Especifica si los usuarios u otras entidades de servicio necesitan que se les otorgue una asignación de roles de aplicación para esta entidad de servicio para que los usuarios puedan iniciar sesión o las aplicaciones puedan obtener tokens. El valor predeterminado es false. No admite valores NULL. Admite $filter (eq, ne y NOT).
appRoles	Colección appRole	Los roles expuestos por la aplicación que está vinculada a esta entidad de servicio. Para obtener más información, consulte la definición de propiedad appRoles en la entidad de aplicación . No admite valores NULL. Los roles de aplicación y los ámbitos de permisos delegados expuestos (oauth2PermissionScopes) comparten un límite predeterminado de 700 definiciones de permisos por entidad de servicio, incluidas las definiciones heredadas de la aplicación y las definiciones agregadas directamente a la entidad de servicio. Tanto las definiciones habilitadas como las deshabilitadas cuentan. Este límite cuenta definiciones, no asignaciones de roles de aplicación. Para ver las reglas de recuento, el comportamiento de los objetos existentes por encima del límite y las instrucciones de diseño, consulte Límites de roles de la aplicación.
createdByAppId	Cadena	El appId de la aplicación que creó esta entidad de servicio. Establecido internamente por Microsoft Entra ID. Solo lectura.
customSecurityAttributes	customSecurityAttributeValue	Un tipo complejo abierto que contiene el valor de un atributo de seguridad personalizado que se asigna a un objeto de directorio. Admite un valor NULL. Requiere $select recuperarse. Admite $filter (eq, ne, not y startsWith). El valor del filtro distingue mayúsculas de minúsculas. Para leer esta propiedad, se debe asignar a la aplicación que realiza la llamada el permiso CustomSecAttributeAssignment.Read.All . Para escribir esta propiedad, se deben asignar a la aplicación que realiza la llamada los permisos CustomSecAttributeAssignment.ReadWrite.All . Para leer o escribir esta propiedad en escenarios delegados, se debe asignar al administrador el rol de Administrador de asignación de atributos .
deletedDateTime	DateTimeOffset	La fecha y la hora en que se eliminó la entidad de servicio. Solo lectura.
description	String	Campo de texto libre para proporcionar una descripción interna orientada al usuario final de la entidad de servicio. Los portales de usuario final, como MyApps , muestran la descripción de la aplicación en este campo. El tamaño máximo permitido es de 1024 caracteres. Admite $filter (eq, ne, not, ge, le, startsWith) y $search.
disabledByMicrosoftStatus	Cadena	Especifica si Microsoft ha deshabilitado la aplicación registrada. Los valores posibles son: null (valor predeterminado) NotDisabledy DisabledDueToViolationOfServicesAgreement (las razones incluyen actividad sospechosa, abusiva o malintencionada, o una infracción del Contrato de servicios de Microsoft). Admite $filter (eq, ne y not).
displayName	Cadena	El nombre para mostrar de la entidad de servicio. Admite $filter (eq, ne, not, ge, le, in, startsWith y eq en valores null), $search y $orderby.
homepage	String	La página de inicio o la página de aterrizaje de la aplicación.
id	Cadena	Identificador único para la entidad de servicio. Heredado de directoryObject. Clave. No admite valores NULL. Solo lectura. Admite $filter (eq, ne, not, in).
info	informationalUrl	Información de perfil básica de la aplicación adquirida, como las direcciones URL de marketing, soporte técnico, condiciones del servicio y declaración de privacidad de la aplicación. Las condiciones del servicio y la declaración de privacidad se exponen a los usuarios mediante la experiencia de consentimiento del usuario. Para obtener más información, consulta Cómo: Agregar términos de servicio y declaración de privacidad para las aplicaciones de Microsoft Entra registradas. Admite $filter (eq, ne, not, ge, le y eq en valores null).
keyCredentials	Colección keyCredential	El conjunto de credenciales clave asociadas con la entidad de servicio. No admite valores NULL. Admite $filter (eq, not, ge, le).
loginUrl	Cadena	Especifica la dirección URL a la que el proveedor de servicios redirige al usuario a Microsoft Entra ID para autenticarse. Microsoft Entra ID usa la dirección URL para iniciar la aplicación desde Microsoft 365 o el Microsoft Entra Aplicaciones. Cuando está en blanco, Microsoft Entra ID realiza el inicio de sesión iniciado por el IdP para las aplicaciones configuradas con el inicio de sesión único basado en SAML. El usuario inicia la aplicación desde Microsoft 365, la Microsoft Entra Aplicaciones o la dirección URL de SSO Microsoft Entra.
logoutUrl	Cadena	Especifica la dirección URL que usa el servicio de autorización de Microsoft para cerrar la sesión de un usuario mediante los protocolos de cierre de sesión de canal frontal, canal posterior o SAML de OpenID Connect.
notas	Cadena	Campo de texto libre para capturar información sobre la entidad de servicio, que suele usarse con fines operativos. El tamaño máximo permitido es de 1024 caracteres.
notificationEmailAddresses	Colección de cadenas	Especifica la lista de direcciones de correo electrónico en las que Microsoft Entra ID envía una notificación cuando el certificado activo está cerca de la fecha de expiración. Esto es solo para los certificados utilizados para firmar el token SAML emitido para las aplicaciones de Microsoft Entra Gallery.
oauth2PermissionScopes	Colección permissionScope	Los permisos delegados expuestos por la aplicación. Para obtener más información, consulte la propiedad oauth2PermissionScopes en la propiedad de API de la entidad de aplicación. No admite valores NULL. Estos ámbitos y appRoles comparten un límite predeterminado de 700 definiciones de permisos por entidad de servicio. Tanto las definiciones habilitadas como las deshabilitadas cuentan. Para ver las reglas de recuento, el comportamiento de los objetos existentes por encima del límite y las instrucciones de diseño, consulte Límites de roles de la aplicación.
passwordCredentials	Colección passwordCredential	Conjunto de credenciales de contraseña asociadas a la aplicación. No admite valores NULL.
preferredSingleSignOnMode	cadena	Especifica el modo de inicio de sesión único configurado para esta aplicación. Microsoft Entra ID usa el modo de inicio de sesión único preferido para iniciar la aplicación desde Microsoft 365 o el portal Mis Aplicaciones. Los valores admitidos son: password, saml, notSupported y oidc. Nota: Este campo puede ser null para aplicaciones SAML anteriores y para aplicaciones OIDC donde no se establece automáticamente.
preferredTokenSigningKeyThumbprint	Cadena	Esta propiedad se puede usar en aplicaciones SAML (aplicaciones que tienen preferredSingleSignOnMode establecido en saml) para controlar qué certificado se usa para firmar las respuestas SAML. Para las aplicaciones que no son SAML, no escriba ni confíe en esta propiedad.
replyUrls	Colección de cadenas	Las direcciones URL a las que se envía los tokens de usuario para iniciar sesión con la aplicación asociada o el URI de redireccionamiento al que se envían los códigos de autorización de OAuth 2.0 y los tokens de acceso de la aplicación asociada. No admite valores NULL.
resourceSpecificApplicationPermissions	colección resourceSpecificPermission	Los permisos de aplicación específicos de los recursos expuestos por esta aplicación. Actualmente, los permisos específicos de los recursos sólo son compatibles con las aplicaciones de Teams que acceden a chats y equipos específicos mediante Microsoft Graph. Solo lectura.
samlSingleSignOnSettings	samlSingleSignOnSettings	La colección de configuraciones relacionadas con el inicio de sesión único de SAML.
servicePrincipalNames	Colección de cadenas	Contiene la lista de identifiersUris, copiada desde la aplicación asociada. Se pueden agregar valores adicionales a las aplicaciones híbridas. Estos valores se pueden usar para identificar los permisos expuestos por esta aplicación en Microsoft Entra ID. Por ejemplo, Las aplicaciones cliente pueden especificar un URI de recurso que se basa en los valores de esta propiedad para adquirir un token de acceso, que es el URI devuelto en la notificación "aud". El operador any es necesario para las expresiones de filtro en las propiedades de varios valores. No admite valores NULL. Admite $filter (eq, not, ge, le y startsWith).
servicePrincipalType	Cadena	Identifica si la entidad de servicio representa una aplicación, una identidad administrada o una aplicación heredada. Esta propiedad la establece Microsoft Entra ID internamente. La propiedad servicePrincipalType puede establecerse en tres valores diferentes: Application - Una entidad de servicio que representa una aplicación o servicio. La propiedad appId identifica el registro de la aplicación asociado y coincide con la appId de una aplicación, posiblemente de otro espacio empresarial. Si falta el registro de la aplicación asociado, no se emiten tokens para la entidad de servicio. ManagedIdentity - Una entidad de servicio que representa una identidad administrada. A las entidades de servicio que representan identidades administradas se les puede conceder acceso y permisos, pero no se pueden actualizar ni modificar directamente. Legacy - Una entidad de servicio que representa una aplicación creada antes de los registros de aplicaciones o a través de experiencias heredadas. Una entidad de servicio heredada puede tener credenciales, nombres de entidad de seguridad de servicio, direcciones URL de respuesta y otras propiedades que puede editar un usuario autorizado, pero no tiene un registro de aplicación asociado. El valor appId no asocia la entidad de servicio con un registro de aplicaciones. La entidad de servicio solo puede usarse en el espacio empresarial donde se creó. ServiceIdentity - Una entidad de servicio que representa la identidad de un agente. SocialIdp - Para uso interno.
signInAudience	Cadena	Especifica las cuentas de Microsoft compatibles con la aplicación actual. Solo lectura. Los valores admitidos son los siguientes: AzureADMyOrg: Usuarios con una cuenta profesional o educativa de Microsoft en el inquilino de Microsoft Entra de mi organización (inquilino único). AzureADMultipleOrgs: usuarios con una cuenta profesional o educativa de Microsoft en el inquilino de Microsoft Entra de cualquier organización (multiinquilino). AzureADandPersonalMicrosoftAccount: Usuarios con una cuenta personal de Microsoft o una cuenta profesional o educativa en el inquilino de Microsoft Entra de cualquier organización. PersonalMicrosoftAccount: Solo usuarios con una cuenta de Microsoft personal.
tags	Colección de cadenas	Cadenas personalizadas que pueden usarse para clasificar por categorías e identificar la entidad de servicio. No admite valores NULL. El valor es la unión de cadenas establecida aquí y en la propiedad tags de la entidad de aplicación asociada. Admite $filter (eq, not, ge, le y startsWith).
tokenEncryptionKeyId	Cadena	Especifica el valor keyId de una clave pública de la colección keyCredentials. Cuando se configura, Microsoft Entra ID emite tokens para esta aplicación cifrados con la clave especificada por esta propiedad. El código de aplicación que recibe el token cifrado debe usar la clave privada coincidente para descifrar el token a fin de poder usarlo para el usuario que ha iniciado sesión.
verifiedPublisher	verifiedPublisher	Especifica el publicador comprobado de la aplicación que está vinculada a esta entidad de servicio.

Relaciones

Importante

El uso específico del $filter parámetro de consulta solo se admite cuando se usa el conjunto de encabezados ConsistencyLevel en eventual y $count. Para obtener más información, vea Funcionalidades avanzadas de consulta en objetos de directorio.

Relación	Tipo	Descripción
appManagementPolicies	Colección appManagementPolicy	AppManagementPolicy aplicado a esta aplicación.
appRoleAssignedTo	appRoleAssignment	Asignaciones de roles de aplicación para esta aplicación o servicio, concedidos a usuarios, grupos y otras entidad de servicio. Admite $expand.
appRoleAssignments	Colección appRoleAssignment	Asignación de roles de aplicación para otra aplicación o servicio, concedido a esta entidad de servicio. Admite $expand.
claimsMappingPolicies	Colección claimsMappingPolicy	Las colecciones claimsMappingPolicies asignadas a esta entidad de servicio. Admite $expand.
createdObjects	Colección directoryObject	Objetos de directorio creados mediante esta entidad de servicio. Solo lectura. Admite valores NULL.
federatedIdentityCredentials	Colección federatedIdentityCredential	Identidades federadas para un tipo específico de entidad de servicio: identidad administrada. Admite $expand y $filter (/$count eq 0, /$count ne 0).
homeRealmDiscoveryPolicies	Colección homeRealmDiscoveryPolicy	La colección homeRealmDiscoveryPolicies asignada a esta entidad de servicio. Admite $expand.
memberOf	Colección directoryObject	Roles a los que pertenece esta entidad de servicio. Métodos HTTP: GET de solo lectura. Admite un valor NULL. Admite $expand.
oauth2PermissionGrants	Colección oAuth2PermissionGrant	El permiso delegado concede acceso a esta entidad de servicio para que pueda acceder a una API en nombre de un usuario que ha iniciado sesión. Solo lectura. Admite valores NULL.
ownedObjects	Colección directoryObject	Directory de los que es propietaria esta entidad de servicio. Solo lectura. Admite valores NULL. Admite $expand, $select anidado en $expandy $filter (/$count eq 0, /$count ne 0, /$count eq 1, /$count ne 1).
owners	Colección directoryObject	Objetos de directorio que son propietarios de este servicePrincipal. Los propietarios son un conjunto de usuarios no administradores o entidades de servicio que pueden modificar este objeto. Admite $expand, $filter (/$count eq 0, /$count ne 0, /$count eq 1/$count ne 1, ) y $select anidado en $expand.
remoteDesktopSecurityConfiguration	remoteDesktopSecurityConfiguration	El objeto remoteDesktopSecurityConfiguration aplicado a esta entidad de servicio. Admite $filter (eq) para la propiedad isRemoteDesktopProtocolEnabled .
Sincronización	sincronización	Representa la capacidad de sincronización de identidades de Microsoft Entra a través de la API de Microsoft Graph API.
tokenIssuancePolicies	Colección tokenIssuancePolicy	Las tokenIssuancePolicies asignadas a esta entidad de servicio.
tokenLifetimePolicies	Colección tokenLifetimePolicy	La colección tokenLifetimePolicies asignada a esta entidad de servicio.

Representación JSON

La siguiente representación JSON muestra el tipo de recurso.

{
  "accountEnabled": true,
  "addIns": [{"@odata.type": "microsoft.graph.addIn"}],
  "alternativeNames": ["String"] ,
  "appDisplayName": "String",
  "appId": "String",
  "appOwnerOrganizationId": "Guid",
  "appRoleAssignmentRequired": true,
  "appRoles": [{"@odata.type": "microsoft.graph.appRole"}],
  "createdByAppId": "String",
  "customSecurityAttributes": {
    "@odata.type": "microsoft.graph.customSecurityAttributeValue"
  },
  "disabledByMicrosoftStatus": "String",
  "displayName": "String",
  "homepage": "String",
  "id": "String (identifier)",
  "info": {"@odata.type": "microsoft.graph.informationalUrl"},
  "keyCredentials": [{"@odata.type": "microsoft.graph.keyCredential"}],
  "logoutUrl": "String",
  "notes": "String",
  "oauth2PermissionScopes": [{"@odata.type": "microsoft.graph.permissionScope"}],
  "passwordCredentials": [{"@odata.type": "microsoft.graph.passwordCredential"}],
  "preferredTokenSigningKeyThumbprint": "String",
  "replyUrls": ["String"],
  "resourceSpecificApplicationPermissions": [{"@odata.type": "microsoft.graph.resourceSpecificPermission"}],
  "servicePrincipalNames": ["String"],
  "servicePrincipalType": "String",
  "tags": ["String"],
  "tokenEncryptionKeyId": "String",
  "verifiedPublisher": {"@odata.type": "microsoft.graph.verifiedPublisher"}
}