Microsoft Entra のアプリマニフェスト

[アーティクル]
04/10/2024

アプリケーションマニフェストには、Microsoft ID プラットフォームにあるアプリケーションオブジェクトのすべての属性の定義が含まれます。それは、アプリケーションオブジェクトを更新するメカニズムとしても機能します。アプリケーションエンティティとそのスキーマの詳細については、Graph API のアプリケーションエンティティに関するドキュメントを参照してください。

Microsoft Entra 管理センターで、あるいは Microsoft Graph API または Microsoft Graph PowerShell SDK を使用してプログラムでアプリの属性を構成できます。ただし、一部のシナリオでは、アプリマニフェストを編集してアプリの属性を構成する必要があります。これらのシナリオは、次のとおりです。

Microsoft Entra マルチテナントと個人用 Microsoft アカウントの設定で、アプリを登録した場合、サポートされる Microsoft アカウントを UI で変更することはできません。代わりに、アプリケーションマニフェストエディターを使用して、サポートされるアカウントの種類を変更する必要があります。
アプリでサポートされるアクセス許可とロールを定義するには、アプリケーションマニフェストを変更する必要があります。

アプリマニフェストを構成する

アプリケーションマニフェストを構成するには:

アプリケーション開発者以上として Microsoft Entra 管理センターにサインインします。
[ID]>[アプリケーション]>[アプリの登録] を参照します。
構成するアプリを選択します。
アプリの [概要] ページで、 [マニフェスト] セクションを選択します。 Web ベースのマニフェストエディターが開き、マニフェストを編集できます。必要があれば、 [ダウンロード] を選択してローカルでマニフェストを編集します。その後、 [アップロード] を使用して、アプリケーションにマニフェストを再適用します。

マニフェストリファレンス

ここでは、アプリケーションマニフェストで見られる属性について説明します。

id 属性

Key	値の型
id	String

ディレクトリ内のアプリの一意識別子。この ID は、いずれかのプロトコルトランザクション内のアプリを識別するために使用される識別子ではありません。これは、ディレクトリクエリ内のオブジェクトを参照するために使用されます。

例:

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

acceptMappedClaims 属性

Key	値の型
acceptMappedClaims	Nullable Boolean

「apiApplication リソースの種類」に記載されているように、これにより、カスタム署名キーを指定せずに、アプリケーションでクレームマッピングが使用できます。トークンを受信するアプリケーションは、クレーム値が Microsoft Entra ID によって正式に発行され、改ざんできないという事実に依存しています。ただし、クレームマッピングポリシーによってトークンの内容を変更すると、この前提は通用しなくなります。悪意のある目的で作成されたクレームマッピングポリシーからアプリケーションを保護するため、アプリケーションでは、クレームマッピングポリシーの作成者がトークンを変更したことを、明示的に確認する必要があります。

警告

マルチテナントアプリでは acceptMappedClaims プロパティを true に設定しないでください。悪意のある者がアプリのクレームマッピングポリシーを作成することを許可してしまう場合があります。

例:

    "acceptMappedClaims": true,

accessTokenAcceptedVersion 属性

Key	値の型
accessTokenAcceptedVersion	Null 許容の Int32

リソースで想定されているアクセストークンのバージョンを指定します。このパラメーターを使うと、アクセストークンを要求するために使用されたエンドポイントまたはクライアントとは関係なく、生成される JWT のバージョンと形式を変更できます。

使用されるエンドポイント (v1.0 または v2.0) はクライアントによって選択され、id_token のバージョンにのみ影響します。リソースでは、サポートされるアクセストークンの形式を明示的に示すように、accesstokenAcceptedVersion を構成する必要があります。

accesstokenAcceptedVersion に指定できる値は、1、2、または null です。値が null の場合、このパラメーターの既定値は 1 であり、v1.0 のエンドポイントに対応します。

signInAudience が AzureADandPersonalMicrosoftAccount の場合は、値は 2 である必要があります。

例:

    "accessTokenAcceptedVersion": 2,

addIns 属性

Key	値の型
addIns	コレクション

使用するサービスが特定のコンテキストでアプリの呼び出しに使用できるカスタム動作を定義します。たとえば、ファイルストリームをレンダリングできるアプリケーションでは、その "FileHandler" 機能の addIns プロパティを設定できます。このパラメーターを使うと、Microsoft 365 などのサービスで、ユーザーが作業中のドキュメントのコンテキストでアプリケーションを呼び出すことができます。

例:

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

allowPublicClient 属性

Key	値の型
allowPublicClient	Boolean

フォールバックアプリケーションの種類を指定します。 Microsoft Entra ID は、既定では replyUrlsWithType からアプリケーションの種類を推測します。 Microsoft Entra ID がクライアントアプリの種類を判断できない特定のシナリオがあります。たとえば、このようなシナリオの 1 つとして、URL リダイレクトなしで HTTP 要求が発生する ROPC フローがあります。そのような場合、Microsoft Entra ID では、このプロパティの値に基づいて、アプリケーションの種類を解釈します。この値が true に設定されている場合、フォールバックアプリケーションの種類は、モバイルデバイス上で実行されているインストール済みのアプリなど、パブリッククライアントとして設定されます。既定値は false です。これは、フォールバックアプリケーションの種類が、Web アプリなどの機密クライアントであることを意味します。

例:

    "allowPublicClient": false,

appId 属性

Key	値の型
appId	String

Microsoft Entra ID によってアプリに割り当てられた一意識別子を指定します。

例:

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

appRoles 属性

Key	値の型
appRoles	コレクション

アプリが宣言する可能性のあるロールのコレクションを指定します。これらのロールは、ユーザー、グループ、またはサービスプリンシパルに割り当てることができます。その他の例および詳細については、「アプリケーションにアプリロールを追加してトークンで受け取る」を参照してください。

例:

    "appRoles": [
        {
           "allowedMemberTypes": [
               "User"
           ],
           "description": "Read-only access to device information",
           "displayName": "Read Only",
           "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
           "isEnabled": true,
           "value": "ReadOnly"
        }
    ],

errorUrl 属性

Key	値の型
errorUrl	String

サポートされていません。

groupMembershipClaims 属性

Key	値の型
groupMembershipClaims	String

アプリが期待する、ユーザーまたは OAuth 2.0 アクセストークンで発行される groups 要求を構成します。この属性を設定するには、次のいずれかの有効な文字列値を使用します。

"None"
"SecurityGroup"(セキュリティグループと Microsoft Entra ロールの場合)
"ApplicationGroup" (このオプションには、アプリケーションに割り当てられているグループのみが含まれます)
"DirectoryRole" (ユーザーがメンバーになっている Microsoft Entra ディレクトリロールを取得します)
"All" (これは、サインインユーザーがメンバーになっているすべてのセキュリティグループ、配布グループ、Microsoft Entra ディレクトリロールを取得します)。

例:

    "groupMembershipClaims": "SecurityGroup",

optionalClaims 属性

Key	値の型
optionalClaims	String

この特定のアプリのセキュリティトークンサービスによってトークンで返される省略可能な要求。

個人アカウントと Microsoft Entra ID の両方をサポートするアプリでは、省略可能な要求を使用できません。ただし、v2.0 エンドポイントを使用して Microsoft Entra ID のみに登録されたアプリは、マニフェストで要求した省略可能な要求を取得することができます。詳細については、「省略可能な要求」に関するページを参照してください。

例:

    "optionalClaims": null,

identifierUris 属性

Key	値の型
identifierUris	String Array

Microsoft Entra テナントまたは検証済みの顧客所有ドメイン内で Web アプリを一意に識別するユーザー定義 URI。アプリケーションをリソースアプリとして使用する場合、リソースを一意に識別してアクセスするために、identifierUri 値が使用されます。

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

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

Note

api:// スキームを使用している場合は、"api://" の直後に文字列値を追加します。たとえば、api://<string> です。その文字列値には、GUID または任意の文字列を指定できます。 GUID 値を追加する場合は、アプリ ID またはテナント ID と一致する必要があります。アプリケーション ID URI の値は、テナントに対して一意である必要があります。アプリケーション ID URI として api://<tenantId> を追加すると、他の誰も他のアプリでその URI を使用できなくなります。代わりに api://<appId>、または HTTP スキームを使用することをお勧めします。

重要

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

例:

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

informationalUrls 属性

Key	値の型
informationalUrls	String

アプリのサービス利用規約とプライバシーに関する声明へのリンクを指定します。サービス利用規約とプライバシーに関する声明は、ユーザーの同意エクスペリエンスからユーザーに提示されます。詳細については、「登録済み Microsoft Entra アプリのサービス使用条件とプライバシーに関する声明を追加する方法」を参照してください。

例:

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

keyCredentials 属性

Key	値の型
keyCredentials	コレクション

アプリで割り当てられた資格情報、文字列ベースの共有シークレット、および X.509 証明書への参照を保持します。これらの資格情報は、アクセストークンを要求するときに使用されます (そのアプリがリソースとしてではなく、クライアントとして機能している場合)。

例:

    "keyCredentials": [
        {
           "customKeyIdentifier":null,
           "endDateTime":"2018-09-13T00:00:00Z",
           "keyId":"<guid>",
           "startDateTime":"2017-09-12T00:00:00Z",
           "type":"AsymmetricX509Cert",
           "usage":"Verify",
           "value":null
        }
    ],

knownClientApplications 属性

Key	値の型
knownClientApplications	String Array

クライアントアプリとカスタム Web API アプリの 2 つの部分を含むソリューションがある場合に、同意をバンドルするために使用されます。この値にクライアントアプリの appID を入力すると、ユーザーは、クライアントアプリに 1 回同意するだけで済みます。クライアントへの同意が Web API への暗黙的な同意を意味することが Microsoft Entra ID によって認識されます。クライアントと Web API の両方のサービスプリンシパルが同時に自動でプロビジョニングされます。クライアントと Web API アプリの両方が同じテナントに登録されている必要があります。

例:

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

logoUrl 属性

Key	値の型
logoUrl	String

アップロードされたロゴへの CDN URL を指す値のみを読み取ります。

例:

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

logoutUrl 属性

Key	値の型
logoutUrl	String

アプリからログアウトするための URL。

例:

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

name 属性

Key	値の型
name	String

アプリの表示名。

例:

    "name": "MyRegisteredApp",

oauth2AllowImplicitFlow 属性

Key	値の型
oauth2AllowImplicitFlow	Boolean

この Web アプリで OAuth2.0 暗黙的フローアクセストークンを要求できるかどうかを指定します。既定値は false です。このフラグは、ブラウザーベースのアプリ (JavaScript シングルページアプリなど) に使用されます。詳細については、目次に「OAuth 2.0 implicit grant flow」と入力し、暗黙的フローに関するトピックを表示します。

例:

    "oauth2AllowImplicitFlow": false,

oauth2AllowIdTokenImplicitFlow 属性

Key	値の型
oauth2AllowIdTokenImplicitFlow	Boolean

この Web アプリで OAuth2.0 暗黙的フロー ID トークンを要求できるかどうかを指定します。既定値は false です。このフラグは、ブラウザーベースのアプリ (JavaScript シングルページアプリなど) に使用されます。

例:

    "oauth2AllowIdTokenImplicitFlow": false,

oauth2Permissions 属性

Key	値の型
oauth2Permissions	コレクション

Web API (リソース) アプリがクライアントアプリに公開する OAuth 2.0 アクセス許可スコープのコレクションを指定します。これらのアクセス許可スコープは、同意中にクライアントアプリに付与できます。

例:

    "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"
        }
    ],

oauth2RequiredPostResponse 属性

Key	値の型
oauth2RequiredPostResponse	ブール型

OAuth 2.0 トークン要求の一部として、Microsoft Entra ID が GET 要求ではなく、POST 要求を許可するかどうかを指定します。既定値は false です。これは、GET 要求のみが許可されることを指定します。

例:

    "oauth2RequirePostResponse": false,

parentalControlSettings 属性

Key	値の型
parentalControlSettings	String

countriesBlockedForMinors は、未成年者に関してアプリがブロックされる国/地域を指定します。
legalAgeGroupRule は、アプリのユーザーに適用される法的年齢グループルールを指定します。 Allow、RequireConsentForPrivacyServices、RequireConsentForMinors、RequireConsentForKids、BlockMinors のいずれかに設定できます。

例:

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

passwordCredentials 属性

Key	値の型
passwordCredentials	コレクション

keyCredentials プロパティの説明を参照してください。

例:

    "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"
      }
    ],

preAuthorizedApplications 属性

Key	値の型
preAuthorizedApplications	コレクション

暗黙的に同意するアプリケーションと要求されたアクセス許可がリストされます。管理者がアプリケーションに同意する必要があります。 preAuthorizedApplications では、ユーザーが要求されたアクセス許可に同意する必要はありません。 PreAuthorizedApplications でリストされるアクセス許可にはユーザーの同意は必要ありません。しかし、preAuthorizedApplications にリストされていない追加の要求されたアクセス許可にはユーザーの同意が必要です。

例:

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

publisherDomain 属性

Key	値の型
publisherDomain	String

アプリケーションの確認された発行元のドメイン。読み取り専用です。

例:

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

replyUrlsWithType 属性

Key	値の型
replyUrlsWithType	コレクション

この複数値プロパティは、Microsoft Entra ID がトークンを返すときに宛先として受け入れる登録済みの redirect_uri 値の一覧を保持します。各 URI 値には、関連付けられているアプリの種類の値を含める必要があります。サポートされる種類の値は次のとおりです。

Web
InstalledClient
Spa

詳細については、replyUrl の制約と制限に関するページを参照してください。

例:

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

requiredResourceAccess 属性

Key	値の型
requiredResourceAccess	コレクション

動的な同意では、静的な同意を使用しているユーザーに対する管理者の同意エクスペリエンスおよびユーザーの同意エクスペリエンスが requiredResourceAccess によって作動します。ただし、このパラメーターを使用しても、一般的な場合のユーザーの同意エクスペリエンスは促進されません。

resourceAppId は、アプリがアクセスする必要があるリソースの一意識別子です。この値は、ターゲットリソースアプリで宣言された appId に等しくなるようにしてください。
resourceAccess は、指定されたリソースに対してアプリが必要とする OAuth2.0 アクセス許可スコープとアプリロールを格納する配列です。指定されたリソースの id と type の値が格納されます。

例:

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

samlMetadataUrl 属性

Key	値の型
samlMetadataUrl	String

アプリの SAML メタデータへの URL。

例:

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

signInUrl 属性

Key	値の型
signInUrl	String

アプリのホームページへの URL を指定します。

例:

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

signInAudience 属性

Key	値の型
signInAudience	String

現在のアプリケーションでサポートされる Microsoft アカウントを指定します。サポートされる値は次のとおりです。

AzureADMyOrg - 自分の組織の Microsoft Entra テナント (たとえば、シングルテナント) に、Microsoft の職場アカウントまたは学校アカウントを持つユーザー
AzureADMultipleOrgs - 任意の組織の Microsoft Entra テナント (たとえば、マルチテナント) に、Microsoft の職場アカウントまたは学校アカウントを持つユーザー
AzureADandPersonalMicrosoftAccount - 個人用の Microsoft アカウント、または任意の組織の Microsoft Entra テナントに職場アカウントまたは学校アカウントを持つユーザー
PersonalMicrosoftAccount - Xbox や Skype などのサービスのサインインに使用する個人用アカウント。

例:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

tags 属性

Key	値の型
tags	String Array

アプリケーションの分類と特定に使用できるカスタム文字列。

例:

    "tags": [
       "ProductionApp"
    ],

一般的な問題

マニフェストの制限

アプリケーションマニフェストには、appRoles、keyCredentials、knownClientApplications、identifierUris、redirectUris、requiredResourceAccess、oauth2Permissions など複数の属性があり、コレクションと呼ばれています。任意のアプリケーションの完全なアプリケーションマニフェスト内では、すべてのコレクションを組み合わせたときのエントリの合計数は 1200 個に制限されています。アプリケーションマニフェストで 100 個のリダイレクト URI を以前に指定した場合、マニフェストを構成する他の組み合わされたコレクション全体で使用できるエントリ数は残りの 1100 個です。

注意

アプリケーションマニフェストに 1200 個を超えるエントリを追加しようとすると、"アプリケーション xxxxxx を更新できませんでした。エラーの詳細:マニフェストのサイズ制限を超えました。値の数を減らしてから、要求を再試行してください" というエラーが表示される場合があります。

サポート外の属性

アプリケーションマニフェストでは、Microsoft Entra ID の基礎となっているアプリケーションモデルのスキーマが表示されます。基になるスキーマの進化に応じて、マニフェストエディターが新しいスキーマを反映するように随時更新されます。このため、アプリケーションマニフェストに新しい属性が表示される場合があります。まれに、既存の属性が構文上またはセマンティックに変更されていたり、以前に存在していた属性がサポートされなくなっていたりする場合があります。たとえば、アプリの登録には、アプリの登録 (レガシ) エクスペリエンスでは別の呼称だった新しい属性が表示されます。

アプリの登録 (レガシ)	アプリの登録
`availableToOtherTenants`	`signInAudience`
`displayName`	`name`
`errorUrl`	-
`homepage`	`signInUrl`
`objectId`	`Id`
`publicClient`	`allowPublicClient`
`replyUrls`	`replyUrlsWithType`

これらの属性については、マニフェストリファレンスのセクションをご覧ください。

以前にダウンロードしたマニフェストをアップロードしようとすると、次のいずれかのエラーが表示される場合があります。マニフェストエディターで現在サポートされている新しいバージョンのスキーマが、アップロードしようとしているスキーマと一致していないためにこのエラーが発生している可能性があります。

"xxxxxx アプリケーションを更新できませんでした。エラーの詳細:無効なオブジェクト識別子 'undefined' です。 []."
"xxxxxx アプリケーションを更新できませんでした。エラーの詳細:指定した 1 つ以上のプロパティ値が無効です。 []."
"xxxxxx アプリケーションを更新できませんでした。エラーの詳細:この API バージョンで更新用に availableToOtherTenants を設定することはできません。 []."
"xxxxxx アプリケーションを更新できませんでした。エラーの詳細:'replyUrls' プロパティの更新は、このアプリケーションでは許可されていません。代わりに、'replyUrlsWithType' プロパティを使用してください。 []."
"xxxxxx アプリケーションを更新できませんでした。エラーの詳細:型名のない値が見つかりましたが、使用できる必要な型がありません。モデルが指定されている場合、ペイロード内の値ごとに型が必要です。その型は、ペイロードで指定できる型か、呼び出し元による明示的な型か、親値から暗黙的に推定される型にすることができます。 []"

これらのエラーのいずれかが表示された場合、以下の操作を実行することをお勧めします。

以前にダウンロードしたマニフェストのアップロードではなく、マニフェストエディターで個別に属性を編集します。関心のある属性を正常に編集するために、マニフェストリファレンスの表を使って新旧の属性の構文とセマンティクスを理解します。
ワークフローにおいて、後で使用するためにソースリポジトリ内にマニフェストを保存する必要がある場合は、リポジトリに保存されたマニフェストを、アプリの登録エクスペリエンスに表示されているものにリベースすることをお勧めします。

次のステップ

アプリのアプリケーションオブジェクトとサービスプリンシパルオブジェクトの関係の詳細については、「Microsoft Entra ID のアプリケーションオブジェクトとサービスプリンシパルオブジェクト」を参照してください。
Microsoft ID プラットフォーム開発者向けの基本的な一部の概念の定義については、「Microsoft ID プラットフォーム開発者向け用語集」を参照してください。

次のコメントセクションを使用して、Microsoft のコンテンツの改善に役立つフィードバックを提供してください。

Microsoft Entra のアプリ マニフェスト

アプリ マニフェストを構成する

マニフェスト リファレンス