/Office365-PacUtil

Primary LanguageC#MIT LicenseMIT

Proxy Auto Configuration (PAC) File Utility for Office 365

This utility interacts with the Office 365 IP Address and URL web service, which helps you better identify and differentiate Office 365 network traffic, making it easier for you to evaluate, configure, and stay up to date with changes.

The intention of the tool is to provide a custom proxy.pac template file which has been setup for your network.

Requirements

Getting started

  1. Download the release and unzip to a folder on your computer.
  2. Open up File Explorer and navigate to the folder where you extracted the zip file contents.
  3. Open up the appsettings.json file and review the configuration and replace the ClientRequestId value with a unique GUID for your machine.
  4. Update your custom proxy.pac file template with the token marker defined in configuration. For example, /// Office 365 PAC Data /// would be added to the template file and this is what's replaced.
  5. You can check for updates by running the following command: 
    .\Office365.PacUtil.exe pac-file update-check
  6. Run the following command to generate the PAC file and update your template file: 
    .\Office365.PacUtil.exe pac-file generate --file "proxy-template.pac"
  7. Optionally, you can force the file generation even if no changes were detected by running the following command: 
    .\Office365.PacUtil.exe pac-file generate --file "proxy-template.pac" --force
  8. The generated output will be located in your USERS TEMP directory. C:\Users\{username}\AppData\Local\Temp\PacUtil\proxy.pac

Configuration

The following is the configuration found in the appsettings.json file.

  "Office365IpUrlWebService": {
    "ClientRequestId": "GENERATE_YOUR_UNIQURE_GUID",
    "TemplateFileTokenStartMarker": "/// START Office 365 PAC Data ///",
    "TemplateFileTokenEndMarker": "/// END Office 365 PAC Data ///",
    "WebServiceRootUrl": "https://endpoints.office.com",
    "VersionPath": "PacUtil\\O365_endpoints_latestversion.json",
    "DataPath": "PacUtil\\O365_endpoints_data.json",
    "Instance": "Worldwide",
    "IncludeIPv6": false
  }

  • ClientRequestId = < guid > - A required GUID that you generate for client association. Generate a unique GUID for each machine that calls the web service. GUID format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x represents a hexadecimal number. You can use https://guidgenerator.com/ to generate one.

  • TemplateFileTokenMarker - The token marker to insert into your PAC file template which is replaced by the content generated from this tool.

  • VersionPath - This is the path and filename to store the latest version from the Office 365 IP and Url Web Service. The version value in this file is based on the format of YYYYMMDDNN, where NN is a natural number incremented if there are multiple versions required to be published on a single day, with 00 representing the first update for a given day.

  • DataPath - This is the path and filename to store the latest data from the Office 365 IP and Url Web Service, which is then used to generate the final output.

  • Instance = < Worldwide | China | USGovDoD | USGovGCCHigh > - The short name of the Office 365 service instance.

  • IncludeIPv6 = < true | false > - Set the value to true to exclude IPv6 addresses from the output if you don't use IPv6 in your network. Default is false.

Template

Here is a snippet of how you would incorporate this into your proxy template file.

function FindProxyForURL(url, host)
{
    // ...
	

    // Office 365
	if (
            (
		        shExpMatch(host, "127.0.0.1")
		    ) &&
		    (

/// START Office 365 PAC Data ///

 /// Generated content goes here

/// END Office 365 PAC Data ///
				
			)
	    )
    {
        return direct;
    }


	// ...
}

The following is the output file which replaces the token in the template:

function FindProxyForURL(url, host)
{
    // ...
	

    // Office 365
	if (
            (
                // Example of something else from local/network:
		        shExpMatch(host, "127.0.0.1")
		    ) &&
		    (

/// START Office 365 PAC Data ///
// Microsoft 365 URLs and IP address data version: 2024013000
// URL to compare version 2024013000 with the latest: https://endpoints.office.com/changes/Worldwide/2024013000?clientrequestid=635f7b4a-ad6c-4ff2-bf39-756935dff84c

                // Event ID 1 - Exchange
                shExpMatch(host, "outlook.office.com") ||
                shExpMatch(host, "outlook.office365.com") ||

                isInNet(myIpAddress(),"13.107.6.152","255.255.255.254") ||
                isInNet(myIpAddress(),"13.107.18.10","255.255.255.254") ||
                isInNet(myIpAddress(),"13.107.128.0","255.255.252.0") ||
                isInNet(myIpAddress(),"23.103.160.0","255.255.240.0") ||
                isInNet(myIpAddress(),"40.96.0.0","255.248.0.0") ||
                isInNet(myIpAddress(),"40.104.0.0","255.254.0.0") ||
                isInNet(myIpAddress(),"52.96.0.0","255.252.0.0") ||
                isInNet(myIpAddress(),"131.253.33.215","255.255.255.255") ||
                isInNet(myIpAddress(),"132.245.0.0","255.255.0.0") ||
                isInNet(myIpAddress(),"150.171.32.0","255.255.252.0") ||
                isInNet(myIpAddress(),"204.79.197.215","255.255.255.255") ||

                // Event ID 2 - Exchange
                shExpMatch(host, "outlook.office365.com") ||
                shExpMatch(host, "smtp.office365.com") ||

                isInNet(myIpAddress(),"13.107.6.152","255.255.255.254") ||
                isInNet(myIpAddress(),"13.107.18.10","255.255.255.254") ||
                isInNet(myIpAddress(),"13.107.128.0","255.255.252.0") ||
                isInNet(myIpAddress(),"23.103.160.0","255.255.240.0") ||
                isInNet(myIpAddress(),"40.96.0.0","255.248.0.0") ||
                isInNet(myIpAddress(),"40.104.0.0","255.254.0.0") ||
                isInNet(myIpAddress(),"52.96.0.0","255.252.0.0") ||
                isInNet(myIpAddress(),"131.253.33.215","255.255.255.255") ||
                isInNet(myIpAddress(),"132.245.0.0","255.255.0.0") ||
                isInNet(myIpAddress(),"150.171.32.0","255.255.252.0") ||
                isInNet(myIpAddress(),"204.79.197.215","255.255.255.255") ||

                // Event ID 8 - Exchange
                shExpMatch(host, "*.outlook.com") ||
                shExpMatch(host, "autodiscover.*.onmicrosoft.com") ||

                // ...

/// END Office 365 PAC Data ///

			)
	    )
    {
        return direct;
    }


	// ...
}

References

Office 365 IP Address and URL web service