Manifiesto de la aplicación de Microsoft Entra

El manifiesto de la aplicación contiene una definición de todos los atributos de un objeto de la aplicación en la plataforma de identidad de Microsoft. También sirve como mecanismo para actualizar el objeto de la aplicación. Para más información sobre la entidad Application y su esquema, consulte la documentación sobre la entidad Application de Graph API.

Puede configurar los atributos de una aplicación en centro de administración de Microsoft Entra o mediante programación con Microsoft Graph API o el SDK de PowerShell de Microsoft Graph. Sin embargo, hay algunos escenarios en los que es necesario editar el manifiesto de aplicación para configurar el atributo de una aplicación. Entre los escenarios se incluyen los siguientes:

  • Si registró la aplicación como una cuenta multiinquilino de Microsoft Entra y una cuenta de Microsoft personal, no podrá cambiar las cuentas de Microsoft compatibles en la interfaz de usuario. En su lugar, tendrá que utilizar el editor de manifiesto de la aplicación para cambiar los tipos de cuenta compatibles.
  • Para definir permisos y roles compatibles con la aplicación, debe modificar el manifiesto de la aplicación.

Configuración del manifiesto de la aplicación

Para configurar el manifiesto de la aplicación:

  1. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Desarrollador de aplicaciones.
  2. Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.
  3. Seleccione la aplicación que desee configurar.
  4. Desde la página Introducción de la aplicación, seleccione la sección Manifiesto. Se abrirá un editor de manifiestos basado en web que le permitirá editar el manifiesto. Si lo desea, también puede seleccionar Descargar para editar el manifiesto de forma local y usar después Cargar para aplicarlo de nuevo a la aplicación.

Referencia de manifiesto

En esta sección se describen los atributos que se encuentran en el manifiesto de la aplicación.

Atributo id

Clave Tipo de valor
id String

El identificador único de la aplicación en el directorio. Este identificador no es el que se usa para identificar la aplicación en cualquier transacción del protocolo. Úselo para hacer referencia al objeto en las consultas de directorio.

Ejemplo:

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

Atributo acceptMappedClaims

Clave Tipo de valor
acceptMappedClaims Booleano que admite un valor NULL

Como se documenta en el tipo apiApplication de recurso, esto permite que una aplicación use la asignación de notificaciones sin especificar una clave de firma personalizada. Las aplicaciones que reciben tokens se basan en el hecho de que los valores de notificación se emiten de forma autoritaria por parte de Microsoft Entra ID y no se pueden alterar. Sin embargo, al modificar el contenido del token a través de las directivas de asignación de notificaciones, es posible que estas suposiciones ya no sean correctas. Las aplicaciones deben reconocer explícitamente que el creador de la directiva de asignación de notificaciones ha modificado los tokens para protegerse de las directivas de asignación de notificaciones creadas por actores malintencionados.

Advertencia

No establezca la propiedad acceptMappedClaims en true para las aplicaciones multiinquilino, ya que puede permitir que actores malintencionados creen directivas de asignación de notificaciones para la aplicación.

Ejemplo:

    "acceptMappedClaims": true,

Atributo accessTokenAcceptedVersion

Clave Tipo de valor
accessTokenAcceptedVersion Int32 que acepta valores null

Especifica la versión del token de acceso que espera el recurso. Este parámetro cambia la versión y el formato de JWT generado independientemente del punto de conexión o cliente utilizado para solicitar el token de acceso.

El punto de conexión usado, v1.0 o v2.0, lo elige el cliente y solo afecta a la versión de id_tokens. Los recursos deben configurar explícitamente accesstokenAcceptedVersion para indicar el formato del token de acceso admitido.

Los valores posibles de accesstokenAcceptedVersion son 1, 2 o un valor null. Si el valor es NULL, el valor predeterminado es 1, lo que corresponde al punto de conexión v1.0.

Si signInAudience es AzureADandPersonalMicrosoftAccount, el valor debe ser 2.

Ejemplo:

    "accessTokenAcceptedVersion": 2,

Atributo addIns

Clave Tipo de valor
addIns Colección

Define el comportamiento personalizado que puede usar un servicio de consumo para llamar a una aplicación en contextos concretos. Por ejemplo, las aplicaciones que pueden representar secuencias de archivos pueden establecer la propiedad addIns para su funcionalidad "FileHandler". Este parámetro permite a los servicios como Microsoft 365 llamar a la aplicación en el contexto de un documento en el que está trabajando el usuario.

Ejemplo:

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

Atributo allowPublicClient

Clave Tipo de valor
allowPublicClient Boolean

Especifica el tipo de aplicación de reserva. Microsoft Entra ID deduce el tipo de aplicación a partir de replyUrlsWithType, de forma predeterminada. Hay algunos escenarios en los que Microsoft Entra ID no puede determinar el tipo de aplicación cliente. Por ejemplo, uno de estos escenarios es el flujo ROPC en el que la solicitud HTTP se realiza sin redireccionamiento de direcciones URL). En esos casos, Microsoft Entra ID interpreta el tipo de aplicación en función del valor de esta propiedad. Si este valor se establece en true, el tipo de aplicación de reserva se establece como cliente público, como una aplicación instalada que se ejecuta en un dispositivo móvil. El valor predeterminado es false, lo que significa que el tipo de aplicación de reserva es cliente confidencial, como la aplicación web.

Ejemplo:

    "allowPublicClient": false,

Atributo appId

Clave Tipo de valor
appId String

Especifica el identificador único de la aplicación que Microsoft Entra ID asigna a una aplicación.

Ejemplo:

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

Atributo appRoles

Clave Tipo de valor
appRoles Colección

Especifica la colección de roles que una aplicación puede declarar. Dichos roles se pueden asignar a usuarios, grupos o entidades de servicio. Para ver más ejemplos e información, consulte el artículo Agregar roles de aplicación en la aplicación y recibirlos en el token.

Ejemplo:

    "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

Clave Tipo de valor
errorUrl String

No compatible.

Atributo groupMembershipClaims

Clave Tipo de valor
groupMembershipClaims String

Configura la notificación groups emitida en un token de acceso OAuth 2.0 o de usuario que la aplicación espera. Para establecer este atributo, use uno de los siguientes valores de cadena válidos:

  • "None"
  • "SecurityGroup"(para grupos de seguridad y roles de Microsoft Entra)
  • "ApplicationGroup" (esta opción solo incluye los grupos asignados a la aplicación)
  • "DirectoryRole"(obtiene los roles de directorio de Microsoft Entra de los que el usuario es miembro)
  • "All" (se obtendrán todos los grupos de seguridad, grupos de distribución y roles de directorio de Microsoft Entra a los que pertenezca el usuario que inició sesión).

Ejemplo:

    "groupMembershipClaims": "SecurityGroup",

Atributo optionalClaims

Clave Tipo de valor
optionalClaims String

Las notificaciones opcionales que el servicio de token de seguridad devuelve en el token para esta aplicación específica.

Aplicaciones que admiten tanto cuentas personales como Microsoft Entra ID no pueden usar notificaciones opcionales. Sin embargo, las aplicaciones registradas solo para Microsoft Entra ID mediante el punto de conexión v2.0 pueden obtener las notificaciones opcionales que han solicitado en el manifiesto. Para obtener más información, consulte las notificaciones opcionales.

Ejemplo:

    "optionalClaims": null,

Atributo identifierUris

Clave Tipo de valor
identifierUris Matriz de cadenas

Identificadores URI definidos por el usuario que identifican de forma única una aplicación web dentro de su inquilino de Microsoft Entra o un dominio comprobado de propiedad del cliente. Cuando se usa una aplicación como aplicación de recursos, el valor de identifierUri se usa para acceder e identificar de forma única al recurso.

Se admiten los siguientes formatos de URI de identificador de aplicación basados en esquemas HTTP y API. Reemplace los valores de marcador de posición como se describe en la lista que sigue a la tabla.

Identificadores de aplicación admitidos
Formatos de URI
Ejemplos de URI de id. de aplicación
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>: propiedad de identificador de aplicación (appId) del objeto de aplicación.
  • <string>: valor de cadena para el host o el segmento de trazado de API.
  • <tenantId>: GUID generado por Azure para representar el inquilino dentro de Azure.
  • <tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com, donde <tenantInitialDomain> es el nombre de dominio inicial que el creador del inquilino especificó durante la creación del inquilino.
  • <verifiedCustomDomain>: un dominio personalizado comprobado configurado para el inquilino de Microsoft Entra.

Nota:

Si usa el esquema api://, se agrega un valor de cadena directamente después de "api://". Por ejemplo, api://<string>. Ese valor de cadena puede ser un GUID o una cadena arbitraria. Si agrega un valor GUID, debe coincidir con el identificador de la aplicación o con el identificador de inquilino. El valor de URI del identificador de aplicación debe ser único para el inquilino. Si agrega api://<tenantId> como URI de identificador de aplicación, nadie más podrá usar ese URI en ninguna otra aplicación. La recomendación es usar api://<appId>, en su lugar, o el esquema HTTP.

Importante

El valor de URI del id. de aplicación no debe terminar con un carácter de barra diagonal "/".

Ejemplo:

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

Atributo informationalUrls

Clave Tipo de valor
informationalUrls String

Especifica los vínculos a los términos del servicio y la 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 más información, consulte Condiciones del servicio y declaración de privacidad de las aplicaciones registradas de Microsoft Entra.

Ejemplo:

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

Atributo keyCredentials

Clave Tipo de valor
keyCredentials Colección

Contiene referencias a credenciales asignadas por la aplicación, secretos compartidos basados en cadena y certificados X.509. Estas credenciales se usan cuando se solicitan tokens de acceso (cuando la aplicación actúa como cliente, en lugar de como recurso).

Ejemplo:

    "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

Clave Tipo de valor
knownClientApplications Matriz de cadenas

Se usa para el consentimiento de unión si dispone de una solución que contenga dos partes, una aplicación cliente y una aplicación de API web personalizada. Si especifica el valor de appID de la aplicación cliente en este valor, el usuario solo tendrá que dar su consentimiento una vez a la aplicación cliente. Microsoft Entra ID sabrá que el consentimiento al cliente significa consentir implícitamente a la API web. Aprovisiona automáticamente entidades de servicio para el cliente y la API web al mismo tiempo. Tanto el cliente como la aplicación de API web deben estar registrados en el mismo inquilino.

Ejemplo:

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

Atributo logoUrl

Clave Tipo de valor
logoUrl String

Leer el valor solo que apunta a la dirección URL de CDN para el logotipo que se cargó.

Ejemplo:

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

Atributo logoutUrl

Clave Tipo de valor
logoutUrl String

La dirección URL para cerrar la sesión de la aplicación.

Ejemplo:

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

Atributo name

Clave Tipo de valor
name String

El nombre para mostrar de la aplicación.

Ejemplo:

    "name": "MyRegisteredApp",

Atributo oauth2AllowImplicitFlow

Clave Tipo de valor
oauth2AllowImplicitFlow Boolean

Especifica si esta aplicación web puede solicitar tokens de acceso de flujo implícitos de OAuth2.0. El valor predeterminado es false. Esta marca se usa para las aplicaciones basadas en explorador, como las aplicaciones de página única de JavaScript. Para más información, escriba OAuth 2.0 implicit grant flow en la tabla de contenido y vea los temas sobre el flujo implícito.

Ejemplo:

    "oauth2AllowImplicitFlow": false,

Atributo oauth2AllowIdTokenImplicitFlow

Clave Tipo de valor
oauth2AllowIdTokenImplicitFlow Boolean

Especifica si esta aplicación web puede solicitar tokens de identificador de flujo implícitos de OAuth2.0. El valor predeterminado es false. Esta marca se usa para las aplicaciones basadas en explorador, como las aplicaciones de página única de JavaScript.

Ejemplo:

    "oauth2AllowIdTokenImplicitFlow": false,

Atributo oauth2Permissions

Clave Tipo de valor
oauth2Permissions Colección

Especifica la colección de ámbitos de permiso de OAuth 2.0 que la aplicación de API (recurso) web expone a las aplicaciones cliente. Estos ámbitos de permisos pueden concederse a las aplicaciones cliente durante el consentimiento.

Ejemplo:

    "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

Clave Tipo de valor
oauth2RequiredPostResponse Booleano

Especifica si, como parte de las solicitudes de tokens de OAuth 2.0, Microsoft Entra ID permitirá solicitudes POST, frente a las solicitudes GET. El valor predeterminado es false, que especifica que solo se permiten las solicitudes GET.

Ejemplo:

    "oauth2RequirePostResponse": false,

Atributo parentalControlSettings

Clave Tipo de valor
parentalControlSettings String
  • countriesBlockedForMinors especifica los países o regiones en los que la aplicación se bloquea para menores de edad.
  • legalAgeGroupRule especifica la regla de grupo de edad legal que se aplica a los usuarios de la aplicación. Se puede establecer en Allow, RequireConsentForPrivacyServices, RequireConsentForMinors, RequireConsentForKids o BlockMinors.

Ejemplo:

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

Atributo passwordCredentials

Clave Tipo de valor
passwordCredentials Colección

Consulte la descripción de la propiedad keyCredentials.

Ejemplo:

    "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

Clave Tipo de valor
preAuthorizedApplications Colección

Enumera las aplicaciones y los permisos solicitados para el consentimiento implícito. Requiere que un administrador proporcione consentimiento a la aplicación. preAuthorizedApplications no requiere que el usuario dé su consentimiento para los permisos solicitados. Los permisos enumerados en preAuthorizedApplications no requieren el consentimiento del usuario. Sin embargo, los permisos solicitados adicionales que no aparecen en preAuthorizedApplications requieren el consentimiento del usuario.

Ejemplo:

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

Atributo publisherDomain

Clave Tipo de valor
publisherDomain String

El dominio del publicador comprobado para la aplicación. Solo lectura.

Ejemplo:

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

Atributo replyUrlsWithType

Clave Tipo de valor
replyUrlsWithType Collection

Esta propiedad multivalor contiene la lista de valores de redirect_uri registrados que Microsoft Entra ID aceptará como destinos cuando se devuelvan tokens. Cada valor del identificador URI debe contener un valor de tipo de aplicación asociado. Los valores de tipo admitidos son:

  • Web
  • InstalledClient
  • Spa

Para obtener más información, consulte las limitaciones y restricciones de las URL de respuesta.

Ejemplo:

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

Atributo requiredResourceAccess

Clave Tipo de valor
requiredResourceAccess Colección

Con el consentimiento dinámico, requiredResourceAccess controla la experiencia de consentimiento del administrador y la experiencia de consentimiento del usuario para usuarios que usan consentimiento estático. Aunque este parámetro no controla la experiencia de consentimiento del usuario del caso general.

  • resourceAppId es el único identificador del recurso al que la aplicación necesita acceso. Este valor debe ser igual que el valor de appId declarado en la aplicación del recurso de destino.
  • resourceAccess es una matriz que enumera los ámbitos de permiso de OAuth 2.0 y los roles de aplicación que necesita la aplicación del recurso especificado. Contiene los valores id y type de los recursos especificados.

Ejemplo:

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

Atributo samlMetadataUrl

Clave Tipo de valor
samlMetadataUrl String

La dirección URL de los metadatos de SAML de la aplicación.

Ejemplo:

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

Atributo signInUrl

Clave Tipo de valor
signInUrl String

Especifica la dirección URL a la página principal de la aplicación.

Ejemplo:

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

Atributo signInAudience

Clave Tipo de valor
signInAudience String

Especifica qué cuentas de Microsoft se admiten en la aplicación actual. Los valores admitidos son:

  • AzureADMyOrg: usuarios con una cuenta profesional o educativa de Microsoft en el inquilino de Microsoft Entra de la organización (por ejemplo, un inquilino único)
  • AzureADMultipleOrgs: usuarios con una cuenta profesional o educativa de Microsoft en el inquilino de Microsoft Entra de una organización (por ejemplo, un multiinquilino)
  • AzureADandPersonalMicrosoftAccount: usuarios con una cuenta de Microsoft personal o una cuenta profesional o educativa en el inquilino de Microsoft Entra de una organización
  • PersonalMicrosoftAccount: cuentas personales que se usan para iniciar sesión en servicios como Xbox y Skype.

Ejemplo:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

Atributo tags

Clave Tipo de valor
etiquetas Matriz de cadenas

Cadenas personalizadas que pueden utilizarse para clasificar e identificar la aplicación.

Ejemplo:

    "tags": [
       "ProductionApp"
    ],

Problemas comunes

Límites de manifiesto

Un manifiesto de aplicación tiene varios atributos que se conocen como colecciones; por ejemplo, appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess y oauth2Permissions. Dentro del manifiesto de aplicación completa para cualquier aplicación, el número total de entradas de todas las colecciones combinadas se ha limitado a 1200. Si previamente especifica 100 URI de redireccionamiento en el manifiesto de aplicación, solo le quedarán 1100 entradas restantes para usar entre todas las demás colecciones combinadas que componen el manifiesto.

Nota

Si intenta agregar más de 1200 entradas en el manifiesto de aplicación, es posible que aparezca un error "No se pudo actualizar la aplicación xxxxxx. Detalles del error: El tamaño del manifiesto ha excedido su límite. Reduzca el número de valores y vuelva a intentar la solicitud".

Atributos no admitidos

El manifiesto de aplicación representa el esquema del modelo de aplicación subyacente de Microsoft Entra ID. A medida que evoluciona el esquema subyacente, el editor de manifiestos se actualizará para reflejar el nuevo esquema de vez en cuando. Como resultado, es posible que observe nuevos atributos que se muestran en el manifiesto de aplicación. En raras ocasiones, es posible que observe un cambio semántico o sintáctico en los atributos existentes o quizás encontrará un atributo que existía previamente, pero ya no se admite. Por ejemplo, verá los nuevos atributos en los Registros de aplicaciones que se conocen por otro nombre en la experiencia de Registros de aplicaciones (heredados).

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

Para obtener descripciones de estos atributos, consulte la sección de referencia de manifiesto.

Al intentar cargar un manifiesto descargado anteriormente, es posible que vea uno de los siguientes errores. Este error probablemente se deba a que el editor de manifiestos ahora admite una versión más reciente del esquema, que no coincide con el que está intentando cargar.

  • "No se pudo actualizar la aplicación xxxxxx. Detalle del error: Identificador de objeto no válido "undefined". []."
  • "No se pudo actualizar la aplicación xxxxxx. Detalle del error: Uno o más de los valores de propiedad especificados no son válidos. []."
  • "No se pudo actualizar la aplicación xxxxxx. Detalle del error: No se permite establecer availableToOtherTenants en esta versión de API para la actualización. []."
  • "No se pudo actualizar la aplicación xxxxxx. Detalle del error: No se permiten actualizaciones de la propiedad "replyUrls" para esta aplicación. Use la propiedad "replyUrlsWithType" en su lugar. []."
  • "No se pudo actualizar la aplicación xxxxxx. Detalle del error: Se encontró un valor sin nombre de tipo y no ningún tipo esperado disponible. Cuando se especifica el modelo, cada valor de la carga debe tener un tipo que el autor puede especificar en la carga de forma explícita o que se puede inferir de forma implícita a partir del valor primario. []"

Cuando vea uno de estos errores, se recomienda realizar las acciones siguientes:

  1. Edite los atributos de forma individualmente en el editor de manifiestos en lugar de cargar un manifiesto descargado anteriormente. Use la tabla de referencia de manifiesto para comprender la sintaxis y semántica de atributos antiguos y nuevos para que se puedan editar correctamente los atributos que le interesan.
  2. Si el flujo de trabajo requiere guardar los manifiestos en el repositorio de origen para su uso posterior, se recomienda reorganizar los manifiestos guardados en el repositorio con el que ve en la experiencia Registros de aplicaciones.

Pasos siguientes

Use la siguiente sección de comentarios para especificar opiniones que ayuden a afinar y dar forma al contenido.