Compartir a través de


Configuración del proxy de aplicación de Microsoft Entra mediante las API de Microsoft Graph

El proxy de la aplicación Microsoft Entra proporciona acceso remoto seguro y inicio de sesión único (SSO) a aplicaciones web locales. Permite a los usuarios acceder a sus aplicaciones locales a través de una dirección URL externa, el portal Mis aplicaciones u otros portales de aplicaciones internos.

En este tutorial, aprenderá a configurar el proxy de la aplicación Microsoft Entra mediante las API de Microsoft Graph.

Importante

Las operaciones de API específicas del proxy de la aplicación solo están disponibles actualmente en el punto de beta conexión.

Requisitos previos

  • Instale un conector y complete los requisitos previos para el proxy de aplicación para que los conectores puedan comunicarse con los servicios de Microsoft Entra.
  • Inicie sesión en un cliente de API, como Graph Explorer , con una cuenta que tenga al menos el rol Administrador de aplicaciones en la nube.
  • Concédete el permiso delegado de Microsoft Graph Directory.ReadWrite.All .
  • Hacer que un usuario de prueba se asigne a la aplicación.

Paso 1: Crear una aplicación personalizada

Para configurar el proxy de aplicación, primero cree una aplicación personalizada y, a continuación, actualice la configuración del proxy de aplicación en la propiedad onPremisesPublishing de la aplicación. En este tutorial, usará una plantilla de aplicación para crear una instancia de una aplicación personalizada y una entidad de servicio en el inquilino. El identificador de plantilla de una aplicación personalizada es 8adf8e6e-67b2-4cf2-a259-e3dc5476c621, que puede detectar mediante la ejecución de la siguiente consulta: GET https://graph.microsoft.com/v1.0/applicationTemplates?$filter=displayName eq 'Custom'.

En la respuesta, registre el identificador de la entidad de servicio y los objetos de aplicación, y el valor de appId para usarlo más adelante en el tutorial.

Solicitud

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

{
  "displayName": "Contoso IWA App"
}

Respuesta

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

Paso 2: Configuración del proxy de aplicación

Para la aplicación que creó en el paso 1, configure los URI para la aplicación. Supongamos que la dirección URL interna de la aplicación es https://contosoiwaapp.com y el dominio predeterminado para la dirección URL externa es https://contosoiwaapp-contoso.msappproxy.net. Agregue el valor de dirección URL externa a las propiedades identifierUris, web>redirectUris y web>homePageUrl .

Además, configure la propiedad onPremisesPublishing para establecer las direcciones URL internas y externas, y otras propiedades según sea necesario. Esta propiedad solo está disponible en beta y no se puede configurar hasta que configure los URI.

Paso 2.1: Configuración de los URI

En la solicitud siguiente se usa el valor de appId para la propiedad identifierUris . También puede usar cualquier otro identificador que coincida con el formato uri de id. de aplicación esperado por Microsoft Entra ID. La solicitud devuelve una 204 No content respuesta.

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

Paso 2.2: Configurar la propiedad onPremisesPublishing

La solicitud devuelve una 204 No content respuesta.

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

Paso 3: Asignación de un grupo de conectores a la aplicación

Paso 3.1: Obtención de conectores

Identifique el conector que desea asignar al grupo de conectores. Registre su identificador.

Solicitud

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

Respuesta

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

Paso 3.2: Crear un conectorGrupo

Cree un connectorGroup denominado IWA Demo Connector Group para la aplicación. Registre su identificador.

Solicitud

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

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

Respuesta

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
}

Paso 3.3: Asignación de un conector al conectorGrupo

La solicitud devuelve una 204 No content respuesta.

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

Paso 3.4: Asignar la aplicación al connectorGroup

La solicitud devuelve una 204 No content respuesta.

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

Paso 4: Configuración del inicio de sesión único (SSO)

En este paso, configurará las propiedades onPremisesPublishing > singleSignOnSettings y onPremisesPublishing > singleSignOnMode para la aplicación.

Opción 1: Configuración del inicio de sesión único basado en IWA

En la solicitud siguiente se muestra cómo configurar la autenticación integrada de Windows (IWA) para la aplicación. La solicitud devuelve una 204 No content respuesta.

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

Opción 2: Configuración del inicio de sesión único basado en encabezado

En la solicitud siguiente se muestra cómo configurar el inicio de sesión único basado en encabezados para la aplicación. En este modo, el valor de la propiedad singleSignOnMode puede ser aadHeaderBased, pingHeaderBasedo oAuthToken. La solicitud devuelve una 204 No content respuesta.

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

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

Paso 5: Asignación de un usuario a la aplicación

Quiere asignar un usuario a la aplicación. En la entidad de servicio que creó en el paso 1, registre el identificador del rol de usuario predeterminado definido en la propiedad appRoles . Este valor es 18d14569-c3bd-439b-9a66-3a2aee01d14f.

En el cuerpo de la solicitud, proporcione los siguientes valores:

  • principalId : el identificador de la cuenta de usuario que creó.
  • appRoleId : el identificador del rol de aplicación predeterminado User que recuperó de la entidad de servicio.
  • resourceId : el identificador de la entidad de servicio.

Solicitud

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

Respuesta

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

Paso 6: Probar el acceso a la aplicación

Pruebe la aplicación visitando externalUrl configurado para la aplicación en el explorador y, a continuación, inicie sesión con el usuario de prueba. Debería poder iniciar sesión en la aplicación y acceder a la aplicación.

Paso 7: Limpiar los recursos

En este paso, quite los recursos que ha creado y que ya no necesitan.

Elimine la cuenta de usuario

La solicitud devuelve una 204 No content respuesta.

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

Eliminar la aplicación

Al eliminar la aplicación, también se elimina la entidad de servicio del inquilino. Esta solicitud devuelve una 204 No content respuesta.

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

Eliminación del grupo de conectores

La solicitud devuelve una 204 No content respuesta.

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