次の方法で共有


Microsoft Graph を使用してMicrosoft Entra アプリケーションを管理する

アプリは、Microsoft ID プラットフォームが Microsoft クラウドに格納されているデータへのアクセスを承認する前に、Microsoft Entra IDに登録する必要があります。 この条件は、自分で開発したアプリ、テナントが所有しているアプリ、またはアクティブなサブスクリプションを通じてアクセスするアプリに適用されます。

アプリの多くの設定は、Microsoft Graph を使用してアクセス、更新、または削除できるオブジェクトとして記録されます。 この記事では、Microsoft Graph を使用して、プロパティ、アクセス許可、ロールの割り当てを含むアプリおよびサービス プリンシパル オブジェクトの詳細を管理する方法について説明します。

前提条件

API 操作をテストするには、次のリソースと特権が必要です。

  • 作業Microsoft Entraテナント。
  • テナントでアプリケーションを作成および管理できる権限を持つユーザーとして Graph エクスプローラーにサインインします。
  • 操作に対して示されている最小限の特権委任されたアクセス許可を自分に付与します。

アプリケーションをMicrosoft Entra IDに登録する

次の要求では、必要な displayName プロパティのみを指定してアプリを作成します。 その他のプロパティには既定値が割り当てられます。

最小特権委任アクセス許可: Application.ReadWrite.All

POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json

{
  "displayName": "My application"
}

要求は、応答本文にアプリケーション オブジェクトを含む 201 Created 応答を返します。 アプリケーションには、テナント内のアプリに固有の ID と、Microsoft Entra ID エコシステムでグローバルに一意の appId が割り当てられます。

アプリケーションのサービス プリンシパルを作成する

最小特権委任アクセス許可: Application.ReadWrite.All

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
  "appId": "fc876dd1-6bcb-4304-b9b6-18ddf1526b62"
}

要求は、応答本文にサービス プリンシパル オブジェクトを含む 201 Created 応答を返します。

アプリケーションまたはサービス プリンシパル オブジェクトのアドレス指定

アプリケーションまたはサービス プリンシパルのアドレスは、ID またはその appId で指定できます。ID はオブジェクト ID と呼ばれ、appId はMicrosoft Entra 管理センターのアプリケーション (クライアント) ID と呼ばれます。 これらの構文は、アプリケーションとサービス プリンシパルに対するすべての HTTP CRUD 操作でサポートされます。

アプリケーションまたはサービス プリンシパルの ID でアドレス指定する。

https://graph.microsoft.com/v1.0/applications/{applicationObjectId}
https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalObjectId}

appId によってアプリケーションまたはサービス プリンシパルに対処する。

https://graph.microsoft.com/v1.0/applications(appId='appId')
https://graph.microsoft.com/v1.0/servicePrincipals(appId='appId')

さらに、アプリケーション オブジェクト固有の uniqueName に対処することもできます。 このプロパティを使用して、一意の名前のアプリケーションが存在しない場合は作成するか、存在する場合は更新できます。"Upsert" と呼ばれる操作。

指定した uniqueName が存在しない場合は、アプリケーションを作成し、それ以外の場合は更新します。

PATCH https://graph.microsoft.com/v1.0/applications(uniqueName='{uniqueName}')
Content-Type: application/json
Prefer: create-if-missing

{
  "displayName": "Display name"
}

アプリのその他の基本的なプロパティを構成する

最小特権委任アクセス許可: Application.ReadWrite.All

アプリの次の基本的なプロパティを構成します。

  • organizationに分類用のタグを追加します。 また、HideApp タグを使用して、アプリをマイ アプリおよび Microsoft 365 Launcher から非表示にします。
  • ロゴ、利用規約、プライバシーに関する声明などの基本情報を追加します。
  • アプリケーションに関する連絡先情報を保存する
PATCH https://graph.microsoft.com/v1.0/applications/0d0021e2-eaab-4b9f-a5ad-38c55337d63e/
Content-type: application/json

{
    "tags": [
        "HR",
        "Payroll",
        "HideApp"
    ],
    "info": {
        "logoUrl": "https://cdn.pixabay.com/photo/2016/03/21/23/25/link-1271843_1280.png",
        "marketingUrl": "https://www.contoso.com/app/marketing",
        "privacyStatementUrl": "https://www.contoso.com/app/privacy",
        "supportUrl": "https://www.contoso.com/app/support",
        "termsOfServiceUrl": "https://www.contoso.com/app/termsofservice"
    },
    "web": {
        "homePageUrl": "https://www.contoso.com/",
        "logoutUrl": "https://www.contoso.com/frontchannel_logout",
        "redirectUris": [
            "https://localhost"
        ]
    },
    "serviceManagementReference": "Owners aliases: Finance @ contosofinance@contoso.com; The Phone Company HR consulting @ hronsite@thephone-company.com;"
}

アプリのサインインを割り当てられた ID のみに制限する

次の操作では、アプリにサインインできる ID を、アプリ上のすべてのロールが割り当てられている ID のみに制限します。

最小特権委任アクセス許可: Application.ReadWrite.All

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/89473e09-0737-41a1-a0c3-1418d6908bcd

{
    "appRoleAssignmentRequired": true
}

アプリにアクセス許可を割り当てる

Microsoft Entra 管理センターを使用してアプリにアクセス許可を割り当てることができますが、アプリ オブジェクトの requiredResourceAccess プロパティを更新することで、Microsoft Graph を使用してアクセス許可を割り当てることもできます。 既存のアクセス許可と新しいアクセス許可の両方を渡す必要があります。 新しいアクセス許可のみを渡すと、まだ同意されていない既存のアクセス許可が上書きされ、削除されます。

アクセス許可を割り当てると、アプリに自動的に付与されることはありません。 引き続き、Microsoft Entra 管理センターを使用して管理者の同意を付与する必要があります。 対話型の同意なしでアクセス許可を付与するには、「 プログラムによる API アクセス許可の付与または取り消し」を参照してください。

最小特権委任アクセス許可: Application.ReadWrite.All

PATCH https://graph.microsoft.com/v1.0/applications/581088ba-83c5-4975-b8af-11d2d7a76e98
Content-Type: application/json

{
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
                    "type": "Scope"
                },
                {
                    "id": "3afa6a7d-9b1a-42eb-948e-1650a849e176",
                    "type": "Role"
                }
            ]
        }
    ]
}

アプリ ロールを作成する

アプリケーション オブジェクトにアプリ ロールを作成する

既存のアプリ ロールを保持するには、それらを要求に含めます。 それ以外の場合は、新しいオブジェクトに置き換えられます。

PATCH https://graph.microsoft.com/v1.0/applications/bbd46130-e957-4c38-a116-d4d02afd1057
Content-Type: application/json

{
    "appRoles": [
        {
            "allowedMemberTypes": [
                "User",
                "Application"
            ],
            "description": "Survey.Read",
            "displayName": "Survey.Read",
            "id": "7a9ddfc4-cc8a-48ea-8275-8ecbffffd5a0",
            "isEnabled": false,
            "origin": "Application",
            "value": "Survey.Read"
        }
    ]
}

所有者の管理

所有者のないサービス プリンシパルとサービス プリンシパルを 1 人の所有者で識別する

最小特権委任アクセス許可: Application.ReadWrite.All

この要求では、$count が要求にあるため、ConsistencyLevel ヘッダーを eventual に設定する必要があります。 ConsistencyLevel$count の使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

この要求は、フィルター条件に一致するアプリの数も返します。

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=owners/$count eq 0 or owners/$count eq 1&$count=true
ConsistencyLevel: eventual

アプリに所有者を割り当てる

最小特権委任アクセス許可: Application.ReadWrite.All

次の要求では、 8afc02cb-4d62-4dba-b536-9f6d73e9be26 はユーザーまたはサービス プリンシパルのオブジェクト ID です。

POST https://graph.microsoft.com/v1.0/applications/7b45cf6d-9083-4eb2-92c4-a7e090f1fc40/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"
}

サービス プリンシパルに所有者を割り当てる

最小特権委任アクセス許可: Application.ReadWrite.All

次の要求は、 appId を使用してサービス プリンシパルを参照します。 または、パターン ../servicePrincipals/{bject ID}/owners/$refの オブジェクト ID を使用して参照することもできます。 8afc02cb-4d62-4dba-b536-9f6d73e9be26 は、ユーザーまたはサービス プリンシパルのオブジェクト ID です。

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='46e6adf4-a9cf-4b60-9390-0ba6fb00bf6b')/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"
}

サービス プリンシパルの機密性の高いプロパティをロックする

アプリ インスタンスロック機能を使用すると、マルチテナント アプリの機密性の高いプロパティを不正な改ざんから保護できます。 サービス プリンシパル オブジェクトの次のプロパティをロックできます。

  • 使用の種類がSignまたはVerifyされている keyCredentials
  • passwordCredentials 使用の種類が Sign または Verify
  • tokenEncryptionKeyId プロパティ。

アプリ インスタンスロック機能は、マルチテナント アプリのアプリケーション オブジェクトの servicePrincipalLockConfiguration プロパティを使用して管理します。

サービス プリンシパルのすべての機密性の高いプロパティをロックするには

isEnabledallPropertiestrueに設定されている場合、servicePrincipalLockConfiguration オブジェクトの他のプロパティがnullされている場合でも、サービス プリンシパルのすべての機密性の高いプロパティがロックされます。

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "allProperties": true
    }
}

サービス プリンシパルの特定の機密プロパティをロックするには

次の例では、サービス プリンシパルの keyCredentials プロパティと passwordCredentials プロパティをロックし、アプリ インスタンスロック機能を有効にします。

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "credentialsWithUsageSign": true,
        "credentialsWithUsageVerify": true
    }
}

アプリの信頼できる証明機関を構成する

テナント内のアプリの証明書資格情報の使用を、信頼された証明機関によって発行された証明書のみに制限できます。 このポリシーは、証明書をアプリに追加するときに適用され、既存の証明書がローテーションされない限り影響しません。 アプリは、証明書の資格情報をローテーションしようとすると、ポリシーの評価を経て、追加される資格情報が信頼された証明機関の制限に準拠していることを確認します。

手順 1: 信頼の証明書チェーンを作成する

最小特権委任アクセス許可: AppCertTrustConfiguration.Read.All最小特権Microsoft Entraロール:Application Administrator

POST https://graph.microsoft.com/beta/certificateAuthorities/certificateBasedApplicationConfigurations

{
    "displayName": "Trusted Certificate Chain of Trust for Contoso",
    "description": "The Trusted Certificate Chain of Trust containing a certificate chain used by app policy, to only allow application certificates from selected issuer.",
    "trustedCertificateAuthorities": [
        {
            "isRootAuthority": true,
            "certificate": "MIIFVjCCAz6gAwIBAgIQJdrL...UyNDIyNTcwM1owPDE …="
        },
        {
            "isRootAuthority": false,
            "certificate": QAAAAAAWjABAQsFADA8M...UyNDIyNTcwM1o …="
        }
    ]
}

要求は 200 OK 応答オブジェクトを返します。 応答には、信頼オブジェクトの証明書チェーンの ID が含まれます。 ID が eec5ba11-2fc0-4113-83a2-ed986ed13743されていると仮定します。

手順 2: 証明書の信頼チェーンをアプリケーション管理ポリシーに割り当てる

次のサンプルでは、前の手順で定義した中間証明機関によって発行された証明書のみをテナント内のアプリに追加できるようにポリシーを設定します。 applicationRestrictions>keyCredentials オブジェクトは、作成された ID を参照するtrustedCertificateAuthority値を持つ restrictionType を定義します。 このポリシーは既定のテナント レベルのアプリ管理ポリシーに適用されるため、テナントで作成されたすべてのアプリに適用され、アプリの証明書資格情報の一部として非準拠証明書の追加が拒否されます。

このポリシーにより、指定された中間証明機関の証明書のみをアプリに追加できます。 applicationRestrictions>keyCredentials オブジェクトは、作成された ID を参照して restrictionTypetrustedCertificateAuthorityに設定します。 このポリシーは、テナント内のすべてのアプリに適用され、準拠していない証明書は拒否されます。

最小特権委任アクセス許可: Policy.Read.ApplicationConfiguration最小特権Microsoft Entraロール:Security Administrator

PATCH https://graph.microsoft.com/v1.0/policies/defaultAppManagementPolicy

{
  "id": "d015220e-9789-4e8e-bbcc-270fe419229d",
  "description": "Lorem ipsum",
  "displayName": "Credential management policy",
  "isEnabled": true,
  "applicationRestrictions": {
    "passwordCredentials": [
      {
        "restrictionType": "passwordLifetime",
        "maxLifetime": "P14D",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T07:00:00Z"
      }
    ],
    "keyCredentials": [
      {
        "restrictionType": "certificateLifetime",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T10:37:00Z",
        "maxLifetime": "P90D"
      },
      {
        "restrictionType": "trustedCertificateAuthority",
        "certificateBasedApplicationConfigurationIds": [
          "eec5ba11-2fc0-4113-83a2-ed986ed13743"
        ],
        "restrictForAppsCreatedAfterDateTime": "2019-10-19T10:37:00Z"
      }
    ]
  }
}