使用 Microsoft Graph API 自动配置应用程序代理Automate the configuration of Application Proxy using the Microsoft Graph API

在本文中,您将了解如何为应用程序创建和配置 Azure Active Directory (Azure AD) 应用程序代理In this article, you'll learn how to create and configure Azure Active Directory (Azure AD) Application Proxy for an application. 应用程序代理提供了对本地 web 应用程序的安全远程访问和单一登录。Application Proxy provides secure remote access and single sign-on to on-premises web applications. 为应用程序配置应用程序代理后,用户可以通过外部 URL、"我的应用程序" 门户或其他内部应用程序门户访问其本地应用程序。After configuring Application Proxy for an application, users can access their on-premises applications through an external URL, the My Apps portal, or other internal application portals.

本文假定您已经安装了连接器并完成了应用程序代理的 先决条件 ,以便连接器可以与 Azure AD 服务进行通信。This article assumes you have already installed a connector and completed the prerequisites for Application Proxy so that connectors can communicate with Azure AD services.

请确保你具有相应的权限来调用以下 API。Make sure you have the corresponding permissions to call the following APIs.

资源类型Resource type 方法Method
applicationsapplications
onPremisesPublishingonPremisesPublishing
创建应用程序Create application
更新应用程序Update application
向 connectorGroup 添加应用程序Add application to connectorGroup
连接器connector 获取连接器Get connectors
connectorGroupconnectorGroup Create connectorGroupCreate connectorGroup
Add connector to connectorGroupAdd connector to connectorGroup
servicePrincipalsservicePrincipals 创建 servicePrincipalCreate servicePrincipal
更新 servicePrincipalUpdate servicePrincipal
创建 appRoleAssignmentsCreate appRoleAssignments

备注

本文中所示的请求使用示例值。The requests shown in this article use sample values. 你将需要更新这些。You will need update these. 显示的响应对象可能还会缩短可读性。The response objects shown might also be shortened for readability.

步骤1:创建应用程序Step 1: Create an application

  1. 启动 Microsoft Graph 浏览器Start Microsoft Graph Explorer.
  2. 选择 "使用 Microsoft 登录" ,并使用 Azure AD 全局管理员或应用程序管理员凭据登录。Select Sign-in with Microsoft and sign in using an Azure AD global administrator or App Admin credentials.
  3. 成功登录后,将在左窗格中看到用户帐户详细信息。Upon successful sign in, you'll see the user account details in the left pane.

创建应用程序Create an application

若要使用 API 为应用程序配置应用程序代理,请创建应用程序,将服务主体添加到应用中,然后更新应用程序的 onPremisesPublishing 属性以配置应用程序代理设置。To configure Application Proxy for an app using the API, you create an application, add a service principal to the app, and then update the application's onPremisesPublishing property to configure the App Proxy settings. 在创建应用程序时,将应用程序的 signInAudience 设置为 "AzureADMyOrg"。When creating the application, set the application's signInAudience to "AzureADMyOrg".

请求Request

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

{
  "displayName": "Contoso IWA App",
  "signInAudience":"AzureADMyOrg"
}

响应Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#applications/$entity",
  "id": "bf21f7e9-9d25-4da2-82ab-7fdd85049f83",
  "deletedDateTime": null,
  "addIns": [],
  "appId": "d7fbfe28-c60e-46d2-8335-841923950d3b",
  "applicationTemplateId": null,
  "identifierUris": [],
  "createdDateTime": "2020-08-11T21:07:47.5919755Z",
  "description": null,
  "displayName": "Contoso IWA App",
  "isAuthorizationServiceEnabled": false,
  "isDeviceOnlyAuthSupported": null,
  "isFallbackPublicClient": null,
  "groupMembershipClaims": null,
  "notes": null,
  "optionalClaims": null,
  "orgRestrictions": [],
  "publisherDomain": "f128.info",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "tags": [],
  "tokenEncryptionKeyId": null,
  "uniqueName": null,
  "verifiedPublisher": {
      "displayName": null,
      "verifiedPublisherId": null,
      "addedDateTime": null
  },
}

检索应用程序对象 ID 和 appIdRetrieve the application object ID and appId

使用上一次调用的响应检索并保存应用程序对象 ID 和应用程序 ID。Use the response from the previous call to retrieve and save the application object ID and app ID.

"application": {
  "id": "bf21f7e9-9d25-4da2-82ab-7fdd85049f83",
  "appId": "d7fbfe28-c60e-46d2-8335-841923950d3b"
}

为应用程序创建一个 servicePrincipal 并添加所需的标记Create a servicePrincipal for the application and add required tags

使用 appId 为应用程序创建服务主体。Use the appId to create a service principal for the application. 然后添加为应用配置应用程序代理所需的标记。Then add the tags required for configuring Application Proxy for an app.

请求Request

POST https://graph.microsoft.com/beta/serviceprincipals
Content-type: appplication/json

{
  "appId":"d7fbfe28-c60e-46d2-8335-841923950d3b",
  "tags": [
    "WindowsAzureActiveDirectoryIntegratedApp",
    "WindowsAzureActiveDirectoryOnPremApp"
  ]
}

响应Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals/$entity",
  "id": "a8cac399-cde5-4516-a674-819503c61313",
  "deletedDateTime": null,
  "accountEnabled": true,
  "alternativeNames": [],
  "createdDateTime": null,
  "deviceManagementAppType": null,
  "appDescription": null,
  "appDisplayName": "Contoso IWA App",
  "appId": "d7fbfe28-c60e-46d2-8335-841923950d3b",
  "applicationTemplateId": null,
  "appOwnerOrganizationId": "7918d4b5-0442-4a97-be2d-36f9f9962ece",
  "appRoleAssignmentRequired": false,
  "description": null,
  "displayName": "vtestapi2",
  "errorUrl": null,
  "homepage": null,
  "isAuthorizationServiceEnabled": false,
  "loginUrl": null,
  "logoutUrl": null,
  "notes": null,
  "notificationEmailAddresses": [],
  "preferredSingleSignOnMode": null,
  "preferredTokenSigningKeyEndDateTime": null,
  "preferredTokenSigningKeyThumbprint": null,
  "publisherName": "f/128 Photography",
  "replyUrls": [],
  "samlMetadataUrl": null,
  "samlSingleSignOnSettings": null,
  "servicePrincipalNames": [
      "b92b92d4-3874-46a5-b715-a00ea01cff93"
  ],
  "servicePrincipalType": "Application",
}

步骤2:配置应用程序代理属性Step 2: Configure Application Proxy properties

设置 onPremisesPublishing 配置Set the onPremisesPublishing configuration

使用上一步中的 application 对象 ID 为应用程序配置应用程序代理,并将 onPremisesPublishing 属性更新为所需的配置。Use the application object ID from the previous step to configure Application Proxy for the app and update the onPremisesPublishing property to the desired configuration. 在此示例中,您使用的是内部 URL 的应用程序: https://contosoiwaapp.com 并使用外部 url 的默认域: https://contosoiwaapp-contoso.msappproxy.netIn this example, you're using an app with the internal URL: https://contosoiwaapp.com and using the default domain for the external URL: https://contosoiwaapp-contoso.msappproxy.net.

请求Request

PATCH https://graph.microsoft.com/beta/applications/bf21f7e9-9d25-4da2-82ab-7fdd85049f83
Content-type: appplication/json

{
    "onPremisesPublishing": {
        "externalAuthenticationType": "aadPreAuthentication",
        "internalUrl": "https://contosoiwaapp.com",
        "externalUrl": "https://contosoiwaapp-contoso.msappproxy.net"
    }
}

响应Response

HTTP/1.1 204 No content

完成应用程序的配置Complete the configuration of the application

将应用程序的 " redirectUri"、" identifierUri" 和 " HomepageUrl " 属性更新为 onPremisesPublishing 属性中配置的外部 UR。Update the application's redirectUri, identifierUri, and homepageUrl properties to the external UR configured in the onPremisesPublishing property. 然后,将 implicitGrantSettings 更新为 true 针对 enabledTokenIssuancefalse enabledAccessTokenIssuanceThen update implicitGrantSettings to true for enabledTokenIssuance and false for enabledAccessTokenIssuance.

请求Request

PATCH https://graph.microsoft.com/beta/applications/bf21f7e9-9d25-4da2-82ab-7fdd85049f83
Content-type: appplication/json

{
  "identifierUris": ["https://contosoiwaapp-contoso.msappproxy.net"],
  "web": {
    "redirectUris": ["https://contosoiwaapp-contoso.msappproxy.net"],
    "homePageUrl": "https://contosoiwaapp-contoso.msappproxy.net",
    "implicitGrantSettings": {
      "enableIdTokenIssuance": true,
      "enableAccessTokenIssuance": false
    }
  }
}

响应Response

HTTP/1.1 204 No content

步骤3:将连接器组分配给应用程序Step 3: Assign the connector group to the application

获取连接器Get connectors

列出连接器并使用响应来检索和保存连接器对象 ID。List the connectors and use the response to retrieve and save the connector object ID. 连接器对象 ID 将用于将连接器分配给连接器组。The connector object ID will be used to assign the connector to a connector group.

请求Request

GET https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectors

响应Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#connectors",
    "value": [
        {
            "id": "d2b1e8e8-8511-49d6-a4ba-323cb083fbb0",
            "machineName": "connectorA.redmond.contoso.com"",
            "externalIp": "131.137.147.164",
            "status": "active"
        },
        {
            "id": "f2cab422-a1c8-4d70-a47e-2cb297a2e051",
            "machineName": "connectorB.contoso.com"",
            "externalIp": "68.0.191.210",
            "status": "active"
        },
        {
            "id": "8555cc3c-5c8b-48a8-a8b2-5e97c32ef907",
            "machineName": "connectorC.contoso.com",
            "externalIp": "40.78.66.161",
            "status": "active"
        }
    ]
}

创建 connectorGroupCreate a connectorGroup

在此示例中,创建了一个用于应用程序的名为 "IWA Demo Connector Group" 的新 connectorGroup。For this example, a new connectorGroup is created named "IWA Demo Connector Group" that is used for the application. 如果您的连接器已分配给相应的 connectorGroup,也可以跳过此步骤。You can also skip this step if your connector is already assigned to the appropriate connectorGroup. 检索并保存要在下一步中使用的 connectorGroup 对象 ID。Retrieve and save the connectorGroup object ID to use in the next step.

请求Request

POST https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectorGroups

Content-type: application/json
{
   "name": "IWA Demo Connector Group"
}

响应Response

HTTP/1.1 201
Content-type: connectorGroup/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#connectorGroups/$entity",
    "id": "3e6f4c35-a04b-4d03-b98a-66fff89b72e6",
    "name": "IWA Demo Connector Group",
    "connectorGroupType": "applicationProxy",
    "isDefault": false
}

将连接器分配给 connectorGroupAssign a connector to the connectorGroup

请求Request

POST https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectors/8555cc3c-5c8b-48a8-a8b2-5e97c32ef907/memberOf/$ref

Content-type: application/json
{
  "@odata.id":"https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectorGroups/3e6f4c35-a04b-4d03-b98a-66fff89b72e6"
}

响应Response

HTTP/1.1 204 No content

将应用程序分配给 connectorGroupAssign the application to the connectorGroup

请求Request

PUT https://graph.microsoft.com/beta/applications/bf21f7e9-9d25-4da2-82ab-7fdd85049f83/connectorGroup/$ref
Content-type: application/json

{
"@odata.id":"https://graph.microsoft.com/onPremisesPublishingProfiles/applicationproxy/connectorGroups/3e6f4c35-a04b-4d03-b98a-66fff89b72e6"
}

响应Response

HTTP/1.1 204 No content

步骤4:配置单一登录Step 4: Configure single sign-on

此应用程序使用集成的 Windows 身份验证 (IWA) 。This application uses Integrated Windows Authentication (IWA). 若要配置 IWA,请在 singleSignOnSettings 资源类型中设置单一登录属性。To configure IWA, set the single sign-on properties in the singleSignOnSettings resource type.

请求Request

PATCH https://graph.microsoft.com/beta/applications/bf21f7e9-9d25-4da2-82ab-7fdd85049f83
Content-type: appplication/json

{
   "onPremisesPublishing": {
      "singleSignOnSettings": {
         "kerberosSignOnSettings": {
            "kerberosServicePrincipalName": "HTTP/iwademo.contoso.com",
        "kerberosSignOnMappingAttributeType": "userPrincipalName"
         },
         "singleSignOnMode": "onPremisesKerberos"
      }
   }
}

响应Response

HTTP/1.1 204 No content

第 5 步:分配用户Step 5: Assign users

检索应用程序的 appRoleRetrieve appRole for the applicaiton

请求Request

GET https://graph.microsoft.com/beta/servicePrincipals/a8cac399-cde5-4516-a674-819503c61313/appRoles

响应Response

HTTP/1.1 200
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('a8cac399-cde5-4516-a674-819503c61313')/appRoles",
    "value": [
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "User",
            "displayName": "User",
            "id": "18d14569-c3bd-439b-9a66-3a2aee01d14f",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "msiam_access",
            "displayName": "msiam_access",
            "id": "b9632174-c057-4f7e-951b-be3adc52bfe6",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        }
    ]
}

使用上一次调用中的响应检索并保存 appRole ID 以用于下一步。Use the response from the previous call to retrieve and save the appRole ID to use for the next step.

      {
            "description": "User",
            "displayName": "User",
            "id": "18d14569-c3bd-439b-9a66-3a2aee01d14f"
        }

向应用程序分配用户和组Assign users and groups to the application

使用以下属性将用户分配给应用程序。Use the following properties to assign a user to the application.

属性Property 说明Description IDID
principalIdprincipalId 将分配给应用程序的用户的用户 IDUser ID of the user that will be assigned to the app 2fe96d23-5dc6-4f35-8222-0426a8c115c82fe96d23-5dc6-4f35-8222-0426a8c115c8
principalTypeprincipalType 用户类型Type of user 用户User
appRoleIdappRoleId 应用程序的默认应用程序角色的应用程序角色 IDThe App role ID of the default app role of the app 18d14569-c3bd-439b-9a66-3a2aee01d14f18d14569-c3bd-439b-9a66-3a2aee01d14f
resourceIdresourceId 应用程序的 servicePrincipal IDThe servicePrincipal ID of the app a8cac399-cde5-4516-a674-819503c61313a8cac399-cde5-4516-a674-819503c61313

请求Request

POST https://graph.microsoft.com/beta/servicePrincipals/b00c693f-9658-4c06-bd1b-c402c4653dea/appRoleAssignments

Content-type: appRoleAssignments/json

{
  "principalId": "2fe96d23-5dc6-4f35-8222-0426a8c115c8",
  "principalType": "User",
  "appRoleId":"18d14569-c3bd-439b-9a66-3a2aee01d14f",
  "resourceId":"a8cac399-cde5-4516-a674-819503c61313"
}

响应Response

HTTP/1.1 200
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#appRoleAssignments/$entity",
    "id": "I23pL8ZdNU-CIgQmqMEVyLJ0E6fx0ixEo92az8MnhtU",
    "creationTimestamp": "2020-06-09T00:06:07.5129268Z",
    "appRoleId": "18d14569-c3bd-439b-9a66-3a2aee01d14f",
    "principalDisplayName": "Jean Green",
    "principalId": "2fe96d23-5dc6-4f35-8222-0426a8c115c8",
    "principalType": "User",
    "resourceDisplayName": "Contoso IWA App",
    "resourceId": "a8cac399-cde5-4516-a674-819503c61313"
}

有关详细信息,请参阅 appRoleAssignment 资源类型。For more information, see appRoleAssignment resource type.

其他步骤Additional steps