Compartir a través de

Restricciones en los URI de identificador de las aplicaciones de Microsoft Entra

La propiedad identifierUri, también denominada Application ID URI, de una aplicación de Microsoft Entra es una propiedad que normalmente se configura en aplicaciones de recursos (API). La configuración de esta propiedad de forma segura es fundamental para la seguridad del recurso.

Patrones seguros

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://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
<api:// string>.<verifiedCustomDomainOrInitialDomain>/<string> api://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. Si usa un valor de cadena, debe usar un dominio personalizado comprobado o un dominio inicial del inquilino. La recomendación es usar api://< appId>.

Importante

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

Importante

El valor del URI del identificador de aplicación debe ser único dentro de su entorno.

Aplicación de patrones seguros con directivas

Microsoft ha introducido una configuración de seguridad que protege contra la configuración no segura de los URI de identificadores (también denominados "URI de id. de aplicación") en aplicaciones de Microsoft Entra. Esta configuración de seguridad garantiza que los URI recién agregados en las aplicaciones v1 cumplan los patrones seguros descritos anteriormente.

Comportamiento de la directiva

Cuando esta configuración está habilitada, se aplican estrictamente los patrones seguros. Cuando se habilita, si alguien de su organización intenta agregar un URI de identificador que no cumple los patrones seguros, recibirá un error como:

Failed to add identifier URI {uri}. All newly added URIs must contain a tenant verified domain, tenant ID, or app ID, as per the default tenant policy of your organization. See https://aka.ms/identifier-uri-addition-error for more information on this error.

Las aplicaciones configuradas para usar tokens de identificación Entra v2.0, estableciendo la propiedad api.requestedAccessTokenVersion de la aplicación a 2, están exentas de forma predeterminada. Las aplicaciones que están configuradas para usar el protocolo SAML para el inicio de sesión único, al establecer la propiedad preferredSingleSignOnMode de la entidad de servicio en SAML, también están exentas de forma predeterminada.

Los URI de identificador existentes ya configurados en la aplicación no se verán afectados y todas las aplicaciones seguirán funcionando de la forma normal. Esto solo afectará a las nuevas actualizaciones de las configuraciones de aplicaciones de Microsoft Entra.

Cuando no está habilitado, todavía se pueden usar algunos patrones no seguros. Por ejemplo, se pueden agregar URI del formato api://{string} . Sin embargo, incluso cuando la configuración está deshabilitada, puede que todavía se requiera un dominio verificado o inicial de locatario en algunos escenarios, por ejemplo, al usar el esquema https://.

Activación y gestión de la política

Es posible que Microsoft ya haya habilitado esta directiva en su organización para mejorar su seguridad. Para comprobarlo, ejecute este script.

Incluso si Microsoft habilitó la directiva en su organización, un administrador de inquilinos todavía tiene control total sobre ella. Pueden conceder exenciones a una aplicación específica de Microsoft Entra, a sí mismos, a otro usuario de la organización, o a cualquier servicio o proceso que use la organización. O bien, un administrador puede deshabilitar la directiva (no se recomienda).

Microsoft no habilitará la directiva en su organización si detecta que la organización tiene procesos que podrían interrumpirse por el cambio. En su lugar, un administrador de la organización puede habilitarlo a sí mismo (recomendado).

Instrucciones para desarrolladores

Lea esta sección si es desarrollador y está intentando agregar un identificador URI (también conocido como URI de identificador de aplicación) a una API de Microsoft Entra que posee, pero recibió este error.

Hay tres formas posibles de agregar un identificador URI a la aplicación. Se recomiendan en el orden siguiente:

  1. Uso de uno de los patrones de URI seguros

  2. Si ha detectado este error, significa que la API usa actualmente tokens v1.0. Puede desbloquearse actualizando su servicio para que acepte los tokens de la versión 2.0. Los tokens V2.0 son similares a v1.0, pero hay algunas diferencias. Una vez que el servicio puede controlar los tokens v2.0, puede actualizar la configuración de la aplicación para que Microsoft Entra los envíe tokens v2.0. Una manera fácil de hacerlo es a través del editor de manifiestos en la experiencia de registros de aplicaciones del Centro de administración de Microsoft Entra.

    Captura de pantalla de la experiencia de la versión del token de actualización.

    Sin embargo, debe proceder con cautela al realizar este cambio. Esto se debe a que una vez que la aplicación se ha actualizado al formato de token v2.0, no podrá volver a los tokens v1.0 si tiene URI de identificador no conforme configurados, a menos que se le haya concedido una exención (consulte la opción 3).

  3. Si necesita agregar un URI de identificador no conforme a la aplicación antes de poder actualizar al formato de token v2.0, puede solicitar al administrador que conceda a la aplicación una exención.

Configuración de seguridad adicional

Microsoft también ofrece una política de seguridad más restrictiva para la propiedad identifierUris. Esta directiva más restrictiva se denomina nonDefaultUriAddition.

Cuando esta protección está habilitada, no se pueden agregar nuevos URI de identificador personalizado a ninguna aplicación de esa organización, excepto en escenarios seguros conocidos. En concreto, si se cumple alguna de las condiciones siguientes, se puede agregar un URI de identificador:

  • El identificador URI que se va a agregar a la aplicación es uno de los URI "predeterminados", lo que significa que está en el formato de api://{appId} o api://{tenantId}/{appId}
  • La aplicación acepta tokens v2.0 de Entra. Esto es verdadero si la propiedad api.requestedAccessTokenVersion de la aplicación está establecida en 2.
  • La aplicación usa el protocolo SAML para el inicio de sesión único (SSO). Esto es verdadero si la entidad de servicio de la aplicación tiene establecida su propiedad preferredSingleSignOnMode en SAML.
  • Un administrador ha concedido una exención a la aplicación a la que se agrega el URI, o al usuario o servicio que realiza la adición.

Una vez habilitada esta protección, si alguien de la organización intenta agregar un URI de identificador personalizado a una aplicación v1, recibirá un error similar al siguiente:

The newly added URI {uri} must comply with the format 'api://{appId}' or 'api://{tenantId}/{appId}' as per the default app management policy of your organization. If the requestedAccessTokenVersion is set to 2, this restriction may not apply. See https://aka.ms/identifier-uri-addition-error for more information on this error.

Esta directiva más restrictiva puede ayudar a proteger a su organización frente a errores comunes de validación de tokens en la audience declaración. Se recomienda habilitarlo si es posible, pero Microsoft no lo habilitará en su nombre.

Para habilitar esta directiva más restrictiva en su organización, puede ejecutar este script.

Al igual que la otra directiva, los administradores también pueden conceder exenciones a esta directiva o deshabilitarla después de habilitarla .

Preguntas más frecuentes

¿Qué son los URI de identificador?

Los URI de identificador (también denominados "URI de id. de aplicación") permiten que un desarrollador de recursos (API) especifique un valor de cadena para su aplicación como identificador. Los clientes que adquieren un token para la API pueden usar este valor de cadena durante una solicitud de OAuth. Por ejemplo, si una API había configurado un identificador URI de https://api.contoso.com, los clientes de la API podrían especificar ese valor en las solicitudes de OAuth a Microsoft Entra. Este identificador URI se utiliza como declaración de audiencia en los tokens de acceso de la versión 1.0.

Los URI de identificador se configuran mediante la página "Exponer una API" en Registros de aplicaciones. En los registros de aplicaciones, el URI de identificador se conoce como URI de ID de aplicación; este término es sinónimo de URI de identificador.

Captura de pantalla de la experiencia de configuración del identificador URI.

¿Cómo funcionan estas directivas?

Los cumplimientos se activan configurando las directivas de administración de aplicaciones de una organización. Un administrador de inquilinos puede activarlo o desactivarlo. Microsoft lo habilita de forma predeterminada en algunas organizaciones durante los meses de junio y julio de 2025.

Obtenga información sobre cómo comprobar si la protección se ha habilitado en su organización

Aunque Microsoft habilita esta configuración de forma predeterminada, los administradores de inquilinos conservan el control sobre ella. Pueden activarlo, desactivarlo o concederle excepciones.