SaaS Tenant Restriction using PAN-OS HTTP Header Insertion
Controlling user access *within* sanctioned Software-as-a-Service (SaaS) applications is a critical security challenge. Unsanctioned usage of SaaS applications, particularly accessing personal or consumer versions (e.g., personal Microsoft 365, Google Drive), can be a significant vector for sensitive information leaving your network.
Even if you need to allow access to the enterprise version of these applications for legitimate business purposes, you often want to prevent access to all other tenants from the corporate network. Blocking the entire SaaS application isn't feasible in these cases.
Palo Alto Networks firewalls can help enforce **SaaS Tenant Restrictions** by leveraging
HTTP Header Insertion
. This involves the firewall injecting specific HTTP headers, recognized by major SaaS providers like Microsoft and Google, into user login requests. These headers explicitly declare which specific tenant(s) the user is permitted to access from the corporate network.
This capability allows you to disallow SaaS consumer accounts while permitting access only to specific, sanctioned enterprise accounts.
Core Concept:
The firewall intercepts SaaS login requests, decrypts them, and inserts predefined headers (e.g., `Restrict-Access-To-Tenants`) with specific values (allowed tenant IDs). The SaaS provider then reads this header and enforces access, blocking logins to unauthorized tenants.
Note: According to Palo Alto Networks documentation, using the HTTP Header Insertion feature for tenant restriction does not require a separate URL Filtering license.
Concept & Use Cases - Why Restrict SaaS Tenants?
Implementing SaaS tenant restrictions provides several key security benefits:
Prevent Data Exfiltration:
This is often the primary driver. It stops users from logging into personal instances of OneDrive, Google Drive, Box, Dropbox, Slack, etc., and uploading sensitive corporate documents from managed devices or the corporate network. Unsanctioned SaaS usage is a common path for data leakage.
Enforce Corporate Resource Usage:
Ensures that users utilize company-sanctioned SaaS instances for business purposes, maintaining organizational control and visibility over data stored and shared in the cloud.
Reduce Attack Surface:
Limits the potential impact of compromised credentials. If an attacker compromises a user's corporate account, tenant restrictions can prevent them from easily accessing or exfiltrating data via linked personal SaaS accounts accessed from the corporate network.
Compliance and Governance:
Helps meet regulatory or internal governance requirements that mandate control over where corporate data resides and how collaboration occurs (e.g., preventing use of non-approved storage).
Mitigate Shadow IT Risks:
Prevents the use of unsanctioned tenants of *approved* SaaS applications from the managed network, reducing the sprawl of unmanaged corporate data.
Scenario: Data Leak via Personal Drive
An employee wants to take work home. Instead of using the corporate OneDrive (which might have DLP policies), they log into their personal OneDrive account from their work laptop on the corporate network and upload sensitive design documents. Without tenant restriction, this is often possible. With tenant restriction enforced by the firewall inserting the corporate tenant ID header, Microsoft's login service would see the header, recognize the user is trying to access a different tenant (personal), and block the login from the corporate network.
Concept & Use Cases - How Header Insertion Enables Tenant Restriction
Unlike inserting user identity headers (like `X-Authenticated-User`), tenant restriction relies on inserting **specific, predefined header names** with **static values** (your allowed tenant IDs or domains).
User Initiates Login:
The user attempts to log in to a SaaS application (e.g., `login.microsoftonline.com`, `accounts.google.com`).
Firewall Intercepts & Decrypts:
The PAN-OS firewall intercepts the HTTPS connection.
Decryption is essential
as the headers need to be inserted into the encrypted HTTP request to the login service.
Policy Match & Profile Application:
A Security Policy rule matching the SaaS login domains/URLs and potentially specific users/groups triggers an associated HTTP Header Insertion profile.
Header Insertion (Predefined or Custom Type):
The profile is configured to insert the required header(s).
PAN-OS provides **Predefined Types** for common scenarios like Microsoft 365 enterprise restrictions, simplifying configuration. These are maintained via content updates.
For other SaaS apps, or specific cases like M365 consumer restriction, the **Custom Type** is used:
The **Header Name** is set to the exact name required by the SaaS vendor (e.g., `Restrict-Access-To-Tenants`).
The **Header Value** is set to a **static string** containing the list of allowed Tenant IDs or domains, formatted precisely as required by the vendor.
Request Forwarded:
The firewall forwards the modified HTTPS request (with the inserted tenant restriction header) to the SaaS provider's login service.
SaaS Provider Enforcement:
The SaaS provider's service reads the specific header. If the user is attempting to authenticate to a tenant *not* listed in the header's value, the SaaS provider blocks the login attempt. If they are logging into an allowed tenant, the login proceeds normally.
Key Difference:
The firewall isn't dynamically determining the header value based on the user; it's inserting a *static policy statement* (the allowed tenants) defined in the profile. The *SaaS provider* reads this statement and enforces the restriction. User-ID on the firewall remains important for applying the *correct policy rule* to the user's traffic initially.
Concept & Use Cases - Use Case: Data Exfiltration Prevention
This is the most common driver for implementing tenant restrictions.
Problem:
Users on corporate networks/devices can easily log into personal cloud storage (OneDrive, Google Drive, Box, Dropbox) or collaboration tools (Slack, Teams personal tenants) and upload sensitive corporate data.
Solution:
By configuring the firewall to insert the appropriate tenant restriction header listing *only* the corporate tenant ID(s) for these services, attempts to log into personal or other unauthorized tenants from the corporate network are blocked *by the SaaS provider*.
Mechanism Example (Personal OneDrive):
User browses to `onedrive.live.com` or attempts login via `login.live.com`.
Firewall decrypts, matches policy for Microsoft consumer login domains.
Google sees the user is attempting to access a Customer ID (`othercompany.com`) not listed in the header.
Google blocks the login attempt.
This significantly reduces the risk of accidental or intentional data leakage via common cloud vectors by leveraging the SaaS provider's own enforcement capabilities.
Concept & Use Cases - Use Case: Compliance & Policy Enforcement
Tenant restrictions also support broader compliance and IT policy goals:
Mandated Tool Usage:
Enforces policies stating that employees must use company-provided instances of collaboration or storage tools for all business activities conducted on the corporate network.
Data Residency/Sovereignty:
Ensuring users only access the corporate tenant (which might be configured for specific data regions) helps maintain data residency policies.
Auditability:
Centralizes business activity within sanctioned tenants, making monitoring and auditing via CASB or native SaaS tools more comprehensive, as activity isn't fragmented across personal accounts accessed from work.
Guest Access Control (Indirect):
While tenant restriction primarily controls outbound logins, configuring it correctly is often part of a broader strategy for managing external collaboration and guest access within the sanctioned tenant. (Note: It can sometimes interfere with legitimate guest access *to other tenants* if not carefully configured - see Limitations).
Consider how tenant restrictions align with your Acceptable Use Policy (AUP) and data governance framework.
SaaS Support & Headers - SaaS Header Overview
Before configuring, it's crucial to understand the specific custom HTTP headers required by the SaaS application you intend to manage. Different providers use different header names and expect different values.
Palo Alto Networks provides predefined support for common applications, simplifying configuration. However, for others, or for more granular control, you'll use the 'Custom' header type.
The following sections detail the headers for major providers based on available documentation. Remember that SaaS applications not listed here might still support tenant restriction via headers, but you will need to consult their specific documentation.
Be aware that some headers control access to *types* of accounts (enterprise vs. consumer), while others control access to *specific* tenants/organizations, and some control in-app features (like YouTube's content restriction).
Always verify the exact header requirements with the SaaS vendor's current documentation.
SaaS Support & Headers - Microsoft 365 Headers
Microsoft supports tenant restrictions targeting Azure AD (Entra ID) logins.
Configure both sets of headers (typically via one Predefined entry and one Custom entry in the profile) to control both unauthorized enterprise and personal Microsoft account access.
Find your Tenant ID/Directory ID in the Azure/Entra portal. Verify header names and target domains against current Microsoft documentation, especially regarding V1 vs. V2 implementations.
SaaS Support & Headers - Google Workspace Headers
Google Workspace supports restriction via headers.
Header Name:
X-Goog-Allowed-Resources
(Recommended)
(Legacy name:
X-GooGApps-Allowed-Domains
- use value format below if using this)
Value Format (
X-Goog-Allowed-Resources
):
Comma-separated Google Workspace numeric **customer IDs** (e.g.,
C0123abcd,C9876zyxw
).
Value Format (
X-GooGApps-Allowed-Domains
):
Comma-separated allowed domain names (e.g.,
yourdomain.com,otherdomain.com
).
PAN-OS Profile Type:
Use **Custom Type**.
Target Domains:
Primarily
accounts.google.com
. PAN-OS docs also mention
*.google.com
and
gmail.com
for broader G Suite coverage. Verify with Google's current recommendations.
Use the `Custom` type. Prefer `X-Goog-Allowed-Resources` with Customer IDs per Google's recommendation. Ensure prerequisites like QUIC blocking and potential HTTP/2 handling are addressed.
SaaS Support & Headers - Dropbox & YouTube Examples
PAN-OS provides predefined types or guidance for other services:
Dropbox (Tenant Restriction):
Header Name:
X-Dropbox-allowed-Team-Ids
Value Format:
Comma-separated Dropbox Business Team IDs.
PAN-OS Profile Type:
Use **Predefined Type**
Dropbox
.
Requirement:
Requires enabling Network Control in Dropbox admin console. See
Dropbox documentation
.
Target Domains (Predefined):
*.dropbox.com
.
YouTube (Content Restriction):
Header Name:
YouTube-Restrict
Value Format:
Strict
or
Moderate
.
PAN-OS Profile Type:
Use **Predefined Type**
YouTube
.
Use the correct header for the intended purpose (tenant restriction vs. content filtering). Leverage Predefined types when available and applicable.
SaaS Support & Headers - Header Limits & Vendor Documentation
PAN-OS Header Limits:
Be aware of the character limits for HTTP header insertion in PAN-OS:
Header Name Length:
Max
100
characters.
Header Value Length:
Max
16,000
characters (16K).
These are generally sufficient, but verify if your SaaS provider uses exceptionally long header names or requires extremely long lists of IDs/domains in the value field.
Importance of Vendor Documentation:
Before configuring,
always consult the official documentation for the specific SaaS application
.
Verify the exact **Header Name(s)** (case sensitivity?).
Identify the specific **Target Domains** (login FQDNs).
Understand any **Limitations** or impacts (guest access, mobile apps).
Check for **Updates** (e.g., M365 V1 vs V2).
The SaaS vendor's documentation is the definitive source for tenant restriction header requirements.
Configuration Steps - Prerequisites (Decryption)
Key prerequisites must be met before configuring tenant restriction:
SSL Forward Proxy Decryption:
**(MANDATORY)**
Configure Decryption Profiles and Policies to successfully decrypt traffic to the specific SaaS **login domains** identified for the target application(s).
Deploy the firewall's forward trust certificate to client machines.
Address potential certificate pinning issues with appropriate exclusions if necessary (but note that excluded traffic cannot have headers inserted).
Identify SaaS Login Domains:
Obtain the list of FQDNs used during authentication from vendor documentation (e.g., `login.microsoftonline.com`, `accounts.google.com`, `login.live.com`).
Obtain Allowed Tenant Info:
Find your corporate Tenant ID(s), registered domain(s), or Customer ID(s) in the vendor-required format.
Network Path:
Ensure relevant user traffic routes through the PAN-OS firewall.
(If Google) Handle QUIC:
Create a high-priority Security rule to block the `quic` App-ID.
(If needed) Handle HTTP/2:
Consider enabling `Strip ALPN` in the relevant Decryption Profile if header insertion issues persist, particularly with Google.
PCNSE Relevance:
SSL Decryption configuration (policies targeting specific URLs/Categories, profiles, certificate handling) is essential. Understanding protocol dependencies (QUIC, HTTP/2) is also relevant.
Configure the profile under
Objects > Security Profiles > HTTP Header Insertion
.
Using Predefined Types (e.g., M365 Enterprise, YouTube, Dropbox):
This simplifies setup for common, known headers.
Click **Add** to create a new profile or edit an existing one.
Give the profile a **Name** (e.g., `Tenant-Restrictions-Profile`).
Inside the profile, click **Add** to create an entry.
Give the entry a **Name** (e.g., `TR-M365-Enterprise`).
Select the `User-Agent` tab for the entry.
Select the relevant **Type** from the dropdown (e.g., `Microsoft Office365 Tenant Restrictions`).
The `Domains` list and `Headers` section will pre-populate.
Fill in the required **Value(s)** for the pre-populated Headers based on vendor requirements (e.g., Allowed Tenant IDs for `Restrict-Access-To-Tenants`, Your Tenant ID for `Restrict-Access-Context`).
(Optional) Enable `Log`.
Click **OK** for the entry, then **OK** for the profile.
Using Custom Type (e.g., M365 Consumer, Google, Other SaaS):
Use this when no predefined type exists or for specific control.
Within the same or a new profile, click **Add** to create another entry.
Give the entry a **Name** (e.g., `TR-Google`, `TR-M365-Consumer`).
Select the `User-Agent` tab.
Select the **Type:** `Custom`.
In the `Domains` list, **Add** the specific SaaS login domain(s) for *this* specific restriction (e.g., `accounts.google.com`).
In the `Headers` list, click **Add**:
Enter the vendor-required header **Name** (e.g., `X-Goog-Allowed-Resources`).
Enter the required static **Value** (e.g., `YourGoogleCustomerID1`).
Repeat adding headers if needed for this entry.
(Optional) Enable `Log`.
Click **OK** for the entry, then **OK** for the profile.
A single HTTP Header Insertion Profile object can contain multiple entries, each targeting different domains with different headers (Predefined or Custom). Apply this single profile object to your Security Policy rule(s).
PCNSE Relevance:
Knowing how to configure both Predefined and Custom header entries within the HTTP Header Insertion profile object is key.
Apply the profile via a Security Policy rule (
Policies > Security
) specifically matching the login traffic.
Create or modify Security Policy rule(s). You might need distinct rules if decryption requirements or source users differ for various SaaS login domains.
Configure the rule match criteria:
Source:
Appropriate internal zones/users.
Destination Zone:
`untrust`.
Application:
Specific login App-IDs if accurate (e.g., `ms-entra-id`) or `ssl`.
Service/URL Category:
**CRITICAL:** Use a Custom URL Category or Address Objects containing **only the specific login FQDNs** targeted by the entries in your Header Insertion profile (e.g., `login.microsoftonline.com`, `accounts.google.com`, `login.live.com`).
Configure the **Actions** tab:
Action:
`Allow`.
Profile Setting:**
Type: `Profiles`
Select the **HTTP Header Insertion** profile object containing your tenant restriction entries.
Ensure **Decryption** is applied (either via Decryption Profile here, or ensure a matching Decryption Policy rule exists with Action=Decrypt).
Logging:
Enable 'Log at Session End'.
Click **OK** and **Commit**.
Applying the profile to rules matching broad App-IDs (like `google-drive`) or general web categories will likely fail or insert headers unnecessarily. Target only the specific login URLs/domains.
The primary verification goal is confirming that access to **unauthorized** tenants is blocked **by the SaaS provider**.
Testing Steps:
Test Allowed Tenant(s):
Log in to your sanctioned corporate SaaS tenant(s). This must succeed normally.
Test Disallowed Tenant(s):
**(Most Important)** Attempt to log in to a known disallowed tenant (personal account, different org) from a client subject to the policy.
Expected Result:
The SaaS provider should block the login and display their specific error message related to tenant restrictions or organizational policy. See example below.
Check Firewall Logs (Troubleshooting):
Traffic Log: Verify the login attempt hits the correct Security Rule and the action is 'allow'.
Decryption Log: Verify the session to the login domain was successfully 'decrypted'.
Packet Capture (Advanced):
Egress capture on the firewall during a disallowed login attempt can confirm the correct header *was inserted* by the firewall before being sent to the SaaS provider.
Example error message from Microsoft when Tenant Restriction blocks access.
Successful verification means the **SaaS provider blocks unauthorized logins**, not the firewall itself.
Configuration Steps - M365 Configuration Example Notes
This summarizes the configuration steps based on the provided Palo Alto Networks KCS article description (focused on V1 headers):
Decryption Policy:
Ensure a Decryption rule decrypts traffic (SSL Forward Proxy) to:
login.microsoftonline.com
login.microsoft.com
login.windows.net
login.live.com
(Using a Custom URL Category for these is recommended).
Example snippet of a Decryption Policy targeting login URLs.
Example M365 Consumer Header Configuration (Custom Type).
Example list showing both M365 entries in the profile.
(Note: The source images show configuration within a URL Filtering profile, which is the older method. Configure these entries within an HTTP Header Insertion profile object instead).
Security Policy:
Create a rule allowing traffic to the Microsoft login domains (using the Custom URL Category or Address Objects).
Apply the HTTP Header Insertion profile object created above.
Ensure Decryption is active for this rule.
Example snippet of a Security Policy allowing login traffic.
Example Security Policy Actions tab applying the profile.
Commit Changes.
Verify:
Test logins as described in the Verification section. Expect the Microsoft block page for disallowed tenants.
Advanced & PCNSE - Tenant Restriction vs. User Identity Headers
It's crucial to distinguish these two uses of HTTP Header Insertion:
Feature
Tenant Restriction Headers
User Identity Headers
Purpose
Inform SaaS provider which tenant(s) are allowed for login/access.
Inform downstream device (CASB, proxy, web app) who the user is.
Typical Header Name(s)
Defined by SaaS vendor (e.g., `Restrict-Access-To-Tenants`)
Custom or conventional (e.g., `X-Authenticated-User`)
Header Value Source
**Static** string (List of allowed Tenant IDs/Domains)
**Dynamic** value from User-ID mapping
Profile Header Type Used
**Custom** or **Predefined** (if available)
Username, Domain, User@Domain, Domain\User
Who Enforces?
The **SaaS Provider**
The **Downstream Device**
Primary Benefit
Prevent access to unauthorized SaaS tenants.
Enable user-aware logging/policy downstream.
Advanced & PCNSE - Limitations & Caveats
Tenant restriction via header insertion has limitations:
Requires SaaS Provider Support:
Only works if the vendor supports a specific header.
Decryption Dependency:
Always requires successful HTTPS decryption of login flows.
Configuration Precision:
Needs exact header names, values, and targeted domains.
Guest Access / B2B Impact:
Can block legitimate guest access to other tenants if those IDs aren't allowed. Test B2B scenarios carefully.
Non-Browser Clients:
May not work reliably for thick clients or mobile apps if they don't use standard web login flows or bypass decryption.
Maintenance:
Vendor requirements can change.
PAN-OS Header Limits:
Name (100 chars), Value (16K chars).
Troubleshooting:
Methodical diagnosis using logs and packet captures for features involving traffic modification and external dependencies.
Integration Awareness:
Knowing PAN-OS interacts with specific SaaS vendor requirements (e.g., M365/Google headers).
Focus on the interplay between Decryption, precise Policy targeting, and correct Profile configuration (especially Custom type with static values) for implementing specific SaaS controls.
Quiz: SaaS Tenant Restriction via Header Insertion
Test your understanding of using PAN-OS for SaaS Tenant Restriction.
