PowerShell を使用して 1 人のユーザーに代わって同意を許可する

  • [アーティクル]

この記事では、PowerShell を使用して 1 人のユーザーに代わって同意を許可する方法について説明します。

ユーザーが自分の代わりに同意を許可すると、次のイベントが頻繁に発生します。

  1. クライアント アプリケーションのサービス プリンシパルが作成されます (存在しない場合)。 サービス プリンシパルは、Microsoft Entra テナント内のアプリケーションまたはサービスのインスタンスです。 アプリまたはサービスに許可されているアクセス権は、このサービス プリンシパル オブジェクトに関連付けられます。

  2. アプリケーションがアクセスを必要とする API ごとに、アプリケーションが必要なアクセス許可について、その API に対して委任されたアクセス許可が作成されます。 アクセス権は、ユーザーに代わって付与されます。 委任されたアクセス許可の付与は、そのユーザーがサインインしたときに、アプリケーションがユーザーに代わって API にアクセスする権限を許可します。

  3. ユーザーはクライアント アプリケーションを割り当てられます。 アプリケーションをユーザーに割り当てると、そのユーザーの [マイ アプリ] ポータルにそのアプリケーションが表示されます。 ユーザーは、マイ アプリ ポータルから自分の代わりに付与されたアクセス権をレビューおよび取り消すことができます。

前提条件

1 人のユーザーに代わってアプリケーションに同意を許可するには、次のものが必要です。

  • グローバル管理者、アプリケーション管理者、またはクラウド アプリケーション管理者を持つユーザー アカウント

開始する前に、Microsoft Entra 管理センターから次の詳細を記録します。

  • 同意を許可するアプリのアプリ ID。 この記事では、それをクライアント アプリケーションと呼びます。
  • クライアント アプリケーションに必要な API アクセス許可。 API のアプリ ID とアクセス許可 ID または要求値を調べます。
  • そのユーザーに代わってアクセス権を許可するユーザーのユーザー名またはオブジェクト ID。

この例では、Microsoft Graph PowerShell を使用して、1 人のユーザーに代わって同意を許可します。 クライアント アプリケーションは Microsoft Graph Explorer であり、Microsoft Graph API へのアクセスを許可します。

Microsoft Graph PowerShell を使用して 1 人のユーザーに代わってアプリケーションに同意を付与するには、少なくともクラウド アプリケーション管理者としてサインインする必要があります。

# The app for which consent is being granted. In this example, we're granting access
# to Microsoft Graph Explorer, an application published by Microsoft.
$clientAppId = "de8bc8b5-d9f9-48b1-a8ad-b748da725064" # Microsoft Graph Explorer

# The API to which access will be granted. Microsoft Graph Explorer makes API 
# requests to the Microsoft Graph API, so we'll use that here.
$resourceAppId = "00000003-0000-0000-c000-000000000000" # Microsoft Graph API

# The permissions to grant. Here we're including "openid", "profile", "User.Read"
# and "offline_access" (for basic sign-in), as well as "User.ReadBasic.All" (for 
# reading other users' basic profile).
$permissions = @("openid", "profile", "offline_access", "User.Read", "User.ReadBasic.All")

# The user on behalf of whom access will be granted. The app will be able to access 
# the API on behalf of this user.
$userUpnOrId = "user@example.com"

# Step 0. Connect to Microsoft Graph PowerShell. We need User.ReadBasic.All to get
#    users' IDs, Application.ReadWrite.All to list and create service principals, 
#    DelegatedPermissionGrant.ReadWrite.All to create delegated permission grants, 
#    and AppRoleAssignment.ReadWrite.All to assign an app role.
#    WARNING: These are high-privilege permissions!
Connect-MgGraph -Scopes ("User.ReadBasic.All Application.ReadWrite.All " `
                        + "DelegatedPermissionGrant.ReadWrite.All " `
                        + "AppRoleAssignment.ReadWrite.All")

# Step 1. Check if a service principal exists for the client application. 
#     If one doesn't exist, create it.
$clientSp = Get-MgServicePrincipal -Filter "appId eq '$($clientAppId)'"
if (-not $clientSp) {
   $clientSp = New-MgServicePrincipal -AppId $clientAppId
}

# Step 2. Create a delegated permission that grants the client app access to the
#     API, on behalf of the user. (This example assumes that an existing delegated 
#     permission grant does not already exist, in which case it would be necessary 
#     to update the existing grant, rather than create a new one.)
$user = Get-MgUser -UserId $userUpnOrId
$resourceSp = Get-MgServicePrincipal -Filter "appId eq '$($resourceAppId)'"
$scopeToGrant = $permissions -join " "
$grant = New-MgOauth2PermissionGrant -ResourceId $resourceSp.Id `
                                     -Scope $scopeToGrant `
                                     -ClientId $clientSp.Id `
                                     -ConsentType "Principal" `
                                     -PrincipalId $user.Id

# Step 3. Assign the app to the user. This ensures that the user can sign in if assignment
#     is required, and ensures that the app shows up under the user's My Apps portal.
if ($clientSp.AppRoles | ? { $_.AllowedMemberTypes -contains "User" }) {
    Write-Warning ("A default app role assignment cannot be created because the " `
                 + "client application exposes user-assignable app roles. You must " `
                 + "assign the user a specific app role for the app to be listed " `
                 + "in the user's My Apps access panel.")
} else {
    # The app role ID 00000000-0000-0000-0000-000000000000 is the default app role
    # indicating that the app is assigned to the user, but not for any specific 
    # app role.
    $assignment = New-MgServicePrincipalAppRoleAssignedTo `
          -ServicePrincipalId $clientSp.Id `
          -ResourceId $clientSp.Id `
          -PrincipalId $user.Id `
          -AppRoleId "00000000-0000-0000-0000-000000000000"
}

Microsoft Graph API を使用して 1 人のユーザーに代わってアプリケーションに同意を付与するには、少なくともクラウド アプリケーション管理者として Graph エクスプローラーにサインインします。

次のアクセス許可に同意する必要があります。

Application.ReadWrite.All、 Directory.ReadWrite.All、DelegatedPermissionGrant.ReadWrite.All。

次の例では、リソース API によって定義された委任されたアクセス許可を、1 人のユーザーに代わってクライアント エンタープライズ アプリケーションに付与します。

この例では、リソース エンタープライズ アプリケーションはオブジェクト ID 7ea9e944-71ce-443d-811c-71e8047b557a の Microsoft Graph です。 Microsoft Graph では、委任されたアクセス許可の User.Read.All、Group.Read.All を定義します。 consentType は Principal であり、テナント内の 1 人のユーザーに代わって同意していることを示します。 クライアント エンタープライズ アプリケーションのオブジェクト ID は です b0d9b9e3-0ecf-4bfd-8dab-9273dd055a941。 ユーザーの principalId は 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5 です。

注意事項

ご注意ください。 プログラムによって付与されたアクセス許可は、レビューまたは確認の対象になりません。 それらはすぐに有効になります。

  1. テナント アプリケーションで Microsoft Graph (リソース アプリケーション) によって定義された、すべての委任されたアクセス許可を取得します。 クライアント アプリケーションに付与する委任されたアクセス許可を特定します。 この例では、委任のアクセス許可は User.Read.All と Group.Read.All です

    GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,oauth2PermissionScopes

  2. 次の要求を実行して、委任されたアクセス許可をユーザーに代わってクライアント エンタープライズ アプリケーションに付与します。

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants

Request body
{
   "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
   "consentType": "Principal",
   "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
   "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
   "scope": "User.Read.All Group.Read.All"
}

  3. 次の要求を実行して、ユーザーへの同意を付与したことを確認します。

    GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and consentType eq 'Principal'

  4. アプリをユーザーに割り当てます。 この割り当てにより、割り当てが必要な場合にユーザーがサインインできるようになり、ユーザーのマイ アプリ ポータルからアプリを使用できるようになります。 次の例では、resourceId は、ユーザーが割り当てられるクライアント アプリを表します。 ユーザーには、既定のアプリ ロールである 00000000-0000-0000-0000-000000000000 が割り当てられます。

        POST /servicePrincipals/resource-servicePrincipal-id/appRoleAssignedTo

    {
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "resourceId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "appRoleId": "00000000-0000-0000-0000-000000000000"
    }

次のステップ