Manifesto do aplicativo Microsoft Entra (formato Azure AD Graph)

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 Microsoft pessoais, não é possível alterar as contas 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 compatível.
• 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 seção Gerenciar do aplicativo, selecione 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.

Exemplo:

    "acceptMappedClaims": true,

atributo requestedAccessTokenVersion

Chave	Tipo de valor
requestedAccessTokenVersion	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 requestedAccessTokenVersion para indicar o formato do token de acesso com suporte.

Os valores possíveis para requestedAccessTokenVersion 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:

    "requestedAccessTokenVersion": 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. Para um aplicativo cliente público, ele não pode ter valor para identifierUris.

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://00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<appId>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<string>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
api://<string>/<appId>	api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444
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.

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 desconectar 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. No entanto, desencorajamos o uso de concessão implícita mesmo em SPAs e recomendamos usar o fluxo de código de autorização com PKCE.

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. No entanto, desencorajamos o uso de concessão implícita mesmo em SPAs e recomendamos usar o fluxo de código de autorização com PKCE.

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 apenas 1.100 entradas para você usar em todas as outras coleções combinadas que compõem o manifesto.

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 é 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 que 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

• Para obter mais informações sobre a relação entre os objetos aplicativo e entidade de serviço do aplicativo, confira Objetos de aplicativo e de entidade de serviço no Microsoft Entra ID.
• Confira o Glossário de desenvolvedor da plataforma de identidade da Microsoft para obter definições de alguns conceitos principais do desenvolvedor da plataforma de identidade da Microsoft.

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