Manifesto do aplicativo Microsoft Entra

  • Artigo

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 Aplicativo e seu esquema, confira a Documentação da entidade do Aplicativo da API do Graph.

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 PowerShell do Microsoft Graph. No entanto, existem alguns cenários em que você precisará editar o manifesto do aplicativo para configurar um atributo de aplicativo. Esses cenários incluem:

  • Se você registrou o aplicativo como multilocatário do Microsoft Entra e contas pessoais da Microsoft, não é possível alterar as contas da Microsoft compatíveis na interface do usuário. Em vez disso, você deve usar o editor de manifesto do aplicativo para alterar o tipo de conta suportado.
  • Para definir permissões e funções que seu aplicativo suporta, você deve modificar o manifesto do aplicativo.

Configurar o manifesto do aplicativo

Para configurar o manifesto do aplicativo:

  1. Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
  2. Navegue até Identidade>Aplicativos>Registros do aplicativo.
  3. Selecione o aplicativo que você deseja configurar.
  4. Na página Visão Geral do aplicativo, selecione a seçã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 usar Upload para reaplicá-lo ao seu aplicativo.

Referência do manifesto

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

ID do atributo

Chave Tipo de valor
id String

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

Exemplo:

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

atributo acceptMappedClaims

Chave Tipo de valor
acceptMappedClaims Booleano anulável

Conforme documentado no apiApplication tipo de recurso , isso permite que um aplicativo use o 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 com autorização 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 das políticas de mapeamento de declarações criadas por atores mal-intencionados.

Aviso

Não defina a propriedade acceptMappedClaims como true para aplicativos multilocatário, pois isso poderá 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 do cliente usado para solicitar o token de acesso.

O ponto de extremidade usado, v1.0 ou v2.0, é escolhido pelo cliente e só afeta a versão do id_tokens. Os recursos precisam configurar explicitamente accesstokenAcceptedVersion para indicar o formato do token de acesso com suporte.

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

Se signInAudience é AzureADandPersonalMicrosoftAccount, o valor precisa ser 2.

Exemplo:

    "accessTokenAcceptedVersion": 2,

atributo addIns

Chave Tipo de valor
addIns Coleção

Define o comportamento personalizado que um serviço de consumo pode usar para chamar um aplicativo em contextos específicos. Por exemplo, os aplicativos que podem renderizar fluxos de arquivos podem definir a propriedade addIns para a funcionalidade "FileHandler" dessa propriedade. 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 Microsoft Entra ID infere o tipo de aplicativo do replyUrlsWithType por padrão. Há determinados cenários em que o Microsoft Entra ID não pode determinar o tipo de aplicativo cliente. Por exemplo, um cenário desse tipo é o fluxo ROPC em que a solicitação HTTP ocorre 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 um aplicativo web.

Exemplo:

    "allowPublicClient": false,

atributo appId

Chave Tipo de valor
appId String

Especifica o identificador exclusivo do aplicativo que é atribuído a um aplicativo pelo Microsoft Entra ID.

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 ver exemplos e mais informações, confira Adicionar funções de aplicativo ao 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

Incompatível.

atributo groupMembershipClaims

Chave Tipo de valor
GroupMembershipClaims String

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

  • "None"
  • "SecurityGroup" (para grupos de segurança e funções do Microsoft Entra)
  • "ApplicationGroup" (essa opção inclui apenas os grupos atribuídos ao aplicativo)
  • "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 do diretório do Microsoft Entra dos quais o usuário conectado é membro).

Exemplo:

    "groupMembershipClaims": "SecurityGroup",

atributo optionalClaims

Chave Tipo de valor
optionalClaims String

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

Os aplicativos que oferecem suporte a contas pessoais e ao Microsoft Entra ID não podem usar 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, confira Declarações opcionais.

Exemplo:

    "optionalClaims": null,

atributo identifierUris

Chave Tipo de valor
identifierUris Matriz de cadeia de caracteres

URIs definidos pelo usuário que identificam com exclusividade um aplicativo web no respectivo locatário do Microsoft Entra ou um domínio pertencente a um cliente. Quando um aplicativo é usado como um aplicativo de recurso, o valor de identifierUri é usado para identificar e acessar exclusivamente o recurso.

Há suporte para os seguintes formatos de URI de ID de aplicativo baseados em esquema HTTP e API. Substitua os valores nos espaços reservados conforme descrito na lista após a tabela.

ID do aplicativo com suporte
Formatos de URI		 URIs de ID do aplicativo de exemplo
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>.<verifiedCustomDomain> https://product.contoso.com
https://<string>.<verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
  • <appId> - A propriedade do identificador de aplicativo (appId) do objeto de aplicativo.
  • <string> - O valor da cadeia de caracteres do host ou do segmento de linha da AP.
  • <tenantId> - Um GUID gerado pelo Azure para representar o locatário no Azure.
  • <tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com, em que <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 que foi configurado para seu locatário do Microsoft Entra.

Observação

Ao usar o esquema api://, adicione um valor de cadeia de caracteres diretamente após "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 de 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 da ID do aplicativo, ninguém mais poderá usar esse URI em nenhum outro aplicativo. Recomenda-se usar api://<appId> ou o esquema HTTP como alternativa.

Importante

O valor do URI da 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 política de privacidade do aplicativo. Os termos de serviço e a declaração de privacidade são revelados aos usuários por meio da experiência de consentimento do usuário. Para obter mais informações, confira Como adicionar termos de serviço e política de privacidade para aplicativos do Microsoft Entra registrados.

Exemplo:

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

atributo keyCredentials

Chave Tipo de valor
keyCredentials Coleção

Contém referências a credenciais, segredos compartilhados com base em cadeia de caracteres e certificados X.509 atribuídos ao aplicativo. 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 agrupamento de consentimento no caso de uma solução que contenha duas partes: um aplicativo cliente e um aplicativo de API Web personalizado. Se você inserir a appID do aplicativo cliente nesse valor, o usuário precisará consentir somente uma vez no aplicativo cliente. O Microsoft Entra ID saberá que o consentimento para o cliente significa implicitamente consentir à API Web. Provisiona automaticamente as entidades de serviço tanto para o cliente quanto para a API web ao mesmo tempo. O cliente e o aplicativo de API Web precisam ser registrados no mesmo locatário.

Exemplo:

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

atributo logoUrl

Chave Tipo de valor
logoUrl String

Leia apenas o valor que aponta para a URL da CDN para o logotipo que foi carregado.

Exemplo:

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

atributo logoutUrl

Chave Tipo de valor
logoutUrl String

A URL para fazer logoff do aplicativo.

Exemplo:

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

atributo name

Chave Tipo de valor
name String

O nome de 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ícitos OAuth 2.0. O padrão é false. Esse sinalizador é usado para aplicativos baseados em navegador, como os aplicativos de página única JavaScript. Para saber mais, digite OAuth 2.0 implicit grant flow no sumário e consulte os tópicos sobre fluxo implícito.

Exemplo:

    "oauth2AllowImplicitFlow": false,

atributo oauth2AllowIdTokenImplicitFlow

Chave Tipo de valor
oauth2AllowIdTokenImplicitFlow Boolean

Especifica se este aplicativo Web pode solicitar os tokens de ID de fluxo implícitos OAuth 2.0. O padrão é false. Esse sinalizador é usado para aplicativos baseados em navegador, como os aplicativos de página única JavaScript.

Exemplo:

    "oauth2AllowIdTokenImplicitFlow": false,

atributo oauth2Permissions

Chave Tipo de valor
oauth2Permissions Coleção

Especifica a coleção de escopos de permissão do OAuth 2.0 que o aplicativo de API Web (recurso) expõe aos aplicativos clientes. Esses escopos de permissões podem ser concedidos a aplicativos clientes 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, o que especifica que somente as 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 o aplicativo está bloqueado para menores.
  • legalAgeGroupRule especifica a regra de grupo de faixa etária que se aplica a usuários do aplicativo. Pode ser definido como Allow, RequireConsentForPrivacyServices, RequireConsentForMinors, RequireConsentForKids ou BlockMinors.

Exemplo:

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

atributo passwordCredentials

Chave Tipo de valor
passwordCredentials Coleção

Confira a descrição da propriedade keyCredentials.

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
preAuthorizedApplications Coleção

Lista os aplicativos e as permissões solicitadas para consentimento implícito. Requer que um administrador forneça consentimento ao 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 solicitadas adicionais não listadas no preAuthorizedApplications exigem 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 fornecedor verificado para o aplicativo. Somente 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 redirect_uri registrados que o Microsoft Entra ID aceitará como destinos quando retornar tokens. Cada valor de URI deve conter um valor de tipo de aplicativo associado. Os valores de tipo compatíveis são:

  • Web
  • InstalledClient
  • Spa

Para saber mais, confira restrições e limitações do 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, o requiredResourceAccess gera 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 gera 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 à appId declarada no aplicativo do recurso de destino.
  • resourceAccess é uma matriz que lista os escopos de permissão do OAuth2.0 e as funções de aplicativo que o aplicativo exige do recurso especificado. Contém os valores id 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 dos metadados SAML do aplicativo.

Exemplo:

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

atributo signInUrl

Chave Tipo de valor
signInUrl String

Especifica a URL da home page 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 com suporte são:

  • AzureADMyOrg – usuários com uma conta corporativa ou de estudante 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 de estudante da Microsoft no locatário do Microsoft Entra de qualquer organização (por exemplo, multilocatário)
  • AzureADandPersonalMicrosoftAccount – usuários com uma conta Microsoft pessoal ou uma conta corporativa ou de estudante no locatário do Microsoft Entra de qualquer organização
  • PersonalMicrosoftAccount – Contas pessoais usadas para entrar em serviços como Xbox e Skype.

Exemplo:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

atributo tags

Chave Tipo de valor
marcas 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 completo do aplicativo para qualquer aplicativo, o número total de entradas em todas as coleções combinadas tem sido limitado a 1.200. Se você especificar antecipadamente 100 URIs de redirecionamento no manifesto do aplicativo, restarão a você apenas 1.100 entradas para usar em todas as outras coleções combinadas que compõem o manifesto.

Observação

Caso você tente adicionar mais de 1.200 entradas no manifesto do aplicativo, poderá ver o erro "Falha ao atualizar o aplicativo xxxxxx. Detalhes do erro: O tamanho do manifesto excedeu o limite. Reduza o número de valores e repita a solicitação".

Atributos incompatíveis

O manifesto do aplicativo representa o esquema do modelo de aplicativo subjacente no Microsoft Entra ID. Conforme 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 encontrar um atributo que existia anteriormente mas não é mais compatível. Por exemplo, você verá novos atributos nos Registros de aplicativo que são conhecidos com um nome diferente na experiência Registros de aplicativo (Herdados).

Registros de aplicativo (Herdados) Registros de aplicativo
availableToOtherTenants signInAudience
displayName name
errorUrl -
homepage signInUrl
objectId Id
publicClient allowPublicClient
replyUrls replyUrlsWithType

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

Ao tentar carregar um manifesto baixado anteriormente, você poderá ver um dos erros a seguir. Esse erro é provável porque o editor de manifesto agora dá suporte a uma versão mais recente do esquema, que não corresponde àquela que você está tentando carregar.

  • "Falha ao atualizar o aplicativo xxxxxx. Detalhe do erro: Identificador de objeto inválido 'indefinido'. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhe do erro: Um ou mais valores de propriedade especificados são inválidos. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhe do erro: Não é permitido definir availableToOtherTenants nesta versão de API para atualização. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhe do erro: Atualizações à propriedade 'replyUrls' não são permitidas para este aplicativo. Use a propriedade 'replyUrlsWithType' em seu lugar. []."
  • "Falha ao atualizar o aplicativo xxxxxx. Detalhe do erro: Um valor sem um nome de tipo foi encontrado e nenhum tipo esperado está disponível. Quando o modelo é especificado, cada valor no conteúdo precisa ter um tipo que pode ser especificado no conteúdo, seja explicitamente pelo chamador ou inferido implicitamente 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 referência de manifesto para entender a sintaxe e a semântica dos atributos novos e antigos, a fim de poder editar com êxito os atributos nos quais você está interessado.
  2. Se o fluxo de trabalho exigir que você salve os manifestos no repositório de origem para uso posterior, sugerimos realocar os manifestos salvos em seu repositório com aquele que você vê na experiência de Registros de aplicativo.

Próximas etapas

Use a seção de comentários a seguir para dar sua opinião e nos ajudar a aprimorar e adaptar nosso conteúdo.