代表單一使用者授與同意 - Microsoft Entra ID

發行項
10/30/2024

在本文中，您將了解如何使用 PowerShell 代表單一使用者授與同意。

當使用者對自己授與同意時，會更頻繁地發生下列事件：

建立用戶端應用程式的服務主體 (如果尚未存在)。服務主體是 Microsoft Entra 租用戶中的應用程式或服務執行個體。授與應用程式或服務的存取權與此服務主體物件相關聯。
針對應用程式需要存取權的每個 API，會依應用程式所需的需求來授與該 API 的委派權限。僅代表使用者授與存取。當該使用者登入時，委派的權限授與會授權應用程式代表使用者存取 API。
用戶端應用程式會指派給使用者。將應用程式指派給使用者，確保該應用程式列在該使用者的我的應用程式入口網站中。使用者可以檢閱和撤銷僅代表他們從 [我的應用程式] 入口網站授與的權限。

必要條件

若要代表一位使用者授與同意給應用程式，您需要：

具有特殊權限角色管理員、應用程式管理員或雲端應用程式管理員身分的使用者帳戶

開始之前，請記錄 Microsoft Entra 系統管理中心中的下列詳細資料：

您要授與同意的應用程式的應用程式識別碼。基於本文的目的，我們將會它稱為用戶端應用程式。
用戶端應用程式所需的 API 權限。找出 API 的應用程式識別碼，以及權限識別碼或宣告值。
代表其授與存取權之使用者的使用者名稱或物件識別碼。

在此範例中，我們將使用 Microsoft Graph PowerShell 來代表單一使用者授與同意。用戶端應用程式為 Microsoft Graph Explorer，而且我們會將存取權授與 Microsoft Graph API。

若要使用 Microsoft Graph PowerShell 僅代表使用者將同意授與應用程式，您必須以不低於雲端應用程式管理員的身分登入。

# 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 portal.")
} 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 僅代表使用者將同意授與應用程式，您必須以不低於雲端應用程式管理員的身分登入 Graph 總管。

您必須同意下列權限：

在下列範例中，您將僅代表單一使用者將資源 API 所定義的委派權限授與用戶端企業應用程式。

在範例中，資源企業應用程式是物件識別碼 aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb 的 Microsoft Graph。 Microsoft Graph 會定義委派的權限 User.Read.All 和 Group.Read.All。 consentType 是 Principal，表示您代表租用戶中的所有使用者同意。用戶端企業應用程式的物件識別碼為 aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb。使用者的 principalId 是 aaaaaaaa-bbbb-cccc-1111-222222222222。

警告

請務必小心！以程式設計方式授與的權限不受限於檢閱或確認。其會立即生效。

擷取租用戶應用程式中 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
```

執行下列要求，僅代表使用者將委派的權限授與用戶端企業應用程式。

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

Request body
{
   "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
   "consentType": "Principal",
   "resourceId": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
   "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
   "scope": "User.Read.All Group.Read.All"
}

執行下列要求，確認您已獲授與使用者同意。

GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '00001111-aaaa-2222-bbbb-3333cccc4444' and consentType eq 'Principal'

請將應用程式指派給使用者。此指派確保使用者可以在需要指派時登入，並確保應用程式可透過使用者的「我的應用程式」入口網站取得。在下列範例中， resourceId代表要指派使用者的用戶端應用程式。使用者獲指派為預設應用程式角色 00000000-0000-0000-0000-000000000000。
```
    POST /servicePrincipals/resource-servicePrincipal-id/appRoleAssignedTo

    {
    "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "resourceId": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
    "appRoleId": "00000000-0000-0000-0000-000000000000"
    }
```

共用方式為

必要條件

下一步

意見反應

其他資源