Manifesto da aplicação Microsoft Entra

O manifesto do aplicativo contém uma definição de todos os atributos de um objeto de aplicativo na plataforma de identidade da Microsoft. Ele também serve como um mecanismo para atualizar o objeto do aplicativo. Para obter mais informações sobre a entidade Application e seu esquema, consulte a documentação da entidade Graph API Application.

Você pode configurar os atributos de um aplicativo por meio do centro de administração do Microsoft Entra ou programaticamente usando a API do Microsoft Graph ou o SDK do Microsoft Graph PowerShell. No entanto, há alguns cenários em que você precisa editar o manifesto do aplicativo para configurar o atributo de um aplicativo. Os cenários incluem:

  • Se você registrou o aplicativo como contas multilocatárias e pessoais da Microsoft Entra, não poderá alterar as contas da Microsoft com suporte na interface do usuário. Em vez disso, você deve usar o editor de manifesto do aplicativo para alterar o tipo de conta suportada.
  • Para definir permissões e funções suportadas pelo seu aplicativo, você deve modificar o manifesto do aplicativo.

Configurar o manifesto do aplicativo

Para configurar o manifesto do aplicativo:

  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.
  2. Navegue até Registros do aplicativo Identity>Applications>.
  3. Selecione o aplicativo que você deseja configurar.
  4. A partir da página Descrição geral da aplicação, selecione a secção Manifesto. Um editor de manifesto baseado na Web é aberto, permitindo que você edite o manifesto. Opcionalmente, você pode selecionar Download para editar o manifesto localmente e, em seguida, usar Upload para reaplicá-lo ao seu aplicativo.

Referência do manifesto

Esta seção descreve os atributos encontrados no manifesto do aplicativo.

atributo id

Chave Tipo de Valor
id String

O identificador exclusivo do aplicativo no diretório. Esse ID não é o identificador usado para identificar o aplicativo em qualquer transação de protocolo. Use-o para referenciar o objeto em consultas de diretório.

Exemplo:

    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",

atributo acceptMappedClaims

Chave Tipo de Valor
acceptMappedClaims Booleano anulável

Conforme documentado no tipo de recurso, isso permite que um aplicativo use o apiApplication mapeamento de declarações sem especificar uma chave de assinatura personalizada. Os aplicativos que recebem tokens dependem do fato de que os valores de declaração são emitidos autoritariamente pelo Microsoft Entra ID e não podem ser adulterados. No entanto, quando você modifica o conteúdo do token por meio de políticas de mapeamento de declarações, essas suposições podem não estar mais corretas. Os aplicativos devem reconhecer explicitamente que os tokens foram modificados pelo criador da política de mapeamento de declarações para se protegerem de políticas de mapeamento de declarações criadas por agentes mal-intencionados.

Aviso

Não defina acceptMappedClaims a propriedade como true para aplicativos multilocatário, o que pode permitir que atores mal-intencionados criem políticas de mapeamento de declarações para seu aplicativo.

Exemplo:

    "acceptMappedClaims": true,

atributo accessTokenAcceptedVersion

Chave Tipo de Valor
accessTokenAcceptedVersion Int32 anulável

Especifica a versão do token de acesso esperada pelo recurso. Esse parâmetro altera a versão e o formato do JWT produzido independentemente do ponto de extremidade ou cliente usado para solicitar o token de acesso.

O ponto de extremidade usado, v1.0 ou v2.0, é escolhido pelo cliente e afeta apenas a versão do id_tokens. Os recursos precisam ser configurados accesstokenAcceptedVersion explicitamente para indicar o formato de token de acesso suportado.

Os valores possíveis para accesstokenAcceptedVersion são 1, 2 ou null. Se o valor for null, esse parâmetro assume como padrão 1, que corresponde ao ponto de extremidade v1.0.

Se signInAudience for AzureADandPersonalMicrosoftAccount, o valor deve ser 2.

Exemplo:

    "accessTokenAcceptedVersion": 2,

atributo addIns

Chave Tipo de Valor
Suplementos Coleção

Define o comportamento personalizado que um serviço consumidor pode usar para chamar um aplicativo em contextos específicos. Por exemplo, aplicativos que podem renderizar fluxos de arquivos podem definir a addIns propriedade para sua funcionalidade "FileHandler". Esse parâmetro permite que serviços como o Microsoft 365 chamem o aplicativo no contexto de um documento no qual o usuário está trabalhando.

Exemplo:

    "addIns": [
       {
        "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "type":" FileHandler",
        "properties": [
           {
              "key": "version",
              "value": "2"
           }
        ]
       }
    ],

atributo allowPublicClient

Chave Tipo de Valor
allowPublicClient Boolean

Especifica o tipo de aplicativo de fallback. O ID do Microsoft Entra infere o tipo de aplicativo do replyUrlsWithType por padrão. Há certos cenários em que o Microsoft Entra ID não pode determinar o tipo de aplicativo cliente. Por exemplo, um desses cenários é o fluxo ROPC onde a solicitação HTTP acontece sem um redirecionamento de URL). Nesses casos, o Microsoft Entra ID interpreta o tipo de aplicativo com base no valor dessa propriedade. Se esse valor for definido como true, o tipo de aplicativo de fallback será definido como cliente público, como um aplicativo instalado em execução em um dispositivo móvel. O valor padrão é false, o que significa que o tipo de aplicativo de fallback é um cliente confidencial, como o aplicativo Web.

Exemplo:

    "allowPublicClient": false,

atributo appId

Chave Tipo de Valor
appId String

Especifica o identificador exclusivo para o aplicativo atribuído a um aplicativo pela ID do Microsoft Entra.

Exemplo:

    "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",

atributo appRoles

Chave Tipo de Valor
appRoles Coleção

Especifica a coleção de funções que um aplicativo pode declarar. Essas funções podem ser atribuídas a usuários, grupos ou entidades de serviço. Para obter mais exemplos e informações, consulte Adicionar funções de aplicativo em seu aplicativo e recebê-las no token.

Exemplo:

    "appRoles": [
        {
           "allowedMemberTypes": [
               "User"
           ],
           "description": "Read-only access to device information",
           "displayName": "Read Only",
           "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
           "isEnabled": true,
           "value": "ReadOnly"
        }
    ],

atributo errorUrl

Chave Tipo de Valor
errorUrl String

Não suportado.

atributo groupMembershipClaims

Chave Tipo de Valor
groupMembershipClaims String

Configura a groups declaração emitida em um usuário ou token de acesso OAuth 2.0 esperado pelo aplicativo. Para definir esse atributo, use um dos seguintes valores de cadeia de caracteres válidos:

  • "None"
  • "SecurityGroup" (para grupos de segurança e funções do Microsoft Entra)
  • "ApplicationGroup" (esta opção inclui apenas grupos atribuídos à aplicação)
  • "DirectoryRole" (obtém as funções de diretório do Microsoft Entra das quais o usuário é membro)
  • "All" (isso obterá todos os grupos de segurança, grupos de distribuição e funções de diretório do Microsoft Entra dos quais o usuário conectado é membro).

Exemplo:

    "groupMembershipClaims": "SecurityGroup",

atributo optionalClaims

Chave Tipo de Valor
opcionalReivindicações String

As declarações opcionais retornadas no token pelo serviço de token de segurança para este aplicativo específico.

As aplicações que suportam contas pessoais e o Microsoft Entra ID não podem utilizar declarações opcionais. No entanto, os aplicativos registrados apenas para o Microsoft Entra ID usando o ponto de extremidade v2.0 podem obter as declarações opcionais solicitadas no manifesto. Para obter mais informações, consulte Declarações opcionais.

Exemplo:

    "optionalClaims": null,

identifierAtributo Uris

Chave Tipo de Valor
identificadoUris Matriz de cadeia de caracteres

URIs definidos pelo usuário que identificam exclusivamente um aplicativo Web dentro de seu locatário do Microsoft Entra ou domínio verificado de propriedade do cliente. Quando um aplicativo é usado como um aplicativo de recurso, o valor identifierUri é usado para identificar e acessar exclusivamente o recurso.

Os seguintes formatos de URI de ID de aplicativo baseados em esquema API e HTTP são suportados. Substitua os valores de espaço reservado conforme descrito na lista a seguir à tabela.

ID do aplicativo suportado
Formatos de URI
Exemplo de URIs de ID de aplicativo
api://< appId> api://fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed
api://< tenantId>/<appId> api://a8573488-ff46-450a-b09a-6eca0c6a02dc/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed
api://< tenantId>/<string> api://a8573488-ff46-450a-b09a-6eca0c6a02dc/api
api://< string>/<appId> api://productapi/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed
https://< tenantInitialDomain.onmicrosoft.com/>< string> https://contoso.onmicrosoft.com/productsapi
https://< verifiedCustomDomain>/<string> https://contoso.com/productsapi
https://< string>.<verificadoCustomDomain> https://product.contoso.com
https://< string>.<verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
  • <appId> - A propriedade application identifier (appId) do objeto do aplicativo.
  • <string> - O valor da cadeia de caracteres para o host ou o segmento do caminho da api.
  • <tenantId> - Um GUID gerado pelo Azure para representar o locatário no Azure.
  • <tenantInitialDomain> - <tenantInitialDomain.onmicrosoft.com>, onde< tenantInitialDomain> é o nome de domínio inicial que o criador do locatário especificou na criação do locatário.
  • <verifiedCustomDomain> - Um domínio personalizado verificado configurado para seu locatário do Microsoft Entra.

Nota

Se você usar o esquema api:// , adicionará um valor de cadeia de caracteres diretamente após o "api://". Por exemplo, api://< string>. Esse valor de cadeia de caracteres pode ser um GUID ou uma cadeia de caracteres arbitrária. Se você adicionar um valor GUID, ele deverá corresponder à ID do aplicativo ou à ID do locatário. O valor do URI da ID do aplicativo deve ser exclusivo para seu locatário. Se você adicionar api://< tenantId> como o URI de ID do aplicativo, ninguém mais poderá usar esse URI em nenhum outro aplicativo. A recomendação é usar api://< appId>, em vez disso, ou o esquema HTTP.

Importante

O valor de URI do ID do aplicativo não deve terminar com um caractere de barra "/".

Exemplo:

    "identifierUris": "https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444",

atributo informationalUrls

Chave Tipo de Valor
informationalUrls String

Especifica os links para os termos de serviço e a declaração de privacidade do aplicativo. Os termos de serviço e a declaração de privacidade são apresentados aos usuários através da experiência de consentimento do usuário. Para obter mais informações, consulte Como adicionar termos de serviço e declaração de privacidade para aplicativos registrados do Microsoft Entra.

Exemplo:

    "informationalUrls": {
        "termsOfService": "https://MyRegisteredApp/termsofservice",
        "support": "https://MyRegisteredApp/support",
        "privacy": "https://MyRegisteredApp/privacystatement",
        "marketing": "https://MyRegisteredApp/marketing"
    },

atributo keyCredentials

Chave Tipo de Valor
keyCredenciais Coleção

Contém referências a credenciais atribuídas a aplicativos, segredos compartilhados baseados em cadeia de caracteres e certificados X.509. Essas credenciais são usadas ao solicitar tokens de acesso (quando o aplicativo está agindo como um cliente e não como um recurso).

Exemplo:

    "keyCredentials": [
        {
           "customKeyIdentifier":null,
           "endDateTime":"2018-09-13T00:00:00Z",
           "keyId":"<guid>",
           "startDateTime":"2017-09-12T00:00:00Z",
           "type":"AsymmetricX509Cert",
           "usage":"Verify",
           "value":null
        }
    ],

atributo knownClientApplications

Chave Tipo de Valor
knownClientApplications Matriz de cadeia de caracteres

Usado para agregar consentimento se você tiver uma solução que contenha duas partes: um aplicativo cliente e um aplicativo de API da Web personalizado. Se você inserir o appID do aplicativo cliente nesse valor, o usuário só terá que consentir uma vez para o aplicativo cliente. O Microsoft Entra ID saberá que consentir com o cliente significa consentir implicitamente com a API da Web. Ele provisiona automaticamente entidades de serviço para o cliente e a API da Web ao mesmo tempo. O cliente e o aplicativo de API da Web devem ser registrados no mesmo locatário.

Exemplo:

    "knownClientApplications": ["00001111-aaaa-2222-bbbb-3333cccc4444"],

atributo logoUrl

Chave Tipo de Valor
logoUrl String

Valor somente leitura que aponta para o URL da CDN para o logotipo que foi carregado.

Exemplo:

    "logoUrl": "https://MyRegisteredAppLogo",

atributo logoutUrl

Chave Tipo de Valor
logoutUrl String

O URL para terminar sessão na aplicação.

Exemplo:

    "logoutUrl": "https://MyRegisteredAppLogout",

atributo name

Chave Tipo de Valor
nome Cadeia (de carateres)

O nome para exibição do aplicativo.

Exemplo:

    "name": "MyRegisteredApp",

atributo oauth2AllowImplicitFlow

Chave Tipo de Valor
oauth2AllowImplicitFlow Boolean

Especifica se este aplicativo Web pode solicitar tokens de acesso de fluxo implícito OAuth2.0. O padrão é false. Esse sinalizador é usado para aplicativos baseados em navegador, como aplicativos JavaScript de página única. Para saber mais, entre OAuth 2.0 implicit grant flow no sumário e veja os tópicos sobre fluxo implícito.

Exemplo:

    "oauth2AllowImplicitFlow": false,

atributo oauth2AllowIdTokenImplicitFlow

Chave Tipo de Valor
oauth2AllowIdTokenImplicitFlow Boolean

Especifica se esse aplicativo Web pode solicitar tokens de ID de fluxo implícito OAuth2.0. O padrão é false. Esse sinalizador é usado para aplicativos baseados em navegador, como aplicativos JavaScript de página única.

Exemplo:

    "oauth2AllowIdTokenImplicitFlow": false,

atributo oauth2Permissions

Chave Tipo de Valor
oauth2Permissões Coleção

Especifica a coleção de escopos de permissão OAuth 2.0 que o aplicativo de API Web (recurso) expõe aos aplicativos cliente. Esses escopos de permissão podem ser concedidos a aplicativos cliente durante o consentimento.

Exemplo:

    "oauth2Permissions": [
       {
          "adminConsentDescription": "Allow the app to access resources on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access resource1",
          "id": "<guid>",
          "isEnabled": true,
          "type": "User",
          "userConsentDescription": "Allow the app to access resource1 on your behalf.",
          "userConsentDisplayName": "Access resources",
          "value": "user_impersonation"
        }
    ],

atributo oauth2RequiredPostResponse

Chave Tipo de Valor
oauth2RequiredPostResponse Boolean

Especifica se, como parte das solicitações de token OAuth 2.0, o Microsoft Entra ID permitirá solicitações POST, em vez de solicitações GET. O padrão é false, que especifica que apenas solicitações GET são permitidas.

Exemplo:

    "oauth2RequirePostResponse": false,

atributo parentalControlSettings

Chave Tipo de Valor
parentalControlSettings String
  • countriesBlockedForMinors Especifica os países/regiões em que a aplicação está bloqueada para menores.
  • legalAgeGroupRule Especifica a regra de faixa etária legal que se aplica aos usuários do aplicativo. Pode ser definido como Allow, , , RequireConsentForMinorsRequireConsentForKids, ou BlockMinorsRequireConsentForPrivacyServices.

Exemplo:

    "parentalControlSettings": {
        "countriesBlockedForMinors": [],
        "legalAgeGroupRule": "Allow"
    },

atributo passwordCredentials

Chave Tipo de Valor
passwordCredenciais Coleção

Consulte a descrição do keyCredentials imóvel.

Exemplo:

    "passwordCredentials": [
      {
        "customKeyIdentifier": null,
        "displayName": "Generated by App Service",
        "endDateTime": "2022-10-19T17:59:59.6521653Z",
        "hint": "Nsn",
        "keyId": "<guid>",
        "secretText": null,        
        "startDateTime":"2022-10-19T17:59:59.6521653Z"
      }
    ],

atributo preAuthorizedApplications

Chave Tipo de Valor
Aplicações pré-autorizadas Coleção

Lista aplicativos e permissões solicitadas para consentimento implícito. Requer um administrador para fornecer consentimento para o aplicativo. preAuthorizedApplications não exigem que o usuário consinta com as permissões solicitadas. As permissões listadas em PreAuthorizedApplications não exigem o consentimento do usuário. No entanto, quaisquer permissões adicionais solicitadas não listadas em preAuthorizedApplications requerem o consentimento do usuário.

Exemplo:

    "preAuthorizedApplications": [
       {
          "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "permissionIds": [
             "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
            ]
        }
    ],

atributo publisherDomain

Chave Tipo de Valor
publisherDomain String

O domínio do editor verificado para o aplicativo. Só de Leitura.

Exemplo:

    "publisherDomain": "{tenant}.onmicrosoft.com",

atributo replyUrlsWithType

Chave Tipo de Valor
replyUrlsWithType Coleção

Essa propriedade de vários valores contém a lista de valores de redirect_uri registrados que o Microsoft Entra ID aceitará como destinos ao retornar tokens. Cada valor de URI deve conter um valor de tipo de aplicativo associado. Os valores de tipo suportados são:

  • Web
  • InstalledClient
  • Spa

Para saber mais, consulte restrições e limitações replyUrl.

Exemplo:

    "replyUrlsWithType": [
       {
          "url": "https://localhost:4400/services/office365/redirectTarget.html",
          "type": "InstalledClient"
       }
    ],

atributo requiredResourceAccess

Chave Tipo de Valor
requiredResourceAccess Coleção

Com o consentimento dinâmico, requiredResourceAccess impulsiona a experiência de consentimento do administrador e a experiência de consentimento do usuário para usuários que estão usando o consentimento estático. No entanto, esse parâmetro não orienta a experiência de consentimento do usuário para o caso geral.

  • resourceAppId é o identificador exclusivo do recurso ao qual o aplicativo requer acesso. Esse valor deve ser igual ao appId declarado no aplicativo de recurso de destino.
  • resourceAccess é uma matriz que lista os escopos de permissão OAuth2.0 e as funções do aplicativo que o aplicativo requer do recurso especificado. Contém os id valores e type dos recursos especificados.

Exemplo:

    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
                    "type": "Scope"
                }
            ]
        }
    ],

atributo samlMetadataUrl

Chave Tipo de Valor
samlMetadataUrl String

A URL para os metadados SAML do aplicativo.

Exemplo:

    "samlMetadataUrl": "https://MyRegisteredAppSAMLMetadata",

atributo signInUrl

Chave Tipo de Valor
signInUrl String

Especifica o URL para a página inicial do aplicativo.

Exemplo:

    "signInUrl": "https://MyRegisteredApp",

atributo signInAudience

Chave Tipo de Valor
signInAudience String

Especifica quais contas da Microsoft são suportadas para o aplicativo atual. Os valores suportados são:

  • AzureADMyOrg - Usuários com uma conta corporativa ou escolar da Microsoft no locatário do Microsoft Entra da minha organização (por exemplo, locatário único)
  • AzureADMultipleOrgs - Usuários com uma conta corporativa ou escolar da Microsoft em qualquer locatário do Microsoft Entra de qualquer organização (por exemplo, multilocatário)
  • AzureADandPersonalMicrosoftAccount - Usuários com uma conta pessoal da Microsoft ou uma conta corporativa ou de estudante no locatário do Microsoft Entra de qualquer organização
  • PersonalMicrosoftAccount - Contas pessoais que são usadas para entrar em serviços como Xbox e Skype.

Exemplo:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

atributo tags

Chave Tipo de Valor
etiquetas Matriz de cadeia de caracteres

Cadeias de caracteres personalizadas que podem ser usadas para categorizar e identificar o aplicativo.

Exemplo:

    "tags": [
       "ProductionApp"
    ],

Problemas comuns

Limites de manifesto

Um manifesto de aplicativo tem vários atributos que são chamados de coleções; por exemplo, appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess e oauth2Permissions. No manifesto de candidatura completo para qualquer pedido, o número total de entradas em todas as coleções combinadas foi limitado a 1200. Se você especificar anteriormente 100 URIs de redirecionamento no manifesto do aplicativo, restará apenas 1100 entradas restantes para usar em todas as outras coleções combinadas que compõem o manifesto.

Nota

No caso de tentar adicionar mais de 1200 entradas no manifesto da aplicação, poderá ver um erro "Falha ao atualizar a aplicação xxxxxx. Detalhes do erro: O tamanho do manifesto excedeu seu limite. Por favor, reduza o número de valores e tente novamente o seu pedido."

Atributos não suportados

O manifesto do aplicativo representa o esquema do modelo de aplicativo subjacente no Microsoft Entra ID. À medida que o esquema subjacente evolui, o editor de manifesto será atualizado para refletir o novo esquema de tempos em tempos. Como resultado, você pode notar novos atributos aparecendo no manifesto do aplicativo. Em raras ocasiões, você pode notar uma alteração sintática ou semântica nos atributos existentes ou pode achar que um atributo que existia anteriormente não é mais suportado. Por exemplo, você verá novos atributos nos registros do aplicativo, que são conhecidos com um nome diferente na experiência Registros do aplicativo (Legado).

Registos de aplicações (Legado) Registos de aplicações
availableToOtherTenants signInAudience
displayName name
errorUrl -
homepage signInUrl
objectId Id
publicClient allowPublicClient
replyUrls replyUrlsWithType

Para obter descrições para esses atributos, consulte a seção de referência de manifesto.

Quando tenta carregar um manifesto transferido anteriormente, poderá ver um dos seguintes erros. Este erro é provável porque o editor de manifesto agora suporta uma versão mais recente do esquema, que não corresponde com a que você está tentando carregar.

  • "Falha ao atualizar o aplicativo xxxxxx. Detalhes do erro: Identificador de objeto inválido 'undefined'. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhes do erro: Um ou mais valores de propriedade especificados são inválidos. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhes do erro: Não é permitido definir availableToOtherTenants nesta versão da api para atualização. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhes do erro: Atualizações para a propriedade 'replyUrls' não são permitidas para este aplicativo. Use a propriedade 'replyUrlsWithType' em vez disso. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhes do erro: Um valor sem um nome de tipo foi encontrado e nenhum tipo esperado está disponível. Quando o modelo é especificado, cada valor na carga útil deve ter um tipo que pode ser especificado na carga útil, explicitamente pelo chamador ou implicitamente inferido a partir do valor pai. []"

Quando você vir um desses erros, recomendamos as seguintes ações:

  1. Edite os atributos individualmente no editor de manifesto em vez de carregar um manifesto baixado anteriormente. Use a tabela de referência de manifesto para entender a sintaxe e a semântica de atributos antigos e novos para que você possa editar com êxito os atributos em que está interessado.
  2. Se o seu fluxo de trabalho exigir que você salve os manifestos em seu repositório de origem para uso posterior, sugerimos rebasear os manifestos salvos em seu repositório com o que você vê na experiência de registros de aplicativos.

Próximos passos

Use a seção de comentários a seguir para fornecer comentários que ajudam a refinar e moldar nosso conteúdo.