Microsoft.Graph servicePrincipals

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

注意

个人Microsoft帐户的权限不能用于部署 Bicep 文件中声明的 Microsoft Graph 资源。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	Application.ReadWrite.All	Directory.ReadWrite.All
委派（个人 Microsoft 帐户）	不支持。	不支持。
应用程序	Application.ReadWrite.OwnedBy	Application.ReadWrite.All、Directory.ReadWrite.All

资源格式

若要创建 Microsoft.Graph/servicePrincipals 资源，请将以下 Bicep 添加到模板。

resource symbolicname 'Microsoft.Graph/servicePrincipals@beta' = {
  accountEnabled: bool
  addIns: [
    {
      id: 'string'
      properties: [
        {
          key: 'string'
          value: 'string'
        }
      ]
      type: 'string'
    }
  ]
  alternativeNames: [
    'string'
  ]
  appDescription: 'string'
  appDisplayName: 'string'
  appId: 'string'
  appRoleAssignmentRequired: bool
  appRoles: [
    {
      allowedMemberTypes: [
        'string'
      ]
      description: 'string'
      displayName: 'string'
      id: 'string'
      isEnabled: bool
      value: 'string'
    }
  ]
  description: 'string'
  disabledByMicrosoftStatus: 'string'
  displayName: 'string'
  homepage: 'string'
  info: {
    marketingUrl: 'string'
    privacyStatementUrl: 'string'
    supportUrl: 'string'
    termsOfServiceUrl: 'string'
  }
  keyCredentials: [
    {
      customKeyIdentifier: 'string'
      displayName: 'string'
      endDateTime: 'string'
      key: 'string'
      keyId: 'string'
      startDateTime: 'string'
      type: 'string'
      usage: 'string'
    }
  ]
  loginUrl: 'string'
  logoutUrl: 'string'
  notes: 'string'
  notificationEmailAddresses: [
    'string'
  ]
  passwordCredentials: [
    {
      displayName: 'string'
      endDateTime: 'string'
      keyId: 'string'
      startDateTime: 'string'
    }
  ]
  preferredSingleSignOnMode: 'string'
  preferredTokenSigningKeyEndDateTime: 'string'
  preferredTokenSigningKeyThumbprint: 'string'
  publishedPermissionScopes: [
    {
      adminConsentDescription: 'string'
      adminConsentDisplayName: 'string'
      id: 'string'
      isEnabled: bool
      type: 'string'
      userConsentDescription: 'string'
      userConsentDisplayName: 'string'
      value: 'string'
    }
  ]
  publisherName: 'string'
  replyUrls: [
    'string'
  ]
  samlMetadataUrl: 'string'
  samlSingleSignOnSettings: {
    relayState: 'string'
  }
  servicePrincipalNames: [
    'string'
  ]
  servicePrincipalType: 'string'
  tags: [
    'string'
  ]
  tokenEncryptionKeyId: 'string'
  verifiedPublisher: {
    addedDateTime: 'string'
    displayName: 'string'
    verifiedPublisherId: 'string'
  }
}

属性值

servicePrincipals

名称	描述	值
accountEnabled	如果已启用服务主体帐户，则为 true;否则为 false。 如果设置为 false，则用户无法登录到此应用，即使他们已分配到此应用	布尔
addIns	定义自定义行为，供消耗型服务在特定上下文中调用应用。 例如，可以呈现文件流的应用程序可以为其“FileHandler”功能设置 addIns 属性。 这样，Microsoft 365 等服务就可以在用户正在处理的文档上下文中调用应用程序。	MicrosoftGraphAddIn[]
alternativeNames	用于按订阅检索服务主体，标识托管标识的资源组和完整资源 ID	string[]
apiVersion	资源 API 版本	“beta”（ReadOnly）
appDescription	关联应用程序公开的说明。	string
appDisplayName	关联应用程序公开的显示名称。	string
appId	关联的应用程序的唯一标识符（其 appId 属性）。 备用键	string （必需）
applicationTemplateId	applicationTemplate 的唯一标识符。 只读。 如果未从应用程序模板创建应用，则为 null。	string （ReadOnly）
appOwnerOrganizationId	包含注册应用程序的租户 ID。 这仅适用于应用程序支持的服务主体	string （ReadOnly） 约束： 最小长度 = 36 最大长度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
appRoleAssignmentRequired	指定在用户可以登录或应用获取令牌之前，是否需要为此服务主体授予用户或其他服务主体的应用角色分配。 默认值为 false。 不可为 null	布尔
appRoles	应用程序公开的角色，此服务主体表示。 有关详细信息，请参阅应用程序实体上的 appRoles 属性定义。 不可为 Null。	MicrosoftGraphAppRole[]
deletedDateTime	删除此对象的日期和时间。 当对象尚未删除时，始终为 null。	string （ReadOnly）
description	用于提供面向服务主体的内部最终用户说明的免费文本字段。 此类 MyApps 的最终用户门户在此字段中显示应用程序说明。 允许的最大大小为 1,024 个字符	string
disabledByMicrosoftStatus	指定Microsoft是否已禁用已注册的应用程序。 可能的值包括：null（默认值）、NotDisabled 和 DisabledDueToViolationOfServicesAgreement（原因可能包括可疑、滥用或恶意活动，或违反Microsoft服务协议）	string
displayName	服务主体的显示名称	string
主页	应用程序的主页或登陆页。	string
id	实体的唯一标识符。 只读。	string （ReadOnly）
info	获取的应用程序的基本配置文件信息，例如应用的营销、支持、服务条款和隐私声明 URL。 服务条款和隐私声明通过用户同意体验展示给用户。 有关详细信息，请参阅如何：为已注册的 Microsoft Entra 应用添加服务条款和隐私声明	MicrosoftGraphInformationalUrl
keyCredentials	与服务主体关联的密钥凭据的集合。 不可为 null	MicrosoftGraphKeyCredential[]
loginUrl	指定服务提供商将用户重定向到Microsoft Entra ID 进行身份验证的 URL。 Microsoft Entra ID 使用 URL 从 Microsoft 365 或 Microsoft Entra 我的应用启动应用程序。 当为空时，Microsoft Entra ID 对配置了基于 SAML 的单一登录的应用程序执行 IdP 发起的登录。 用户从 Microsoft 365、Microsoft Entra 我的应用 或 Microsoft Entra SSO URL 启动应用程序。	string
logoutUrl	指定Microsoft授权服务用于使用 OpenId Connect 前端通道、后通道或 SAML 注销协议注销用户的 URL。	string
说明	用于捕获有关服务主体的信息（通常用于操作目的）的免费文本字段。 允许的最大大小为 1,024 个字符。	string
notificationEmailAddresses	指定当活动证书接近到期日期时，Microsoft Entra ID 发送通知的电子邮件地址列表。 这仅适用于用于对Microsoft Entra 库应用程序颁发的 SAML 令牌进行签名的证书。	string[]
passwordCredentials	与服务主体关联的密码凭据集合。 不可为 Null。	MicrosoftGraphPasswordCredential[]
preferredSingleSignOnMode	指定为此应用程序配置的单一登录模式。 Microsoft Entra ID 使用首选的单一登录模式从 Microsoft 365 或 Microsoft Entra 我的应用 启动应用程序。 支持的值包括密码、saml、notSupported 和 oidc。	string
preferredTokenSigningKeyEndDateTime	指定用于令牌签名的 keyCredential 的到期日期，由 preferredTokenSigningKeyThumbprint 标记。 目前不支持更新此属性。 有关详细信息，请参阅 ServicePrincipal 属性差异。	string
preferredTokenSigningKeyThumbprint	此属性可用于 SAML 应用程序（已将 preferredSingleSignOnMode 设置为 saml 的应用）来控制用于对 SAML 响应进行签名的证书。 对于非 SAML 的应用程序，请勿写入或依赖此属性。	string
publishedPermissionScopes	应用程序公开的委托权限。 有关详细信息，请参阅应用程序实体 API 属性上的 oauth2PermissionScopes 属性。 不可为 Null。 注意：此属性在 v1.0 中命名为 oauth2PermissionScopes。	MicrosoftGraphPermissionScope[]
publisherName	发布应用程序的 Microsoft Entra 租户的名称。	string
replyUrls	用户令牌发送到的 URL 用于与关联的应用程序登录，或 OAuth 2.0 授权代码和访问令牌发送到的重定向 URI 供关联应用程序使用。 不可为 Null。	string[]
samlMetadataUrl	服务公开用于联合身份验证的 SAML 元数据的 URL。	string
samlSingleSignOnSettings	与 saml 单一登录相关的设置的集合。	MicrosoftGraphSamlSingleSignOnSettings
servicePrincipalNames	包含从关联的应用程序复制的 identifiersUris 列表。 可将更多值添加到混合应用程序。 这些值可用于标识此应用在 Microsoft Entra ID 中公开的权限。 例如，客户端应用可以指定一个资源 URI，该 URI 基于此属性的值来获取访问令牌，这是“aud”声明中返回的 URI。筛选多值属性上的表达式需要任何运算符。 不可为 null	string[]
servicePrincipalType	标识服务主体是否表示应用程序或托管标识。 这是由内部Microsoft Entra ID 设置的。 对于表示应用程序的服务主体，此服务主体设置为“应用程序”。 对于表示托管标识的服务主体，此标识设置为 ManagedIdentity。 SocialIdp 类型供内部使用。	string
signInAudience	指定当前应用程序支持的Microsoft帐户。 只读。 支持的值为：AzureADMyOrg：我的组织的 Microsoft Entra 租户（单租户）中具有Microsoft工作或学校帐户的用户。AzureADMultipleOrgs：任何组织的 Microsoft Entra 租户（多租户）中具有Microsoft工作或学校帐户的用户。AzureADandPersonalMicrosoftAccount：具有个人Microsoft帐户的用户，或者任何组织的 Microsoft Entra 租户中的工作或学校帐户。PersonalMicrosoftAccount：仅具有个人Microsoft帐户的用户。	string （ReadOnly）
标记	可用于对服务主体进行分类和标识的自定义字符串。 不可为 null	string[]
tokenEncryptionKeyId	指定 keyCredentials 集合中公钥的 keyId。 配置后，Microsoft Entra ID 颁发使用此属性指定的密钥加密的此应用程序的令牌。 接收加密令牌的应用程序代码必须使用匹配的私钥对令牌进行解密，然后才能将其用于登录用户。	string 约束： 最小长度 = 36 最大长度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
type	资源类型	“Microsoft.Graph/servicePrincipals”（ReadOnly）
verifiedPublisher	指定链接到此服务主体的应用程序的已验证发布者。	MicrosoftGraphVerifiedPublisher

MicrosoftGraphKeyValue

名称	描述	值
key	包含与值关联的字段的名称。	string
value	包含指定键的相应值。	string

MicrosoftGraphAddIn

名称	描述	值
id	addIn 对象的唯一标识符。	string 约束： 最小长度 = 36 最大长度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
properties	用于定义使用服务可以使用或调用的参数的键值对的集合。 在 addIns 集合上执行 POST 或 PATCH 操作时，必须指定此属性。 必需。	MicrosoftGraphKeyValue[]
type	应用公开的功能的唯一名称。	string

MicrosoftGraphAppRole

名称	描述	值
allowedMemberTypes	指定此应用角色是否可以分配给用户和组（通过设置为 ['User']）、其他应用程序的 （通过设置为 ['Application'] 或两者（通过设置为 ['User'， 'Application']） 。 支持分配给其他应用程序服务主体的应用角色也称为应用程序权限。 仅应用程序实体上定义的应用角色支持“应用程序”值。	string[]
description	应用角色的说明。 在分配应用角色时，如果应用角色在许可体验期间充当应用程序权限，则会显示这一点。	string
displayName	应用角色分配和许可体验中显示的权限的显示名称。	string
id	appRoles 集合中的唯一角色标识符。 创建新应用角色时，必须指定新的 GUID 标识符。	string 约束： 最小长度 = 36 最大长度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
isEnabled	创建或更新应用角色时，必须将其设置为 true（这是默认值）。 若要删除角色，必须先将其设置为 false。 此时，在后续调用中，可能会删除此角色。	布尔
origin	指定应用角色是在应用程序对象还是 servicePrincipal 实体上定义。 不得包含在任何 POST 或 PATCH 请求中。 只读。	string （ReadOnly）
value	指定在 ID 令牌中的角色声明中包含的值，以及对分配的用户或服务主体进行身份验证的访问令牌。 长度不得超过 120 个字符。 允许的字符为 ： ！ # $ % & ' ( ) * + , -. / : ;= ? @ [ ] ^ + _ { } ~，以及范围 0-9、A-Z 和 a-z 中的字符。 不允许任何其他字符（包括空格字符）。 可能不是以 .开头。	string

MicrosoftGraphInformationalUrl

名称	描述	值
logoUrl	应用程序徽标的 CDN URL，只读。	string （ReadOnly）
marketingUrl	链接到应用程序的市场营销页面。 例如： https://www.contoso.com/app/marketing	string
privacyStatementUrl	链接到应用程序的隐私声明。 例如： https://www.contoso.com/app/privacy	string
支持 URL	链接到应用程序的支持页。 例如： https://www.contoso.com/app/support	string
termsOfServiceUrl	链接到应用程序的服务条款声明。 例如： https://www.contoso.com/app/termsofservice	string

MicrosoftGraphKeyCredential

名称	描述	值
customKeyIdentifier	可用于标识凭据的 40 个字符的二进制类型。 可选。 如果未在有效负载中提供，则默认为证书的指纹。	string
displayName	密钥的友好名称。 可选。	string
endDateTime	凭据过期的日期和时间。 DateTimeOffset 类型表示使用 ISO 8601 格式的日期和时间信息，并且始终采用 UTC 时间。 例如，2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00：00：00Z。	string
key	密钥凭据的值。 应为 Base64 编码值。 从.cer证书中，可以使用 Convert.ToBase64String（） 方法读取密钥。 有关详细信息，请参阅获取证书密钥。	string
keyId	密钥的唯一标识符。	string 约束： 最小长度 = 36 最大长度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
startDateTime	凭据生效的日期和时间。时间戳类型表示使用 ISO 8601 格式的日期和时间信息，并且始终采用 UTC 时间。 例如，2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00：00：00Z。	string
type	密钥凭据的类型;例如，Symmetric、AsymmetricX509Cert 或 X509CertAndPassword。	string
使用情况	描述密钥的用途的字符串;例如，None、Verify、PairwiseIdentifier、Delegation、Decrypt、Encrypt、HashedIdentifier、SelfSignedTls 或 Sign。 如果用法为 Sign，则类型应为 X509CertAndPassword，并且应定义用于签名的 passwordCredentials。	string

MicrosoftGraphPasswordCredential

名称	描述	值
displayName	密码的友好名称。 可选。	string
endDateTime	密码过期的日期和时间使用 ISO 8601 格式表示，并且始终采用 UTC 时间。 例如，2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00：00：00Z。 可选。	string
hint	包含密码的前三个字符。 只读。	string （ReadOnly）
keyId	密码的唯一标识符。	string 约束： 最小长度 = 36 最大长度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
secretText	只读;包含由 Microsoft Entra ID 生成的强密码，长度为 16-64 个字符。 生成的密码值仅在初始 POST 请求中添加Password 期间返回。 将来无法检索此密码。	string （ReadOnly）
startDateTime	密码生效的日期和时间。 时间戳类型表示使用 ISO 8601 格式的日期和时间信息，并且始终采用 UTC 时间。 例如，2014 年 1 月 1 日午夜 UTC 为 2014-01-01T00：00：00Z。 可选。	string

MicrosoftGraphPermissionScope

名称	描述	值
adminConsentDescription	委派权限的说明，旨在由代表所有用户授予权限的管理员读取。 此文本显示在租户范围的管理员许可体验中。	string
adminConsentDisplayName	权限的标题，旨在由管理员代表所有用户授予权限。	string
id	为资源应用程序定义的委派权限集合内的唯一委托权限标识符。	string 约束： 最小长度 = 36 最大长度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
isEnabled	创建或更新权限时，此属性必须设置为 true（默认值）。 若要删除权限，必须先将此属性设置为 false。 此时，在后续调用中，可能会删除权限。	布尔
type	可能的值包括：用户和管理员。指定是否应将此委派权限视为安全，以便非管理员用户代表自己同意，还是应始终要求管理员同意。 虽然 Microsoft Graph 定义了每个权限的默认同意要求，但租户管理员可以替代其组织中的行为（允许、限制或限制用户对此委派权限的同意）。 有关详细信息，请参阅配置最终用户对应用程序表示同意的方式。	string
userConsentDescription	委托权限的说明，旨在由代表自己授予权限的用户读取。 此文本显示在用户仅代表自己同意的同意体验中。	string
userConsentDisplayName	权限的游戏，旨在由代表自己授予权限的用户读取。 此文本显示在用户仅代表自己同意的同意体验中。	string
value	指定要包含在访问令牌中的 scp （scope） 声明中的值。 长度不得超过 120 个字符。 允许的字符为 ： ！ # $ % & ' ( ) * + , -. / : ;= ? @ [ ] ^ + _ { } ~，以及范围 0-9、A-Z 和 a-z 中的字符。 不允许任何其他字符（包括空格字符）。 可能不是以 .开头。	string

MicrosoftGraphSamlSingleSignOnSettings

名称	描述	值
relayState	服务提供商在完成单一登录流后会重定向到的相对 URI。	string

MicrosoftGraphVerifiedPublisher

名称	描述	值
addedDateTime	首次添加或最近更新已验证的发布者时的时间戳。	string
displayName	应用发布者的Microsoft合作伙伴网络（MPN）帐户中已验证的发布者名称。	string
verifiedPublisherId	应用发布者的合作伙伴中心帐户中已验证的发布者的 ID。	string