Configurar o proxy de aplicativo do Microsoft Entra usando APIs do Microsoft Graph

O proxy de aplicativo do Microsoft Entra fornece acesso remoto seguro e SSO (logon único) para aplicativos Web locais. Ele permite que os usuários acessem seus aplicativos locais por meio de uma URL externa, do portal Meus Aplicativos ou de outros portais de aplicativos internos.

Neste tutorial, você aprenderá a configurar o proxy de aplicativo do Microsoft Entra usando APIs do Microsoft Graph.

Importante

No momento, as operações de API específicas do beta proxy do aplicativo estão disponíveis apenas no ponto de extremidade.

Pré-requisitos

  • Instale um conector e conclua os pré-requisitos do proxy de aplicativo para que os conectores possam se comunicar com os serviços do Microsoft Entra.
  • Entre em um cliente de API, como o Graph Explorer, com uma conta que tenha pelo menos a função de Administrador de Aplicativos de Nuvem.
  • Conceda a si mesmo a permissão delegada do Microsoft Graph Directory.ReadWrite.All .
  • Tenha um usuário de teste para atribuir ao aplicativo.

Etapa 1: Criar um aplicativo personalizado

Para configurar o proxy de aplicativo, primeiro crie um aplicativo personalizado e, em seguida, atualize as configurações de proxy de aplicativo na propriedade onPremisesPublishing do aplicativo. Neste tutorial, use um modelo de aplicativo para criar uma instância de um aplicativo personalizado e uma entidade de serviço em seu locatário. A ID do modelo para um aplicativo personalizado é 8adf8e6e-67b2-4cf2-a259-e3dc5476c621, que você pode descobrir executando a seguinte consulta: GET https://graph.microsoft.com/v1.0/applicationTemplates?$filter=displayName eq 'Custom'.

Na resposta, registre a ID da entidade de serviço e dos objetos de aplicativo e o valor de appId para uso posterior no tutorial.

Solicitação

POST https://graph.microsoft.com/v1.0/applicationTemplates/8adf8e6e-67b2-4cf2-a259-e3dc5476c621/instantiate
Content-type: application/json

{
  "displayName": "Contoso IWA App"
}

Resposta

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.applicationServicePrincipal",
    "application": {
        "id": "bf21f7e9-9d25-4da2-82ab-7fdd85049f83",
        "appId": "32977d3b-ee0e-4614-9f50-f583a07842d2",
        "applicationTemplateId": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",
        "createdDateTime": "2024-02-22T16:48:09Z",
        "deletedDateTime": null,
        "displayName": "Contoso IWA App",
        "description": null,
        "groupMembershipClaims": null,
        "identifierUris": [],
        "isFallbackPublicClient": false,
        "signInAudience": "AzureADMyOrg",
        "tags": [],
        "tokenEncryptionKeyId": null,
        "defaultRedirectUri": null,
        "samlMetadataUrl": null,
        "optionalClaims": null,
        "addIns": [],
        "api": {
            "acceptMappedClaims": null,
            "knownClientApplications": [],
            "requestedAccessTokenVersion": null,
            "oauth2PermissionScopes": [
                {
                    "adminConsentDescription": "Allow the application to access Contoso IWA App on behalf of the signed-in user.",
                    "adminConsentDisplayName": "Access Contoso IWA App",
                    "id": "5cda2e1e-d9fd-4f69-b981-48fbc8a16be1",
                    "isEnabled": true,
                    "type": "User",
                    "userConsentDescription": "Allow the application to access Contoso IWA App on your behalf.",
                    "userConsentDisplayName": "Access Contoso IWA App",
                    "value": "user_impersonation"
                }
            ],
            "preAuthorizedApplications": []
        },
        "appRoles": [
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "displayName": "User",
                "id": "18d14569-c3bd-439b-9a66-3a2aee01d14f",
                "isEnabled": true,
                "description": "User",
                "value": null,
                "origin": "Application"
            },
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "displayName": "msiam_access",
                "id": "b9632174-c057-4f7e-951b-be3adc52bfe6",
                "isEnabled": true,
                "description": "msiam_access",
                "value": null,
                "origin": "Application"
            }
        ],
        "info": {
            "logoUrl": null,
            "marketingUrl": null,
            "privacyStatementUrl": null,
            "supportUrl": null,
            "termsOfServiceUrl": null
        },
        "keyCredentials": [],
        "parentalControlSettings": {
            "countriesBlockedForMinors": [],
            "legalAgeGroupRule": "Allow"
        },
        "passwordCredentials": [],
        "publicClient": {
            "redirectUris": []
        },
        "requiredResourceAccess": [],
        "verifiedPublisher": {
            "displayName": null,
            "verifiedPublisherId": null,
            "addedDateTime": null
        },
        "web": {
            "homePageUrl": "https://account.activedirectory.windowsazure.com:444/applications/default.aspx?metadata=customappsso|ISV9.1|primary|z",
            "redirectUris": [],
            "logoutUrl": null
        }
    },
    "servicePrincipal": {
        "id": "a8cac399-cde5-4516-a674-819503c61313",
        "deletedDateTime": null,
        "accountEnabled": true,
        "appId": "32977d3b-ee0e-4614-9f50-f583a07842d2",
        "applicationTemplateId": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",
        "appDisplayName": "Contoso IWA App",
        "alternativeNames": [],
        "appOwnerOrganizationId": "38d49456-54d4-455d-a8d6-c383c71e0a6d",
        "displayName": "Contoso IWA App",
        "appRoleAssignmentRequired": true,
        "loginUrl": null,
        "logoutUrl": null,
        "homepage": "https://account.activedirectory.windowsazure.com:444/applications/default.aspx?metadata=customappsso|ISV9.1|primary|z",
        "notificationEmailAddresses": [],
        "preferredSingleSignOnMode": null,
        "preferredTokenSigningKeyThumbprint": null,
        "replyUrls": [],
        "servicePrincipalNames": [
            "32977d3b-ee0e-4614-9f50-f583a07842d2"
        ],
        "servicePrincipalType": "Application",
        "tags": [
            "WindowsAzureActiveDirectoryCustomSingleSignOnApplication",
            "WindowsAzureActiveDirectoryIntegratedApp"
        ],
        "tokenEncryptionKeyId": null,
        "samlSingleSignOnSettings": null,
        "addIns": [],
        "appRoles": [
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "displayName": "User",
                "id": "18d14569-c3bd-439b-9a66-3a2aee01d14f",
                "isEnabled": true,
                "description": "User",
                "value": null,
                "origin": "Application"
            },
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "displayName": "msiam_access",
                "id": "b9632174-c057-4f7e-951b-be3adc52bfe6",
                "isEnabled": true,
                "description": "msiam_access",
                "value": null,
                "origin": "Application"
            }
        ],
        "info": {
            "logoUrl": null,
            "marketingUrl": null,
            "privacyStatementUrl": null,
            "supportUrl": null,
            "termsOfServiceUrl": null
        },
        "keyCredentials": [],
        "oauth2PermissionScopes": [
            {
                "adminConsentDescription": "Allow the application to access Contoso IWA App on behalf of the signed-in user.",
                "adminConsentDisplayName": "Access Contoso IWA App",
                "id": "5cda2e1e-d9fd-4f69-b981-48fbc8a16be1",
                "isEnabled": true,
                "type": "User",
                "userConsentDescription": "Allow the application to access Contoso IWA App on your behalf.",
                "userConsentDisplayName": "Access Contoso IWA App",
                "value": "user_impersonation"
            }
        ],
        "passwordCredentials": [],
        "verifiedPublisher": {
            "displayName": null,
            "verifiedPublisherId": null,
            "addedDateTime": null
        }
    }
}

Etapa 2: Configurar o proxy de aplicativo

Para o aplicativo que você criou na Etapa 1, configure os URIs para o aplicativo. Suponha que a URL interna do aplicativo seja https://contosoiwaapp.com e o domínio padrão da URL externa seja https://contosoiwaapp-contoso.msappproxy.net. Adicione o valor de URL externo às propriedades identifierUris, web>redirectUris e web>homePageUrl .

Além disso, configure a propriedade onPremisesPublishing para definir as URLs internas e externas e outras propriedades, conforme necessário. Esta propriedade só está disponível e beta não pode ser configurada até que você configure os URIs.

Etapa 2.1: Configurar os URIs

A solicitação a seguir usa o valor de appId para a propriedade identifierUris . Você também pode usar qualquer outro identificador que corresponda ao formato de URI da ID do aplicativo esperado pelo Microsoft Entra ID. A solicitação retorna uma 204 No content resposta.

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

{
    "identifierUris": [
        "api://32977d3b-ee0e-4614-9f50-f583a07842d2"
    ],
    "web": {
        "redirectUris": [
            "https://contosoiwaapp-contoso.msappproxy.net"
        ],
        "homePageUrl": "https://contosoiwaapp-contoso.msappproxy.net"
    }
}

Etapa 2.2: Configurar a propriedade onPremisesPublishing

A solicitação retorna uma 204 No content resposta.

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

{
    "onPremisesPublishing": {
        "externalAuthenticationType": "aadPreAuthentication",
        "internalUrl": "https://contosoiwaapp.com",
        "externalUrl": "https://contosoiwaapp-contoso.msappproxy.net",
        "isHttpOnlyCookieEnabled": true,
        "isOnPremPublishingEnabled": true,
        "isPersistentCookieEnabled": true,
        "isSecureCookieEnabled": true,
        "isStateSessionEnabled": true,
        "isTranslateHostHeaderEnabled": true,
        "isTranslateLinksInBodyEnabled": true
    }
}

Etapa 3: atribuir um grupo de conectores ao aplicativo

Etapa 3.1: obter conectores

Identifique o conector que você deseja atribuir ao grupo de conectores. Registre sua ID.

Solicitação

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

Resposta

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#onPremisesPublishingProfiles('applicationProxy')/connectors",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET onPremisesPublishingProfiles('<key>')/connectors?$select=externalIp,machineName",
    "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"
    }
  ]
}

Etapa 3.2: Criar um connectorGroup

Crie um connectorGroup nomeado IWA Demo Connector Group para o aplicativo. Registre sua ID.

Solicitação

POST https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectorGroups
Content-type: application/json

{
  "name": "IWA Demo Connector Group"
}

Resposta

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

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

Etapa 3.3: Atribuir um conector ao connectorGroup

A solicitação retorna uma 204 No content resposta.

POST https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectors/f2cab422-a1c8-4d70-a47e-2cb297a2e051/memberOf/$ref
Content-type: application/json

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

Etapa 3.4: Atribuir o aplicativo ao connectorGroup

A solicitação retorna uma 204 No content resposta.

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

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

Etapa 4: Configurar logon único (SSO)

Nesta etapa, você configura as propriedades onPremisesPublishing > singleSignOnSettings e onPremisesPublishing > singleSignOnMode para o aplicativo.

Opção 1: configurar SSO baseado em IWA

A solicitação a seguir mostra como configurar a Autenticação Integrada do Windows (IWA) para o aplicativo. A solicitação retorna uma 204 No content resposta.

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

Opção 2: configurar o SSO baseado em cabeçalho

A solicitação a seguir mostra como configurar o SSO baseado em cabeçalho para o aplicativo. Nesse modo, o valor da propriedade singleSignOnMode pode ser aadHeaderBased, pingHeaderBased, ou oAuthToken. A solicitação retorna uma 204 No content resposta.

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

{
  "onPremisesPublishing": {
    "singleSignOnSettings": {
      "kerberosSignOnSettings": {},
      "singleSignOnMode": "aadHeaderBased"
    }
  } 
}

Etapa 5: atribuir um usuário ao aplicativo

Você deseja atribuir um usuário ao aplicativo. Na entidade de serviço que você criou na Etapa 1, registre a ID da função de Usuário padrão definida na propriedade appRoles . Esse valor é 18d14569-c3bd-439b-9a66-3a2aee01d14f.

No corpo da solicitação, forneça os seguintes valores:

  • principalId - A ID da conta de usuário que você criou.
  • appRoleId - A ID da função de aplicativo padrão User que você recuperou da entidade de serviço.
  • resourceId - A ID da entidade de serviço.

Solicitação

POST https://graph.microsoft.com/beta/servicePrincipals/a8cac399-cde5-4516-a674-819503c61313/appRoleAssignments
Content-type: application/json

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

Resposta

HTTP/1.1 200 OK
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": "MyTestUser1",
  "principalId": "2fe96d23-5dc6-4f35-8222-0426a8c115c8",
  "principalType": "User",
  "resourceDisplayName": "Contoso IWA App",
  "resourceId": "a8cac399-cde5-4516-a674-819503c61313"
}

Etapa 6: Testar o acesso ao aplicativo

Teste o aplicativo visitando o externalUrl configurado para o aplicativo em seu navegador e, em seguida, entre com o usuário de teste. Você deve ser capaz de entrar no aplicativo e acessar o aplicativo.

Etapa 7: Limpar recursos

Nesta etapa, remova os recursos que você criou e não precisa mais.

Excluir a conta de usuário

A solicitação retorna uma 204 No content resposta.

DELETE https://graph.microsoft.com/v1.0/users/4628e7df-dff3-407c-a08f-75f08c0806dc

Excluir o aplicativo

Quando você exclui o aplicativo, a entidade de serviço em seu locatário também é excluída. Esta solicitação retorna uma 204 No content resposta.

DELETE https://graph.microsoft.com/v1.0/applications/bf21f7e9-9d25-4da2-82ab-7fdd85049f83

Excluir o grupo de conectores

A solicitação retorna uma 204 No content resposta.

DELETE https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectorGroups/3e6f4c35-a04b-4d03-b98a-66fff89b72e6