Compartilhar via


Configurar o proxy de aplicações do Microsoft Entra com as APIs do Microsoft Graph

O proxy de aplicações do Microsoft Entra fornece acesso remoto seguro e início de sessão único (SSO) a aplicações Web no local. Permite que os utilizadores acedam às respetivas aplicações no local através de um URL externo, do portal As Minhas Aplicações ou de outros portais de aplicações internos.

Neste tutorial, vai aprender a Configurar o proxy de aplicações do Microsoft Entra com as APIs do Microsoft Graph.

Importante

As operações de API específicas do proxy de aplicações estão atualmente disponíveis apenas no beta ponto final.

Pré-requisitos

  • Instale um conector e conclua os pré-requisitos do proxy de aplicações para que os conectores possam comunicar com os serviços do Microsoft Entra.
  • Inicie sessão num cliente de API, como o Graph Explorer , com uma conta que tenha, pelo menos, a função Administrador de Aplicações na Cloud.
  • Conceda a si mesmo a permissão delegada do Microsoft Graph Directory.ReadWrite.All .
  • Ter um utilizador de teste para atribuir à aplicação.

Passo 1: criar uma aplicação personalizada

Para configurar o proxy de aplicações, crie primeiro uma aplicação personalizada e, em seguida, atualize as definições do proxy de aplicações na propriedade onPremisesPublishing da aplicação . Neste tutorial, vai utilizar um modelo de aplicação para criar uma instância de uma aplicação personalizada e principal de serviço no seu inquilino. O ID de modelo de uma aplicação personalizada é 8adf8e6e-67b2-4cf2-a259-e3dc5476c621, que pode descobrir ao executar a seguinte consulta: GET https://graph.microsoft.com/v1.0/applicationTemplates?$filter=displayName eq "Custom".

Na resposta, registe o ID do principal de serviço e os objetos da aplicação e o valor de appId para utilizar mais tarde 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
        }
    }
}

Passo 2: Configurar o proxy de aplicações

Para a aplicação que criou no Passo 1, configure os URIs para a aplicação. Suponha que o URL interno da aplicação é https://contosoiwaapp.com e que o domínio predefinido para o URL externo é 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 os URLs internos e externos e outras propriedades conforme necessário. Esta propriedade só está disponível no beta e não pode ser configurada até configurar os URIs.

Passo 2.1: Configurar os URIs

O pedido seguinte utiliza o valor de appId para a propriedade identifierUris . Também pode utilizar qualquer outro identificador que corresponda ao formato de URI do ID da aplicação esperado pelo ID do Microsoft Entra. O pedido devolve 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"
    }
}

Passo 2.2: Configurar a propriedade onPremisesPublishing

O pedido devolve 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
    }
}

Passo 3: atribuir um grupo de conectores à aplicação

Passo 3.1: Obter conectores

Identifique o conector que pretende atribuir ao grupo de conectores. Grave o respetivo 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"
    }
  ]
}

Passo 3.2: Criar um connectorGroup

Crie um connectorGroup com o nome IWA Demo Connector Group para a aplicação. Grave o respetivo 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
}

Passo 3.3: Atribuir um conector ao connectorGroup

O pedido devolve 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"
}

Passo 3.4: Atribuir a aplicação ao connectorGroup

O pedido devolve 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"
}

Passo 4: Configurar o início de sessão único (SSO)

Neste passo, vai configurar as propriedades onPremisesPublishing > singleSignOnSettings e onPremisesPublishing > singleSignOnMode para a aplicação.

Opção 1: Configurar o SSO baseado no IWA

O pedido seguinte mostra como configurar a Autenticação Integrada do Windows (IWA) para a aplicação. O pedido devolve 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çalhos

O pedido seguinte mostra como configurar o SSO baseado em cabeçalhos para a aplicação. Neste modo, o valor da propriedade singleSignOnMode pode ser aadHeaderBased, pingHeaderBasedou oAuthToken. O pedido devolve 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"
    }
  } 
}

Passo 5: atribuir um utilizador à aplicação

Quer atribuir um utilizador à aplicação. No principal de serviço que criou no Passo 1, registe o ID da função de Utilizador predefinida definida na propriedade appRoles . Este valor é 18d14569-c3bd-439b-9a66-3a2aee01d14f.

No corpo do pedido, forneça os seguintes valores:

  • principalId – o ID da conta de utilizador que criou.
  • appRoleId – o ID da função de aplicação predefinida User que obteve do principal de serviço.
  • resourceId – o ID do principal 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"
}

Passo 6: testar o acesso à aplicação

Teste a aplicação visitando externalUrl configurado para a aplicação no browser e, em seguida, inicie sessão com o utilizador de teste. Deverá conseguir iniciar sessão na aplicação e aceder à aplicação.

Etapa 7: Limpar recursos

Neste passo, remova os recursos que criou e já não precisa.

Excluir a conta de usuário

O pedido devolve uma 204 No content resposta.

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

Excluir o aplicativo

Quando elimina a aplicação, o principal de serviço no seu inquilino também é eliminado. Este pedido devolve uma 204 No content resposta.

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

Eliminar o grupo de conectores

O pedido devolve uma 204 No content resposta.

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