Microsoft Entra アプリケーションの識別子 URI に関する制限事項

2025-06-13

Microsoft Entra アプリケーションの identifierUri ( Application ID URI - プロパティとも呼ばれます) は、通常、リソース (API) アプリケーションで構成されるプロパティです。このプロパティを安全に構成することは、リソースのセキュリティにとって重要です。

セキュリティで保護されたパターン

次の API および HTTP スキームベースのアプリケーション ID URI 形式がサポートされます。表の後の一覧の説明に従って、プレースホルダーの値を置き換えてください。

サポートされるアプリケーション ID URI 形式	アプリ ID URI の例
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> - アプリケーションオブジェクトのアプリケーション ID (appId) プロパティ。
<string> - ホストまたは API パスのセグメントの文字列値。
<tenantId> - Azure 内のテナントを表すために Azure によって生成された GUID。
<tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com。<tenantInitialDomain> は、テナント作成時にテナント作成者が指定した初期ドメイン名です。
<verifiedCustomDomain> - Microsoft Entra テナント用に構成された検証済みのカスタムドメイン。

注

api:// スキームを使用している場合は、"api://" の直後に文字列値を追加します。たとえば、api://<string> です。その文字列値には、GUID または任意の文字列を指定できます。 GUID 値を追加する場合は、アプリ ID またはテナント ID と一致する必要があります。文字列値を使用する場合は、テナントの検証済みのカスタムドメインまたは初期ドメインを使用する必要があります。 api://<appId> を使用することをお勧めします。

Von Bedeutung

アプリケーション ID URI の値は、スラッシュ "/" 文字で終わる必要があります。

Von Bedeutung

アプリケーション ID URI の値は、テナント内で一意である必要があります。

ポリシーを使用してセキュリティで保護されたパターンを適用する

Microsoft は、Microsoft Entra アプリケーションで識別子 URI ("アプリ ID URI" とも呼ばれます) の安全でない構成から保護するセキュリティ設定を導入しました。このセキュリティ設定により、v1 アプリケーションに新しく追加された URI が、上記のセキュリティで保護されたパターンに準拠します。

ポリシーの動作

この設定を有効にすると、セキュリティで保護されたパターンが厳密に適用されます。有効にすると、組織内の誰かがセキュリティで保護されたパターンに準拠していない識別子 URI を追加しようとすると、次のようなエラーが表示されます。

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.

アプリケーションの api.requestedAccessTokenVersion プロパティを 2 に設定することで、v2.0 Entra ID トークンを使用するように構成されているアプリケーションは、既定で除外されます。サービスプリンシパルの preferredSingleSignOnMode プロパティを SAML に設定することで、SSO に SAML プロトコルを使用するように構成されているアプリケーションも、既定で除外されます。

アプリで既に構成されている既存の識別子 URI は影響を受けず、すべてのアプリは引き続き通常どおりに機能します。これは、Microsoft Entra アプリ構成の新しい更新にのみ影響します。

有効になっていない場合でも、一部の安全でないパターンを引き続き使用できます。たとえば、 api://{string} 形式の URI は引き続き追加できます。ただし、設定が無効になっている場合でも、一部のシナリオ (たとえば、 https:// スキームを使用する場合) には、テナントの検証済みドメインまたは初期ドメインが必要になることがあります。

ポリシーの有効化と管理

Microsoft は、セキュリティを強化するために、組織内でこのポリシーを既に有効にしている可能性があります。このスクリプトを実行して確認できます。

Microsoft が組織内のポリシーを有効にした場合でも、テナント管理者はそのポリシーを完全に制御できます。特定の Microsoft Entra アプリケーション、自分自身、組織内の別のユーザー、または組織が使用する任意のサービスまたはプロセスに除外を付与できます。または、管理者はポリシーを無効にすることができます (推奨されません)。

変更によって中断される可能性のあるプロセスが組織で検出された場合、Microsoft は組織内のポリシーを有効にしません。代わりに、組織内の管理者が自分で有効にすることができます (推奨)。

開発者向けのガイダンス

開発者で、所有する Microsoft Entra API に識別子 URI (アプリ ID URI とも呼ばれます) を追加しようとしているが、このエラーが発生した場合は、このセクションをお読みください。

アプリに識別子 URI を追加するには、3 つの方法があります。次の順序で行うことをお勧めします。

セキュリティで保護された URI パターンのいずれかを使用する
このエラーが発生した場合は、API で現在 v1.0 トークンが使用されていることを意味します。 v2.0 トークンを受け入れるようにサービスを更新することで、自分でブロックを解除できます。 V2.0 トークンは v1.0 に似ていますが、いくつかの違いがあります。サービスが v2.0 トークンを処理できるようになったら、Microsoft Entra から v2.0 トークンが送信されるようにアプリ構成を更新できます。これを行う簡単な方法は、 Microsoft Entra 管理センターのアプリ登録エクスペリエンスのマニフェストエディターを使用することです。

ただし、 この変更を行う場合は注意が必要です。これは、アプリが v2.0 トークン形式に更新されると、非準拠識別子 URI が構成されている場合、除外が許可されていない限り v1.0 トークンに切り替えることができないためです (オプション 3 を参照)。
v2.0 トークン形式に更新する前に、準拠していない識別子 URI をアプリに追加する必要がある場合は、アプリに除外を付与するように管理者に要求できます。

追加のセキュリティ設定

Microsoft では、 identifierUris プロパティに対してより制限の厳しいセキュリティポリシーも提供しています。このより制限の厳しいポリシーは、 nonDefaultUriAdditionと呼ばれます。

この保護を有効にすると、既知のセキュリティで保護されたシナリオを除き、その組織内のどのアプリケーションにも新しいカスタム識別子 URI を追加できません。具体的には、次のいずれかの条件が満たされている場合でも、識別子 URI を追加できます。

アプリに追加される識別子 URI は、"既定" URI の 1 つであり、 api://{appId} または api://{tenantId}/{appId}
アプリは、 v2.0 Entra トークンを受け入れます。これは、アプリの api.requestedAccessTokenVersion プロパティが 2 に設定されている場合に当てはまります。
このアプリでは、シングルサインオン (SSO) に SAML プロトコルを使用します。これは、アプリのサービスプリンシパルの preferredSingleSignOnMode プロパティが SAML に設定されている場合に当てはまります。
URI が追加されているアプリ、または追加を実行しているユーザーまたはサービスに対して、管理者によって除外が付与されています。

この保護が有効になると、組織内の誰かが v1 アプリケーションにカスタム識別子 URI を追加しようとすると、次のようなエラーが表示されます。

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.

このより制限の厳しいポリシーは、 audience 要求の一般的なトークン検証エラーから組織を保護するのに役立ちます。可能であれば有効にすることをお勧めしますが、Microsoft はユーザーに代わって有効にしません。

組織内でこのより制限の厳しいポリシーを有効にするには、このスクリプトを実行します。

他のポリシーと同様に、管理者はこのポリシーに除外を付与したり、有効にした後で無効にしたりすることもできます。

よくあるご質問

識別子 URI とは

識別子 URI ("アプリ ID URI" とも呼ばれます) を使用すると、リソース (API) 開発者はアプリケーションの文字列値をその識別子として指定できます。 API のトークンを取得したクライアントは、OAuth 要求中にこの文字列値を使用できます。たとえば、API が https://api.contoso.com の識別子 URI を構成している場合、API のクライアントは、Microsoft Entra への OAuth 要求でその値を指定できます。この識別子 URI は、v1.0 アクセストークンの対象ユーザー要求として使用されます。

識別子 URI は、アプリ登録の [API の公開] ページを使用して構成されます。アプリの登録では、識別子 URI はアプリケーション ID URI と呼ばれます。これは識別子 URI と同義です。

これらのポリシーのしくみ

適用は、組織のアプリ管理ポリシーを構成することによって有効になります。テナント管理者は、そのオンとオフを切り替えることができます。 Microsoft では、2025 年 6 月と 7 月の間に、一部の組織で既定で有効にしています。

組織で保護が有効になっているかどうかを確認する方法について説明します

Microsoft では既定でこの設定を有効にしていますが、テナント管理者は管理を維持します。オン、オフ、または例外を許可することができます。