Freigeben über


Konfigurieren des Microsoft Entra-Anwendungsproxys mithilfe von Microsoft Graph-APIs

Der Microsoft Entra-Anwendungsproxy bietet sicheren Remotezugriff und einmaliges Anmelden (Single Sign-On, SSO) für lokale Webanwendungen. Sie ermöglicht Benutzern den Zugriff auf ihre lokalen Anwendungen über eine externe URL, das Portal "Meine Apps" oder andere interne Anwendungsportale.

In diesem Tutorial erfahren Sie, wie Sie den Microsoft Entra-Anwendungsproxy mithilfe von Microsoft Graph-APIs konfigurieren.

Wichtig

Die für den App-Proxy spezifischen API-Vorgänge sind derzeit nur auf dem beta Endpunkt verfügbar.

Voraussetzungen

  • Installieren Sie einen Connector, und schließen Sie die Voraussetzungen für den Anwendungsproxy ab, damit Connectors mit Microsoft Entra-Diensten kommunizieren können.
  • Melden Sie sich bei einem API-Client wie Graph-Explorer mit einem Konto an, das mindestens über die Rolle Cloudanwendungsadministrator verfügt.
  • Erteilen Sie sich die delegierte Microsoft Graph-Berechtigung Directory.ReadWrite.All .
  • Lassen Sie einen Testbenutzer der Anwendung zuweisen.

Schritt 1: Erstellen einer benutzerdefinierten Anwendung

Zum Konfigurieren des Anwendungsproxys erstellen Sie zunächst eine benutzerdefinierte Anwendung und aktualisieren dann die App-Proxyeinstellungen in der onPremisesPublishing-Eigenschaft der Anwendung. In diesem Tutorial verwenden Sie eine Anwendungsvorlage, um eine Instanz einer benutzerdefinierten Anwendung und eines Dienstprinzipals in Ihrem Mandanten zu erstellen. Die Vorlagen-ID für eine benutzerdefinierte Anwendung ist 8adf8e6e-67b2-4cf2-a259-e3dc5476c621, die Sie ermitteln können, indem Sie die folgende Abfrage ausführen: GET https://graph.microsoft.com/v1.0/applicationTemplates?$filter=displayName eq 'Custom'.

Notieren Sie sich in der Antwort die ID des Dienstprinzipals und der Anwendungsobjekte sowie den Wert von appId zur späteren Verwendung im Tutorial.

Anforderung

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

{
  "displayName": "Contoso IWA App"
}

Antwort

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

Schritt 2: Konfigurieren des Anwendungsproxys

Konfigurieren Sie für die App, die Sie in Schritt 1 erstellt haben, die URIs für die Anwendung. Angenommen, die interne URL der App lautet https://contosoiwaapp.com und die Standarddomäne für die externe URL lautet https://contosoiwaapp-contoso.msappproxy.net. Fügen Sie den Externen URL-Wert den Eigenschaften identifierUris, web>redirectUris und web>homePageUrl hinzu.

Konfigurieren Sie außerdem die onPremisesPublishing-Eigenschaft , um die internen und externen URLs sowie andere Eigenschaften nach Bedarf festzulegen. Diese Eigenschaft ist nur in beta verfügbar und kann erst konfiguriert werden, wenn Sie die URIs konfigurieren.

Schritt 2.1: Konfigurieren der URIs

Die folgende Anforderung verwendet den Wert von appId für die identifierUris-Eigenschaft . Sie können auch einen beliebigen anderen Bezeichner verwenden, der dem von Microsoft Entra ID erwarteten URI-Format der Anwendungs-ID entspricht. Die Anforderung gibt eine 204 No content Antwort zurück.

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

Schritt 2.2: Konfigurieren der onPremisesPublishing-Eigenschaft

Die Anforderung gibt eine 204 No content Antwort zurück.

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

Schritt 3: Zuweisen einer Connectorgruppe zur Anwendung

Schritt 3.1: Abrufen von Connectors

Identifizieren Sie den Connector, den Sie der Connectorgruppe zuweisen möchten. Notieren Sie sich die ID.

Anforderung

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

Antwort

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

Schritt 3.2: Erstellen einer connectorGroup

Erstellen Sie eine connectorGroup mit dem Namen IWA Demo Connector Group für die Anwendung. Notieren Sie sich die ID.

Anforderung

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

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

Antwort

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
}

Schritt 3.3: Zuweisen eines Connectors zur connectorGroup

Die Anforderung gibt eine 204 No content Antwort zurück.

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

Schritt 3.4: Zuweisen der Anwendung zur connectorGroup

Die Anforderung gibt eine 204 No content Antwort zurück.

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

Schritt 4: Konfigurieren des einmaligen Anmeldens (Single Sign-On, SSO)

In diesem Schritt konfigurieren Sie die Eigenschaften onPremisesPublishing > singleSignOnSettings und onPremisesPublishing > singleSignOnMode für die Anwendung.

Option 1: Konfigurieren des IWA-basierten einmaligen Anmeldens

Die folgende Anforderung zeigt, wie Die integrierte Windows-Authentifizierung (IWA) für die Anwendung konfiguriert wird. Die Anforderung gibt eine 204 No content Antwort zurück.

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

Option 2: Konfigurieren des headerbasierten einmaligen Anmeldens

Die folgende Anforderung zeigt, wie Sie headerbasiertes einmaliges Anmelden für die Anwendung konfigurieren. In diesem Modus kann der Wert der singleSignOnMode-Eigenschaft , pingHeaderBasedoder oAuthTokenseinaadHeaderBased. Die Anforderung gibt eine 204 No content Antwort zurück.

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

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

Schritt 5: Zuweisen eines Benutzers zur Anwendung

Sie möchten der Anwendung einen Benutzer zuweisen. Notieren Sie sich in dem Dienstprinzipal, den Sie in Schritt 1 erstellt haben, die ID der Standardrolle Benutzer , die in der appRoles-Eigenschaft definiert ist. Dieser Wert ist 18d14569-c3bd-439b-9a66-3a2aee01d14f.

Geben Sie im Anforderungstext die folgenden Werte an:

  • principalId : Die ID des Benutzerkontos, das Sie erstellt haben.
  • appRoleId : Die ID der Standard-App-Rolle User , die Sie aus dem Dienstprinzipal abgerufen haben.
  • resourceId : Die ID des Dienstprinzipals.

Anforderung

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

Antwort

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

Schritt 6: Testen des Zugriffs auf die Anwendung

Testen Sie die Anwendung, indem Sie die für die App konfigurierte externalUrl in Ihrem Browser aufrufen und sich dann mit Ihrem Testbenutzer anmelden. Sie sollten sich bei der App anmelden und auf die Anwendung zugreifen können.

Schritt 7: Ressourcen bereinigen

Entfernen Sie in diesem Schritt die Ressourcen, die Sie erstellt haben und nicht mehr benötigen.

Löschen Sie das Benutzerkonto.

Die Anforderung gibt eine 204 No content Antwort zurück.

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

Löschen der Anwendung

Wenn Sie die Anwendung löschen, wird auch der Dienstprinzipal in Ihrem Mandanten gelöscht. Diese Anforderung gibt eine 204 No content Antwort zurück.

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

Löschen der Connectorgruppe

Die Anforderung gibt eine 204 No content Antwort zurück.

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