Microsoft Entra Application Proxy: MFA, SSO, Conditional Access, and User Management Guide 2026
Why Microsoft Entra Application Proxy Breaks , And Why the Error Messages Don't Help
You've got a legacy web app sitting on a server in your datacenter. It works perfectly on the corporate LAN. Now your remote workers need to reach it, without a VPN, without punching firewall holes, and with real modern authentication in front of it. That's exactly the problem Microsoft Entra Application Proxy was built to solve. And yet, here you are, staring at a 404, a blank screen, or an AADSTS error code that reads like a filing cabinet fell on you.
I've seen this setup go sideways on dozens of tenants, and almost every time the root cause falls into one of a handful of categories. The first is connector misconfiguration, specifically, publishing an application without actually assigning a working connector group to it. The second is the onPremisesPublishing property sitting at its default state, meaning the app exists in Entra ID but the proxy tunnel to your internal network was never opened. Third, and this one stings, is a Kerberos constrained delegation misconfiguration that lets IWA-based SSO silently fail with error AADSTS50058 or AADSTS75011, both of which tell you almost nothing useful about where the chain broke.
The Entra Application Proxy setup also trips people up because the configuration is split across two different Microsoft Graph API endpoints: the stable v1.0 endpoint for the application registration itself, and the beta endpoint for the onPremisesPublishing properties. If you run your PATCH against v1.0 expecting to set externalUrl or internalUrl, the call succeeds, and does nothing. The schema just silently ignores properties it doesn't recognize at that endpoint version. That silent failure is maddening to debug.
On top of that, the Azure AD Application Proxy connector service (now branded under Entra) sometimes goes stale after Windows updates or certificate rotations. The connector shows "active" in the portal for up to 30 minutes after it's actually stopped communicating, so the UI gives you false confidence. And if you've set appRoleAssignmentRequired to true on the service principal (which the applicationTemplates instantiation does by default), any user who hasn't been explicitly assigned will get an AADSTS65001 access error even if they're in the right group.
The Microsoft Entra Application Proxy configuration process using Microsoft Graph is genuinely powerful once it clicks. You can automate entire app publishing pipelines from a script. But the multi-step dependency chain, app creation, then URI config, then onPremisesPublishing, then connector group assignment, then SSO mode, then user assignment, means that skipping or mis-ordering any single step breaks the whole thing. This guide walks every step in the correct sequence, grounded in official Microsoft documentation.
The Quick Fix, Try This First
If your Microsoft Entra Application Proxy app registration exists but the external URL isn't routing correctly, there's one PATCH call that fixes the majority of cases: setting the onPremisesPublishing block on the beta endpoint with isOnPremPublishingEnabled set to true.
A lot of admins create the app registration through the portal or via a script targeting v1.0, get the app ID, set the redirect URIs, and then wonder why nothing comes through. The missing piece is the onPremisesPublishing property, which only exists on the beta endpoint. Here's what that PATCH looks like:
PATCH https://graph.microsoft.com/beta/applications/{your-app-object-id}
Content-Type: application/json
{
"onPremisesPublishing": {
"externalAuthenticationType": "aadPreAuthentication",
"internalUrl": "https://your-internal-app.contoso.com",
"externalUrl": "https://your-app-contoso.msappproxy.net",
"isHttpOnlyCookieEnabled": true,
"isOnPremPublishingEnabled": true,
"isPersistentCookieEnabled": true,
"isSecureCookieEnabled": true,
"isStateSessionEnabled": true,
"isTranslateHostHeaderEnabled": true,
"isTranslateLinksInBodyEnabled": true
}
}If that returns 204 No Content, you're on the right track. Now go check whether a connector group has been assigned to this application, that's the other half of the equation. If no connector group is linked, the proxy has nowhere to forward the traffic, and the external URL will time out every time.
One more quick check: open the Entra admin center, navigate to Enterprise Applications → [Your App] → Application Proxy, and confirm the connector group dropdown is not showing "None". If it is, jump to Step 4 in this guide before testing again.
For users getting access errors rather than routing errors, specifically the AADSTS65001 "user has not consented" or "no role assignment" variant, the fix is an explicit appRoleAssignment POST for each user. That's covered in Step 5.
id field returned in the app registration) in your Graph API calls, not the appId (client ID). These look similar in URLs but point to entirely different resources. Using appId where id is expected returns a 404 that looks identical to a permissions problem, and you'll waste an hour ruling out auth issues that don't exist.
The cleanest way to set up a Microsoft Entra Application Proxy app via Microsoft Graph is to start from the correct application template rather than creating a blank app registration. For Application Proxy publishing, you instantiate from template ID 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. This pre-wires the service principal with the correct tags, WindowsAzureActiveDirectoryCustomSingleSignOnApplication and WindowsAzureActiveDirectoryIntegratedApp, which the portal uses to render App Proxy settings correctly.
POST the following to the v1.0 endpoint:
POST https://graph.microsoft.com/v1.0/applicationTemplates/8adf8e6e-67b2-4cf2-a259-e3dc5476c621/instantiate
Content-Type: application/json
{
"displayName": "Your App Name Here"
}The response comes back as HTTP 201 Created and returns both an application object and a servicePrincipal object in a single payload. Record both IDs immediately. You need the application's id (the object ID, something like bf21f7e9-9d25-4da2-82ab-7fdd85049f83) for all subsequent PATCH calls. You need the service principal's id for user assignment later.
The instantiated service principal also ships with two pre-built app roles: a default User role (id 18d14569-c3bd-439b-9a66-3a2aee01d14f) and a msiam_access role. The User role ID is what you'll reference when assigning users in Step 5, so keep that value handy.
Also note that appRoleAssignmentRequired comes back as true on the service principal. This means every user must be explicitly granted access, no silent fallthrough. That's the right security posture for an on-premises app proxy scenario, but it does mean user assignment is not optional.
Success check: You should see the new app appear under Enterprise Applications in the Entra admin center within 60 seconds of the POST. If it doesn't appear after two minutes, verify that your calling identity has the Application.ReadWrite.All permission in Microsoft Graph.
With the app registered, the next task is setting the identifier URI and the redirect URI to match your Application Proxy external URL. This is a PATCH against the v1.0 applications endpoint, one of the two calls in this entire process that legitimately belongs on v1.0:
PATCH https://graph.microsoft.com/v1.0/applications/{application-object-id}
Content-Type: application/json
{
"identifierUris": [
"api://{your-app-client-id}"
],
"web": {
"redirectUris": [
"https://your-app-contoso.msappproxy.net"
],
"homePageUrl": "https://your-app-contoso.msappproxy.net"
}
}A successful PATCH here returns 204 No Content with an empty body. That's intentional and correct, don't mistake silence for failure.
The identifierUris field follows the api:// scheme using your app's client ID (the appId GUID, not the object ID). This scheme is required because the app's sign-in audience is AzureADMyOrg, which limits the allowed URI formats. If you try to set a custom domain-based identifier URI without first verifying that domain in Entra ID, this PATCH will return a 400 Bad Request with an unhelpful "Property identifierUris is invalid" message.
The redirectUris and homePageUrl should both point to the external URL, the .msappproxy.net address, or your custom domain if you've configured one. Don't accidentally set these to your internal URL. The proxy handles the internal routing; the application registration only needs to know about the external-facing address.
For custom external domains (where you want https://app.contoso.com instead of https://app-contoso.msappproxy.net), you'll need to verify the domain in Entra and upload a TLS certificate separately. That process is outside this guide's scope but worth flagging if your organization requires branded URLs.
Success check: Pull a GET on the application and confirm both identifierUris and web.redirectUris reflect the values you just set.
This is the step that separates a working Entra Application Proxy setup from a broken one. The onPremisesPublishing property block only exists on the beta endpoint, and it contains everything the App Proxy service needs to know about your internal application. You PATCH the same application object ID as before, but hit the beta path:
PATCH https://graph.microsoft.com/beta/applications/{application-object-id}
Content-Type: application/json
{
"onPremisesPublishing": {
"externalAuthenticationType": "aadPreAuthentication",
"internalUrl": "https://your-internal-app.contoso.com",
"externalUrl": "https://your-app-contoso.msappproxy.net",
"isHttpOnlyCookieEnabled": true,
"isOnPremPublishingEnabled": true,
"isPersistentCookieEnabled": true,
"isSecureCookieEnabled": true,
"isStateSessionEnabled": true,
"isTranslateHostHeaderEnabled": true,
"isTranslateLinksInBodyEnabled": true
}
}Let's talk through the most important properties. externalAuthenticationType set to aadPreAuthentication means Entra ID authenticates the user before any request reaches your internal app, this is how you enforce MFA and Conditional Access policies at the proxy layer. The alternative, passthrough, skips pre-authentication entirely and hands auth off to your internal app, which bypasses all your Entra security controls. For almost all scenarios, aadPreAuthentication is what you want.
The internalUrl is the address of your application as it's known inside your network, the hostname your on-premises connector can reach. The externalUrl is the publicly accessible address that remote users hit.
The cookie settings (isHttpOnlyCookieEnabled, isPersistentCookieEnabled, isSecureCookieEnabled) are security hygiene. Keep them all true unless you have a specific application compatibility reason not to. isStateSessionEnabled: true helps prevent CSRF attacks during the authentication flow. isTranslateHostHeaderEnabled and isTranslateLinksInBodyEnabled tell the connector to rewrite internal hostnames in responses, critical for applications that hardcode internal URLs in their HTML or HTTP headers.
Success check: A 204 No Content response. Then GET the application from beta and verify the onPremisesPublishing block is populated with your values. If it's still empty, check that you're PATCHing the correct object ID and that your token has Application.ReadWrite.All scope.
Connector groups are how the Application Proxy service knows which on-premises connector(s) to use when forwarding traffic for a given application. You need three sub-steps here: find your available connectors, create a named group, assign a connector to the group, then attach the group to the application.
4a, List available connectors. Query the connectors endpoint to find active connectors and record the ID of the one you want to use:
GET https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectors?$select=id,machineName,externalIp,statusNote the $select query parameter here, this is the performance optimization Microsoft's own API tips recommend. Without $select, the response includes every property on every connector object, which is wasteful on tenants with many connectors. You'll typically see each connector return an id, a machineName showing the server it's running on, an externalIp, and a status of either active or inactive.
4b, Create the connector group with a meaningful name. Good naming here pays dividends later when you have 30 apps and need to know which group handles which datacenter:
POST https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectorGroups
Content-Type: application/json
{
"name": "YourApp Connector Group - DC East"
}The 201 Created response gives you the new connector group's id. The connectorGroupType comes back as applicationProxy automatically, and the isDefault flag will be false, which is correct for a purpose-built group.
4c, Assign the connector to the group by POSTing a $ref to the connector's memberOf endpoint:
POST https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectors/{connector-id}/memberOf/$ref
Content-Type: application/json
{
"@odata.id": "https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectorGroups/{connector-group-id}"
}4d, Attach the connector group to the application using a PUT to the application's connectorGroup reference:
PUT https://graph.microsoft.com/beta/applications/{application-object-id}/connectorGroup/$ref
Content-Type: application/json
{
"@odata.id": "https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationproxy/connectorGroups/{connector-group-id}"
}Both the connector assignment and the app assignment return 204 No Content on success. Notice the lowercase applicationproxy in the final PUT URL, that's not a typo, it's how the endpoint is documented and the casing matters.
Success check: In the Entra admin center under Enterprise Applications → [Your App] → Application Proxy, the connector group dropdown should now show your named group instead of "None".
With the proxy plumbing in place, the last configuration step is choosing your SSO method and granting a user access. These are two separate PATCH/POST calls.
SSO configuration, Option A: Integrated Windows Authentication (IWA). If your internal app uses Windows authentication (most legacy IIS apps do), configure Kerberos-based SSO. You need the Kerberos Service Principal Name of your application, this is the SPN registered in Active Directory for the app's service account:
PATCH https://graph.microsoft.com/beta/applications/{application-object-id}
Content-Type: application/json
{
"onPremisesPublishing": {
"singleSignOnSettings": {
"kerberosSignOnSettings": {
"kerberosServicePrincipalName": "HTTP/your-internal-app.contoso.com",
"kerberosSignOnMappingAttributeType": "userPrincipalName"
},
"singleSignOnMode": "onPremisesKerberos"
}
}
}The kerberosSignOnMappingAttributeType tells the connector how to map the Entra ID user identity to an Active Directory account. userPrincipalName works when your UPNs match between Entra and AD. If they don't match, common in hybrid environments where the on-prem UPN suffix is different, switch to onPremisesSamAccountName instead.
SSO configuration, Option B: Header-Based SSO. For apps that accept identity via HTTP headers (common with legacy SSO platforms and some Linux web apps), set singleSignOnMode to aadHeaderBased:
PATCH https://graph.microsoft.com/beta/applications/{application-object-id}
Content-Type: application/json
{
"onPremisesPublishing": {
"singleSignOnSettings": {
"kerberosSignOnSettings": {},
"singleSignOnMode": "aadHeaderBased"
}
}
}Other valid values for singleSignOnMode include pingHeaderBased (for PingAccess-backed applications) and oAuthToken.
User assignment. With appRoleAssignmentRequired: true on the service principal, you must explicitly assign each user. The default User role ID from the template is 18d14569-c3bd-439b-9a66-3a2aee01d14f. POST to the service principal's appRoleAssignments endpoint:
POST https://graph.microsoft.com/beta/servicePrincipals/{service-principal-id}/appRoleAssignments
Content-Type: application/json
{
"principalId": "{user-object-id}",
"principalType": "User",
"appRoleId": "18d14569-c3bd-439b-9a66-3a2aee01d14f",
"resourceId": "{service-principal-id}"
}A 200 OK response (not 201) with the assignment details confirms success. The response includes a principalDisplayName, verify it matches the user you intended to assign.
Success check: Navigate to the externalUrl in a browser while signed in as the assigned test user. You should hit the Entra sign-in page (or pass through silently if you're already authenticated), then land on your internal application, no VPN, no additional prompts.
Advanced Troubleshooting for Microsoft Entra Application Proxy
Diagnosing Connector Problems
When an Application Proxy connector appears active in the portal but traffic still isn't flowing, the first place to look is the connector's local Windows Event Log. On the connector server, open Event Viewer → Applications and Services Logs → Microsoft → AadApplicationProxy → Connector → Admin. Event ID 12003 indicates a bootstrap failure, usually a TLS certificate problem or a blocked outbound connection to *.msappproxy.net on port 443. Event ID 12007 means the connector registered successfully but can't reach the backend service. Event ID 12011 points to a token acquisition failure, often because the system proxy settings on the connector server are intercepting and breaking the HTTPS connection to Azure endpoints.
Also check the connector's network path. The connector needs outbound access to *.msappproxy.net, *.servicebus.windows.net, and Microsoft's login endpoints. Many corporate firewalls do TLS inspection, and the connector's certificate pinning will fail silently when a firewall re-signs the certificate. The fix is a firewall bypass rule for those domains, not disabling TLS inspection globally.
Kerberos Delegation Errors
IWA-based SSO is where the App Proxy connector earns its complexity budget. The connector has to perform Kerberos constrained delegation on behalf of the user, which requires:
- The connector's Active Directory computer account delegated to the SPN you specified in
kerberosServicePrincipalName. - That SPN registered on the correct service account in AD, and registered only once. Duplicate SPNs cause AADSTS50058 failures that are genuinely hard to trace.
- The connector server able to reach a domain controller to request Kerberos tickets.
Run setspn -Q HTTP/your-internal-app.contoso.com from the connector server to verify the SPN exists and is unique. If setspn returns multiple accounts, you have a conflict. Clean it up before anything else.
For the delegation side, open Active Directory Users and Computers, find the connector's computer account, go to Properties → Delegation, and confirm it's set to Trust this computer for delegation to specified services only (constrained delegation), with the application's SPN listed. Protocol transition (Use any authentication protocol) is required if your users authenticate via forms-based login before the connector attempts Kerberos, which is the common scenario with aadPreAuthentication.
Using $select to Optimize Graph API Queries
When you query the connectors endpoint at scale, say, in a script that audits all connectors across a large tenant, the default response payload is substantial. Microsoft's own API tip surfaces this: use $select to specify only the properties you need. For connector health checks, ?$select=id,machineName,externalIp,status reduces payload size significantly and improves response time. For connector group audits, ?$select=id,name,connectorGroupType,isDefault,region gives you everything without the noise.
The onPremisesPublishing Beta Endpoint Trap
If you're automating App Proxy setup in a CI/CD pipeline and your PATCH calls return 204 but the properties aren't taking effect, double-check that every call touching onPremisesPublishing is going to graph.microsoft.com/beta, not graph.microsoft.com/v1.0. The v1.0 endpoint accepts the PATCH body without error but ignores any unknown properties, including the entire onPremisesPublishing block. This is a known developer experience issue that Microsoft has not resolved as of April 2026.
Conditional Access and MFA with Application Proxy
Conditional Access policies apply at the Entra pre-authentication layer when externalAuthenticationType is aadPreAuthentication. This means you can require MFA, compliant device state, specific named locations, or sign-in risk conditions before a user ever touches your internal application. Target the Conditional Access policy at the App Proxy application's service principal, not at "All cloud apps," to scope it precisely.
One trap: if your Conditional Access policy requires a compliant device and your users are on personal devices, they'll hit a block page at the proxy layer. The error will look like an application authentication failure, not a Conditional Access block, because the proxy redirects to an Entra error page before the user sees any app content. Use the Entra sign-in logs under Monitoring → Sign-in logs and filter by the application name to see the Conditional Access evaluation result. The "Conditional Access" tab on each log entry shows exactly which policies evaluated and what the outcome was.
Escalate to Microsoft Support when: the connector shows active in the portal but Event Viewer logs show consistent 12003/12007 errors and you've verified all network paths; when your tenant-level Application Proxy service appears disabled and re-enabling it from the portal has no effect; or when AADSTS error codes in sign-in logs don't match any documented error in the Microsoft identity platform error reference. These are infrastructure-level problems that no amount of config tweaking will fix from your side.
Prevention & Best Practices for Application Proxy Deployments
Getting the initial setup right is only part of the job. A well-run Microsoft Entra Application Proxy deployment stays healthy through consistent operational practices, not just a one-time configuration pass.
Use dedicated connector groups per application boundary. Don't throw every app into the default connector group. Segment by geography (connector servers near the app they serve), by business unit, or by security tier. This isolation means a connector issue in one group doesn't affect unrelated apps, and it makes troubleshooting dramatically faster. The connector group's region property (returned as eur, aus, asia, ind, or nam in the API) should match the Azure region closest to your connector servers to minimize latency.
Deploy connectors in pairs. A single connector per group is a single point of failure. The Application Proxy service load-balances across all active connectors in a group, so two connectors means zero downtime during Windows patching. Keep connectors up to date, the auto-update feature is enabled by default and should stay that way. Outdated connectors stop working when the backend service advances its protocol version.
Document every Kerberos SPN before you deploy. Maintain a spreadsheet or wiki page that maps each App Proxy application to its SPN, the AD service account the SPN is registered to, and the connector computer account that has delegation permission. Kerberos SPN conflicts are almost impossible to debug without this documentation, especially after staff turnover. Run setspn -L {serviceaccount} quarterly to catch drift.
Test Conditional Access policies in report-only mode first. Before enabling an MFA or device compliance requirement on a newly published App Proxy app, switch the Conditional Access policy to Report-only mode for one week. Review the sign-in logs to see how many users would have been blocked. This catches edge cases, service accounts, shared workstations, break-glass scenarios, without impacting real users.
Clean up resources promptly. When decommissioning an App Proxy application, delete in reverse order: remove user assignments, delete the application (which also removes the service principal), then delete the connector group if it's no longer in use. Orphaned connector groups and service principals accumulate and create confusion in future audits. The Graph API DELETE calls for application cleanup return 204 No Content on success.
- Set
$selecton every connector and connector group GET query to reduce API latency in automation scripts - Enable all four cookie security flags (
HttpOnly,Persistent,Secure,StateSession) at publish time, they're allfalseby default and require explicit opt-in - Assign users via group membership rather than individual
appRoleAssignmentswhere possible, it scales better and is easier to audit - Monitor connector server disk space and certificate expiry dates; a full disk or expired cert will silently kill the connector service overnight
Frequently Asked Questions
How do I use $select to speed up my Application Proxy connector queries in Graph API?
Add ?$select=id,machineName,externalIp,status to your GET request against https://graph.microsoft.com/beta/onPremisesPublishingProfiles/applicationProxy/connectors. Microsoft's own API response includes a tip recommending this exact practice. Without $select, the endpoint returns every property on every connector object, which bloats the response payload considerably on tenants with many connectors. For connector group queries, ?$select=id,name,connectorGroupType,isDefault,region is the equivalent slim query. This matters most in scripts that run on a schedule and query connector health across large deployments.
What's the real difference between IWA SSO and header-based SSO in Application Proxy?
Integrated Windows Authentication SSO (singleSignOnMode: "onPremisesKerberos") uses Kerberos constrained delegation, the connector impersonates the user against Active Directory and gets a Kerberos ticket for the internal app. This works for apps that accept Windows authentication natively, like most legacy IIS applications. Header-based SSO (singleSignOnMode: "aadHeaderBased") instead passes the user's identity as HTTP headers to the internal app, which reads those headers to establish the session. Header-based SSO is simpler to configure, no Kerberos delegation needed, but requires the application to be built to trust and consume those headers. If you're publishing a modern app or one that already has an SSO integration, header-based is often the easier path; if you're publishing a classic Windows intranet app, IWA is the right choice.
My App Proxy external URL returns a 404 right after I published the app, where do I start?
The three most common causes of a post-publish 404 are: (1) isOnPremPublishingEnabled is still false, PATCH the onPremisesPublishing block via the beta endpoint and set it explicitly to true; (2) no connector group is assigned to the application, check the portal under Application Proxy settings and assign an active group; (3) the connector in the assigned group is inactive, pull a GET on the connectors endpoint and check the status field, then investigate the connector's local Event Log for IDs 12003, 12007, or 12011. If all three of those check out, verify the internalUrl is reachable from the connector server itself by running a simple curl or browser test from that machine.
Can I assign a group of users to an App Proxy application instead of doing individual assignments?
Yes, you POST an appRoleAssignment where principalType is Group instead of User, and principalId is the object ID of the Entra security group. The Graph API endpoint is the same: POST /beta/servicePrincipals/{sp-id}/appRoleAssignments. This approach scales much better than individual assignments and integrates with your existing AD group structure if you're syncing groups via Entra Connect. One caveat: nested groups are not automatically expanded, only direct members of the assigned group get access, so make sure your group membership model accounts for that.
Does setting externalAuthenticationType to aadPreAuthentication automatically enforce MFA for App Proxy users?
Not automatically, aadPreAuthentication means Entra ID handles authentication before the request reaches your app, which enables MFA enforcement, but MFA only triggers if a Conditional Access policy requires it for that application. You need to create a Conditional Access policy targeting the App Proxy app's service principal and set the grant control to Require multifactor authentication. Without a Conditional Access policy, users authenticate with just their password. The advantage of aadPreAuthentication over passthrough is that when you do apply a Conditional Access policy, it actually runs, with passthrough mode, Conditional Access cannot evaluate the session at all.
What connector group region should I pick, and does it affect performance?
The connector group region field controls which Azure region the Application Proxy service uses as a relay point between the external user's request and your on-premises connector. You should set it to the Azure region geographically closest to your connector servers, not closest to your users. The reason: traffic flows from the user to Azure (low latency, Azure edge network handles this), then from Azure to your connector (where the region selection matters). Setting the wrong region adds a round trip across a continent before hitting your datacenter. Valid region values in the Graph API include eur, aus, asia, ind, and nam. You set the region when creating the connector group by including "region": "nam" (or your region code) in the POST body.