{ "schemaVersion": "1.0", "code": "500021", "name": null, "title": "AADSTS500021 fix: tenant blocked by tenant restrictions", "url": "https://brambrinkmeier.com/entra/aadsts/500021/", "alternates": { "markdown": "https://brambrinkmeier.com/entra/aadsts/500021.md", "json": "https://brambrinkmeier.com/api/aadsts/500021.json", "html": "https://brambrinkmeier.com/entra/aadsts/500021/" }, "description": "AADSTS500021: a tenant restrictions v1 proxy header doesn't allow the tenant you tried to reach. Fixed by the network's admin, not the app's.", "summary": "AADSTS500021 means tenant restrictions (v1) are on in the user's network: a proxy adds a list of allowed tenants to sign-in traffic, and the tenant the user tried to reach isn't on it. It is a control doing its job, with low attack value. The fix is on the side of whoever runs the proxy, usually the user's own organisation, not the app's tenant.", "inMicrosoftReference": true, "unlistedChecked": null, "meaningText": "Microsoft's description:\n\n> Access to '{tenant}' tenant is denied. AADSTS500021 indicates that the tenant restriction feature is configured and that the user is trying to access a tenant that isn't in the list of allowed tenants specified in the header `Restrict-Access-To-Tenant`. For more information, see Use tenant restrictions to manage access to SaaS cloud applications.\n\nMicrosoft gives this code no name. The block comes from the **network**, not from the tenant the user is signing in to.\n\nTenant restrictions (the original version, which Microsoft's v2 page calls *\"Tenant restrictions v1\"*) work like this. A corporate proxy that does TLS inspection adds two headers to every request to `login.microsoftonline.com`, `login.microsoft.com` and `login.windows.net`:\n\n- `Restrict-Access-To-Tenants`: *\"a comma-separated list of tenants you want to allow users to access\"*.\n- `Restrict-Access-Context`: *\"a single directory ID, declaring which tenant is setting the tenant restrictions\"*.\n\nIf the tenant the user tries to reach isn't on the list, sign-in fails. Microsoft's tenant restrictions page says the user *\"sees an access denial message\"* about *\"a resource that belongs to an organization unapproved by your IT department.\"* Microsoft's error description writes the header as `Restrict-Access-To-Tenant`; the tenant restrictions page spells it `Restrict-Access-To-Tenants`, with an s. Use the page's spelling on your proxy.\n\n### v1 or v2?\nBe precise here, because the two versions use different headers and, as far as Microsoft documents, different codes.\n\n| | Tenant restrictions v1 | Tenant restrictions v2 |\n|---|---|---|\n| Where the allow list lives | In the proxy header itself | *\"moved to the server-side cloud policy\"* (cross-tenant access settings) |\n| Header | `Restrict-Access-To-Tenants` + `Restrict-Access-Context` | `sec-Restrict-Tenant-Access-Policy: :` |\n| Enforcement | Corporate proxy only | Proxy, Windows devices (Group Policy) or Global Secure Access |\n| Protects | Authentication plane | Authentication plane, plus data plane with device signalling |\n| Code Microsoft shows | **500021** (error reference) | **[5000211](https://brambrinkmeier.com/entra/aadsts/5000211/)** (v2 setup page) |\n\nSo: 500021 points at a v1 allow list on a proxy. If the message says *\"A tenant restrictions policy added to this request by a device or network administrator\"*, you are looking at v2 and 5000211. Microsoft notes that migrating from v1 to v2 *\"is a one-time operation\"*.", "sections": [ { "heading": "What does AADSTS500021 mean?", "text": "Microsoft's description:\n\n> Access to '{tenant}' tenant is denied. AADSTS500021 indicates that the tenant restriction feature is configured and that the user is trying to access a tenant that isn't in the list of allowed tenants specified in the header `Restrict-Access-To-Tenant`. For more information, see Use tenant restrictions to manage access to SaaS cloud applications.\n\nMicrosoft gives this code no name. The block comes from the **network**, not from the tenant the user is signing in to.\n\nTenant restrictions (the original version, which Microsoft's v2 page calls *\"Tenant restrictions v1\"*) work like this. A corporate proxy that does TLS inspection adds two headers to every request to `login.microsoftonline.com`, `login.microsoft.com` and `login.windows.net`:\n\n- `Restrict-Access-To-Tenants`: *\"a comma-separated list of tenants you want to allow users to access\"*.\n- `Restrict-Access-Context`: *\"a single directory ID, declaring which tenant is setting the tenant restrictions\"*.\n\nIf the tenant the user tries to reach isn't on the list, sign-in fails. Microsoft's tenant restrictions page says the user *\"sees an access denial message\"* about *\"a resource that belongs to an organization unapproved by your IT department.\"* Microsoft's error description writes the header as `Restrict-Access-To-Tenant`; the tenant restrictions page spells it `Restrict-Access-To-Tenants`, with an s. Use the page's spelling on your proxy.\n\n### v1 or v2?\nBe precise here, because the two versions use different headers and, as far as Microsoft documents, different codes.\n\n| | Tenant restrictions v1 | Tenant restrictions v2 |\n|---|---|---|\n| Where the allow list lives | In the proxy header itself | *\"moved to the server-side cloud policy\"* (cross-tenant access settings) |\n| Header | `Restrict-Access-To-Tenants` + `Restrict-Access-Context` | `sec-Restrict-Tenant-Access-Policy: :` |\n| Enforcement | Corporate proxy only | Proxy, Windows devices (Group Policy) or Global Secure Access |\n| Protects | Authentication plane | Authentication plane, plus data plane with device signalling |\n| Code Microsoft shows | **500021** (error reference) | **[5000211](https://brambrinkmeier.com/entra/aadsts/5000211/)** (v2 setup page) |\n\nSo: 500021 points at a v1 allow list on a proxy. If the message says *\"A tenant restrictions policy added to this request by a device or network administrator\"*, you are looking at v2 and 5000211. Microsoft notes that migrating from v1 to v2 *\"is a one-time operation\"*." }, { "heading": "Is it an attack?", "text": "No. It is a block working as designed. Tenant restrictions exist to stop users signing in to tenants their organisation hasn't approved, for example a personal or competitor tenant used to move data out.\n\n| Pattern | Likely meaning |\n|---|---|\n| A guest from a customer or partner organisation gets 500021 on your app | Their IT runs tenant restrictions and your tenant isn't on their list. Users report exactly this in Microsoft Q&A, including for Power BI shared with external customers. |\n| Your own users get 500021 when opening a partner's app | Your proxy doesn't list the partner's tenant. Add it if the access is approved. |\n| Your own users get 500021 for a tenant nobody recognises | The control stopped a sign-in to an unapproved tenant. Our interpretation: worth asking the user why, because this is the data-leak path tenant restrictions are meant to close. |\n| 500021 started for many users at once | Someone changed the proxy's allow list, or traffic moved to a proxy with a different list. |" }, { "heading": "How do I find it in my logs (KQL)?", "text": "Microsoft gives the admin of the `Restrict-Access-Context` tenant a dedicated report: **Entra ID** > **Overview** > **Tenant restrictions**. It shows *\"sign-ins blocked because of the tenant restrictions policy, including the identity used and the target directory ID.\"* Microsoft adds that *\"Sign-ins are included if the tenant setting the restriction is either the user tenant or resource tenant for the sign-in\"*, and that identities from other tenants are masked.\n\nMicrosoft doesn't document which Log Analytics table 500021 rows land in, or in which tenant's workspace. Check yours:\n\n```kusto\nunion withsource=SourceTable SigninLogs, AADNonInteractiveUserSignInLogs\n| where TimeGenerated > ago(7d)\n| where ResultType == \"500021\"\n| summarize Rows = count(), Users = dcount(UserPrincipalName) by SourceTable\n```\n\nWhich target tenants are being blocked, for whom, and from which egress IPs (each egress IP points at a proxy):\n\n```kusto\nSigninLogs\n| where TimeGenerated > ago(30d)\n| where ResultType == \"500021\"\n| summarize Rows = count(),\n Users = dcount(UserPrincipalName),\n Apps = make_set(AppDisplayName, 5),\n EgressIPs = make_set(IPAddress, 10)\n by HomeTenantId, ResourceTenantId, IsTenantRestricted\n| sort by Users desc\n```\n\nThe `IsTenantRestricted` column is documented as *\"Indicates if a signIn is under a tenant restrictions policy or not.\"* Whether Microsoft sets it on 500021 rows isn't documented. If it does, this finds every sign-in under a restrictions policy, blocked or not:\n\n```kusto\nSigninLogs\n| where TimeGenerated > ago(7d)\n| where IsTenantRestricted == true\n| summarize Rows = count(), Users = dcount(UserPrincipalName) by ResultType, ResourceTenantId\n| sort by Rows desc\n```\n\n`ResultType` is a **string** column, so compare it with `\"500021\"`." }, { "heading": "How does Conditional Access affect it?", "text": "- 500021 is not a Conditional Access block. The proxy header decides it, whatever the target tenant's policies say.\n- Don't confuse it with [53003](https://brambrinkmeier.com/entra/aadsts/53003/), which is a Conditional Access block in the target tenant. The owner of the fix is different.\n- Cross-tenant access settings for B2B collaboration are also a different control. One Q&A answer suggests changing outbound B2B settings for this error. Microsoft's description of 500021 points only at the v1 header, so start there." }, { "heading": "How do I fix AADSTS500021?", "text": "**For the user:** the network you are on only allows sign-in to approved tenants. Ask **your own** IT team to allow the tenant you need. If you are a guest on someone else's app, the app's owner can't fix this for you.\n\n**For app owners and B2B hosts:** you can't fix this from your tenant. Tell the guest's IT team your tenant ID or verified domain and ask them to add it to their tenant restrictions list. Users in Microsoft Q&A report this is the step that's missing.\n\n**For admins who run the proxy:**\n1. Find the proxy rule that adds `Restrict-Access-To-Tenants` to traffic for the Microsoft sign-in hosts.\n2. Add the target tenant. Microsoft says *\"Any domain that is registered with a tenant can be used to identify the tenant in this list, and the directory ID itself.\"* Microsoft's example: `Restrict-Access-To-Tenants: contoso.com,fabrikam.onmicrosoft.com,{guid}`.\n3. Keep `Restrict-Access-Context` set to **your own** directory ID. Microsoft warns that with any other ID *\"the sign-in logs appear in someone else's tenant, with all personal information removed.\"*\n4. Before you allow a tenant nobody asked for, check why users tried to reach it.\n5. If you are moving to tenant restrictions v2, the allow list moves into cross-tenant access settings and the v1 header should be removed from the proxy. Blocks then show as [5000211](https://brambrinkmeier.com/entra/aadsts/5000211/)." } ], "microsoftWording": { "text": "Access to '{tenant}' tenant is denied. AADSTS500021 indicates that the tenant restriction feature is configured and that the user is trying to access a tenant that isn't in the list of allowed tenants specified in the header `Restrict-Access-To-Tenant`. For more information, see Use tenant restrictions to manage access to SaaS cloud applications.", "source": "Microsoft's error code reference, as quoted on the page", "sourceUrl": "https://learn.microsoft.com/en-us/entra/identity-platform/reference-error-codes" }, "securityReading": { "category": { "id": "b2b-tenant", "label": "Guests and tenants" }, "kind": { "id": "failure", "label": "Failure" }, "attackSignal": { "level": "low", "label": "Low: usually configuration or user error" }, "mitre": [], "tables": [], "isItAnAttack": "No. It is a block working as designed. Tenant restrictions exist to stop users signing in to tenants their organisation hasn't approved, for example a personal or competitor tenant used to move data out.\n\n| Pattern | Likely meaning |\n|---|---|\n| A guest from a customer or partner organisation gets 500021 on your app | Their IT runs tenant restrictions and your tenant isn't on their list. Users report exactly this in Microsoft Q&A, including for Power BI shared with external customers. |\n| Your own users get 500021 when opening a partner's app | Your proxy doesn't list the partner's tenant. Add it if the access is approved. |\n| Your own users get 500021 for a tenant nobody recognises | The control stopped a sign-in to an unapproved tenant. Our interpretation: worth asking the user why, because this is the data-leak path tenant restrictions are meant to close. |\n| 500021 started for many users at once | Someone changed the proxy's allow list, or traffic moved to a proxy with a different list. |", "conditionalAccess": { "heading": "How does Conditional Access affect it?", "text": "- 500021 is not a Conditional Access block. The proxy header decides it, whatever the target tenant's policies say.\n- Don't confuse it with [53003](https://brambrinkmeier.com/entra/aadsts/53003/), which is a Conditional Access block in the target tenant. The owner of the fix is different.\n- Cross-tenant access settings for B2B collaboration are also a different control. One Q&A answer suggests changing outbound B2B settings for this error. Microsoft's description of 500021 points only at the v1 header, so start there." } }, "kql": [ { "title": null, "leadIn": "Microsoft doesn't document which Log Analytics table 500021 rows land in, or in which tenant's workspace. Check yours:", "query": "union withsource=SourceTable SigninLogs, AADNonInteractiveUserSignInLogs\n| where TimeGenerated > ago(7d)\n| where ResultType == \"500021\"\n| summarize Rows = count(), Users = dcount(UserPrincipalName) by SourceTable" }, { "title": null, "leadIn": "Which target tenants are being blocked, for whom, and from which egress IPs (each egress IP points at a proxy):", "query": "SigninLogs\n| where TimeGenerated > ago(30d)\n| where ResultType == \"500021\"\n| summarize Rows = count(),\n Users = dcount(UserPrincipalName),\n Apps = make_set(AppDisplayName, 5),\n EgressIPs = make_set(IPAddress, 10)\n by HomeTenantId, ResourceTenantId, IsTenantRestricted\n| sort by Users desc" }, { "title": null, "leadIn": "The `IsTenantRestricted` column is documented as *\"Indicates if a signIn is under a tenant restrictions policy or not.\"* Whether Microsoft sets it on 500021 rows isn't documented. If it does, this finds every sign-in under a restrictions policy, blocked or not:", "query": "SigninLogs\n| where TimeGenerated > ago(7d)\n| where IsTenantRestricted == true\n| summarize Rows = count(), Users = dcount(UserPrincipalName) by ResultType, ResourceTenantId\n| sort by Rows desc" } ], "kqlSectionText": "Microsoft gives the admin of the `Restrict-Access-Context` tenant a dedicated report: **Entra ID** > **Overview** > **Tenant restrictions**. It shows *\"sign-ins blocked because of the tenant restrictions policy, including the identity used and the target directory ID.\"* Microsoft adds that *\"Sign-ins are included if the tenant setting the restriction is either the user tenant or resource tenant for the sign-in\"*, and that identities from other tenants are masked.\n\nMicrosoft doesn't document which Log Analytics table 500021 rows land in, or in which tenant's workspace. Check yours:\n\n```kusto\nunion withsource=SourceTable SigninLogs, AADNonInteractiveUserSignInLogs\n| where TimeGenerated > ago(7d)\n| where ResultType == \"500021\"\n| summarize Rows = count(), Users = dcount(UserPrincipalName) by SourceTable\n```\n\nWhich target tenants are being blocked, for whom, and from which egress IPs (each egress IP points at a proxy):\n\n```kusto\nSigninLogs\n| where TimeGenerated > ago(30d)\n| where ResultType == \"500021\"\n| summarize Rows = count(),\n Users = dcount(UserPrincipalName),\n Apps = make_set(AppDisplayName, 5),\n EgressIPs = make_set(IPAddress, 10)\n by HomeTenantId, ResourceTenantId, IsTenantRestricted\n| sort by Users desc\n```\n\nThe `IsTenantRestricted` column is documented as *\"Indicates if a signIn is under a tenant restrictions policy or not.\"* Whether Microsoft sets it on 500021 rows isn't documented. If it does, this finds every sign-in under a restrictions policy, blocked or not:\n\n```kusto\nSigninLogs\n| where TimeGenerated > ago(7d)\n| where IsTenantRestricted == true\n| summarize Rows = count(), Users = dcount(UserPrincipalName) by ResultType, ResourceTenantId\n| sort by Rows desc\n```\n\n`ResultType` is a **string** column, so compare it with `\"500021\"`.", "fix": { "short": "User: you are on a network that only allows certain tenants; ask your own IT team to allow this one. Admin of the network: add the tenant's ID or domain to the Restrict-Access-To-Tenants header on your proxy. App owner: you can't fix this from your tenant; the user's IT team must.", "steps": "**For the user:** the network you are on only allows sign-in to approved tenants. Ask **your own** IT team to allow the tenant you need. If you are a guest on someone else's app, the app's owner can't fix this for you.\n\n**For app owners and B2B hosts:** you can't fix this from your tenant. Tell the guest's IT team your tenant ID or verified domain and ask them to add it to their tenant restrictions list. Users in Microsoft Q&A report this is the step that's missing.\n\n**For admins who run the proxy:**\n1. Find the proxy rule that adds `Restrict-Access-To-Tenants` to traffic for the Microsoft sign-in hosts.\n2. Add the target tenant. Microsoft says *\"Any domain that is registered with a tenant can be used to identify the tenant in this list, and the directory ID itself.\"* Microsoft's example: `Restrict-Access-To-Tenants: contoso.com,fabrikam.onmicrosoft.com,{guid}`.\n3. Keep `Restrict-Access-Context` set to **your own** directory ID. Microsoft warns that with any other ID *\"the sign-in logs appear in someone else's tenant, with all personal information removed.\"*\n4. Before you allow a tenant nobody asked for, check why users tried to reach it.\n5. If you are moving to tenant restrictions v2, the allow list moves into cross-tenant access settings and the v1 header should be removed from the proxy. Blocks then show as [5000211](https://brambrinkmeier.com/entra/aadsts/5000211/)." }, "labReproduced": null, "labSectionText": null, "labRuns": [], "verification": "documentation", "related": [ "5000211", "50020", "53003", "90072" ], "coveredBy": [], "sources": [ { "title": "Microsoft Entra authentication and authorization error codes", "url": "https://learn.microsoft.com/en-us/entra/identity-platform/reference-error-codes" }, { "title": "Use tenant restrictions to manage access to SaaS cloud applications", "url": "https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/tenant-restrictions" }, { "title": "Set up tenant restrictions v2", "url": "https://learn.microsoft.com/en-us/entra/external-id/tenant-restrictions-v2" }, { "title": "SigninLogs table reference (Azure Monitor)", "url": "https://learn.microsoft.com/en-us/azure/azure-monitor/reference/tables/signinlogs" }, { "title": "Microsoft Q&A: Diagnosing and fixing AADSTS500021 (user reports)", "url": "https://learn.microsoft.com/en-us/answers/questions/2201407/diagnosing-and-fixing-aadsts500021" }, { "title": "Microsoft Q&A: Edit Restrict-Access-To-Tenants to external tenant (user reports)", "url": "https://learn.microsoft.com/en-us/answers/questions/661557/edit-restrict-access-to-tenants-to-external-tenant" } ], "published": "2026-11-01", "lastUpdated": "2026-11-01", "lastVerified": null, "license": "CC BY 4.0", "licenseUrl": "https://creativecommons.org/licenses/by/4.0/", "licenseNote": "CC BY 4.0 covers the author's own text and classification fields. Quoted Microsoft error wording belongs to Microsoft, is quoted with its source and can change.", "attribution": "Bram Brinkmeier, \"AADSTS500021 fix: tenant blocked by tenant restrictions\", https://brambrinkmeier.com/entra/aadsts/500021/ (CC BY 4.0)", "microsoftErrorLookup": "https://login.microsoftonline.com/error?code=500021" }