Last active
August 19, 2018 13:33
-
-
Save jhochwald/111e12a88ed1f8d2e00ddd5562ba57be to your computer and use it in GitHub Desktop.
Get the Office 365 Endpoint Information from Microsoft via the new RestFull Webservice (JSON)
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
#requires -Version 3.0 | |
<# | |
.SYNOPSIS | |
Get the Office 365 Endpoint Information from Microsoft via the new RestFull Webservice (JSON) | |
.DESCRIPTION | |
Microsoft updates the Office 365 IP address and FQDN entries at the end of each month and occasionally out of the cycle for operational or support requirements. | |
This function uses the new JSON based Webserice instead of the old XML based one; the XML based service will be retired soon by Microsoft. | |
The Function will compare the last downloaded version with the latest available online version, if there is no update available, the function does nothing. If there is an update, the function will do what you told it to. If you want to enforce the download, just delete the O365_endpoints_*_latestversion.txt in your $Env:TEMP Directory. The * is a placeholder, for the Instance name. | |
.PARAMETER Instance | |
The short name of the Office 365 service instance. | |
Valid: Worldwide, USGovDoD, USGovGCCHigh, China, Germany | |
The default is: Worldwide | |
.PARAMETER Services | |
Valid items are All, Common, Exchange, SharePoint, Skype. | |
Because Common service area items are a prerequisite for all other service areas it is included every time - Adopted that from the Microsoft Statement; nevertheless, we disagree with the selection of Microsoft. There are way to many endpoints included here! | |
The default is: All | |
.PARAMETER Tenant | |
Your Office 365 tenant name. | |
The web service takes your provided name and inserts it in parts of URLs that include the tenant name. | |
If you don't provide a tenant name, those parts of URLs have the wildcard character (*). | |
.PARAMETER NoIPv6 | |
Query string parameter. Set this to true to exclude IPv6 addresses from the output, for example, if you don't use IPv6 in your network. | |
The default is FALSE | |
.PARAMETER ExpressRoute | |
Only display endpoints that could be routed over ExpressRoute. | |
Default is: FALSE - All endpoints will be exported | |
.PARAMETER Category | |
The connectivity category for the endpoint set. | |
Valid values are: All, Optimize, Allow, and Default. | |
Default is: 'All' | |
.PARAMETER Required | |
This endpoint set is required to have connectivity for Office 365 to be supported. | |
Default is: FALSE | |
.PARAMETER Output | |
What to return? | |
Values are: All, IPv4, IPv6, URLs | |
Default is: All | |
.EXAMPLE | |
PS C:\> .\Get-Office365Endpoints.ps1 | |
It gets the International (Worldwide) Office 365 URLs, IPv4, and IPv6 address ranges. | |
.EXAMPLE | |
PS C:\> .\Get-Office365Endpoints.ps1 -Instance Germany | |
It gets the Office 365 Germany URLs, IPv4 address ranges. It would also return IPv6, but IPv6 is not supported, at least not yet. | |
.EXAMPLE | |
PS C:\> .\Get-Office365Endpoints.ps1 -Instance Germany -Category Optimize | |
It gets the Office 365 Germany URLs, IPv4 address ranges. Only in the category 'Optimize'. It would also return IPv6, but IPv6 is not supported, at least not yet. | |
.EXAMPLE | |
PS C:\> .\Get-Office365Endpoints.ps1 -Instance Worldwide -Services Exchange -Required | |
It gets the International (Worldwide) Office 365 URLs, IPv4, and IPv6 address ranges for Exchange and everything to be supported (includes CDNs and other, even external, services). | |
.EXAMPLE | |
PS C:\> .\Get-Office365Endpoints.ps1 -Instance Worldwide -Services Exchange -Required -Tenant 'contoso' | |
It gets the International (Worldwide) Office 365 URLs, IPv4, and IPv6 address ranges for Exchange and everything to be supported (includes CDNs and other, even external, services); this example includes URLs for the tenant with the Name 'contoso'. | |
The Tenant based URLs are generated and not checked, so please make sure you use the correct name! | |
.EXAMPLE | |
PS C:\> ((.\Get-Office365Endpoints.ps1 -Instance Worldwide -Services Exchange -Tenant 'kreativsign' -Output URLs -Required).url | Sort-Object -Unique) -join "," | Out-String | |
It gets the International (Worldwide) Office 365 URLs, IPv4, and IPv6 address ranges for Exchange and everything to be supported (includes CDNs and other, even external, services); this example includes URLs for the tenant with the Name 'contoso'. | |
The Tenant based URLs are generated and not checked, so please make sure you use the correct name! ! | |
It just dumps the URLs in a comma separated (CSV) format. Useful for Proxy Servers. | |
.EXAMPLE | |
PS C:\> (((.\Get-Office365Endpoints.ps1 -Instance Worldwide -Services Exchange -Output IPv4) | Where-Object -FilterScript {$_.tcpPorts -eq '587'}).ip | Sort-Object -Unique) -join "," | Out-String | |
It gets the International (Worldwide) Office 365 IPv4 addresses for Exchange Submission (SMTP) Servers who use Port 587. It dumps a comma separated (CSV) format. Useful for Firewalls. | |
.EXAMPLE | |
PS C:\> (((.\Get-Office365Endpoints.ps1 -Instance Worldwide -Services Exchange -Output IPv6) | Where-Object -FilterScript {$_.tcpPorts -eq '25'}).ip | Sort-Object -Unique) -join "," | Out-String | |
It gets the International (Worldwide) Office 365 IPv4 addresses for Exchange SMTP Servers who use Port 25. It dumps a comma separated (CSV) format. Useful for Firewalls. | |
.EXAMPLE | |
PS C:\> (((.\Get-Office365Endpoints.ps1 -Instance Worldwide -Services Exchange -Output URLs) | Where-Object -FilterScript {$_.notes -like '*Exchange Hybrid Configuration Wizard*' }).url | Sort-Object -Unique) -join "," | Out-String | |
Get a List of Exchange Online URLs that you might need if you want to run the Exchange Hybrid Configuration Wizard. | |
.EXAMPLE | |
PS C:\> ((.\Get-Office365Endpoints.ps1 -Instance Worldwide -Output 'IPv4' -ExpressRoute).ip | Sort-Object -Unique) -join "," | Out-String | |
Get a List of IPv4 addresses for ExpressRoute configuration. | |
.EXAMPLE | |
PS C:\> ((.\Get-Office365Endpoints.ps1 -Instance Worldwide -Output 'IPv6' -ExpressRoute).ip | Sort-Object -Unique) -join "," | Out-String | |
Get a List of IPv6 addresses for ExpressRoute configuration. Please note: IPv6 is not supported with ExpressRoute in every Instance, (example: Germany) | |
.EXAMPLE | |
PS C:\> ((.\Get-Office365Endpoints.ps1 -Instance Worldwide -NoIPv6).ip | Sort-Object -Unique) -join "," | Out-String | |
Get a list of IP addreses and exclude IPv6. The benefit of this parameter is the NoIPv6 parameter: The call will exclude the IPv6 Data from the response, and that might be smarter than filter it. It might be handy if you do NOT use IPv6 within your network - If this is the case, you might miss the future of networking! Think about that, before ignoring IPv6. | |
.NOTES | |
Initial Version that uses the new Microsoft Service. A few things are still missing or not rock solid. | |
However, we needed a solution to configure ExpressRoute now, so we started with some rework to use the new Webservice. | |
This function is part of the commercial en.Office365 PowerShell Module - Distributed separately as OpenSouce with a very flexible license (See below) | |
Some parts of the script are based upon the example that Microsoft published on the info page of the new Webservice! | |
.LINK | |
https://github.com/jhochwald/PowerShell-collection/blob/master/Office365/Get-Office365Endpoints.ps1 | |
.LINK | |
https://hochwald.net/powershell-get-the-office-365-endpoint-information-from-microsoft/ | |
.LINK | |
https://hochwald.net/powershell-function-to-get-the-office-365-urls-and-ip-address-ranges/ | |
.LINK | |
https://support.office.com/en-us/article/managing-office-365-endpoints-99cab9d4-ef59-4207-9f2b-3728eb46bf9a#webservice | |
.LINK | |
https://techcommunity.microsoft.com/t5/Office-365-Blog/Announcing-Office-365-endpoint-categories-and-Office-365-IP/ba-p/177638 | |
#> | |
[CmdletBinding()] | |
[OutputType([psobject])] | |
param | |
( | |
[Parameter(ValueFromPipeline = $true, | |
ValueFromPipelineByPropertyName = $true)] | |
[ValidateNotNullOrEmpty()] | |
[ValidateSet('Worldwide', 'USGovDoD', 'USGovGCCHigh', 'China', 'Germany', IgnoreCase = $true)] | |
[string] | |
$Instance = 'Worldwide', | |
[Parameter(ValueFromPipeline = $true)] | |
[ValidateNotNullOrEmpty()] | |
[ValidateSet('All', 'Common', 'Exchange', 'SharePoint', 'Skype', IgnoreCase = $true)] | |
[Alias('ServiceAreas')] | |
[string] | |
$Services = 'All', | |
[Parameter(ValueFromPipeline = $true)] | |
[Alias('TenantName')] | |
[string] | |
$Tenant = $null, | |
[Parameter(ValueFromPipeline = $true)] | |
[switch] | |
$NoIPv6, | |
[Parameter(ValueFromPipeline = $true)] | |
[switch] | |
$ExpressRoute, | |
[ValidateSet('All', 'Optimize', 'Allow', 'Default', IgnoreCase = $true)] | |
[string[]] | |
$Category, | |
[Parameter(ValueFromPipeline = $true)] | |
[switch] | |
$Required, | |
[Parameter(ValueFromPipeline = $true)] | |
[ValidateSet('All', 'IPv4', 'IPv6', 'URLs', IgnoreCase = $true)] | |
[string] | |
$Output = 'All' | |
) | |
begin | |
{ | |
#region MakeIPv6Plausible | |
if (($NoIPv6) -and ($Output -eq 'IPv6')) | |
{ | |
# This makes no sense, and we totally ignore to do it! | |
Write-Error -Message 'The selected parameters make no sense; we cannot continue!' -ErrorAction Stop | |
# We should never reach this point! | |
Break | |
} | |
#endregion MakeIPv6Plausible | |
#region CategoryTweaker | |
if ((! $Category) -or ($Category -eq 'All')) | |
{ | |
# Set to all | |
$Category += 'Optimize', 'Allow', 'Default' | |
} | |
#endregion CategoryTweaker | |
#region TweakOutputHandler | |
# TODO: Make a simpler solution for that! | |
switch ($Output) | |
{ | |
'All' | |
{ | |
$outIPv4 = $true | |
$outIPv6 = $true | |
$outURLs = $true | |
} | |
'IPv4' | |
{ | |
$outIPv4 = $true | |
$outIPv6 = $false | |
$outURLs = $false | |
} | |
'IPv6' | |
{ | |
$outIPv4 = $false | |
$outIPv6 = $true | |
$outURLs = $false | |
} | |
'URLs' | |
{ | |
$outIPv4 = $false | |
$outIPv6 = $false | |
$outURLs = $true | |
} | |
} | |
#endregion TweakOutputHandler | |
#region ConfigurationVariables | |
# Webservice root URL | |
$BaseURI = 'https://endpoints.office.com' | |
# Path where client ID and latest version number will be stored | |
# TODO: Move the Location wo a parameter | |
$datapath = $Env:TEMP + '\O365_endpoints_' + $Instance + '_latestversion.txt' | |
#endregion ConfigurationVariables | |
#region LocalVersionChecker | |
# fetch client ID and version if data file exists; otherwise create new file | |
if (Test-Path -Path $datapath) | |
{ | |
# Read the File | |
$content = (Get-Content -Path $datapath) | |
# Get the Info | |
$clientRequestId = $content[0] | |
$lastVersion = $content[1] | |
# Cleanup | |
$content = $null | |
} | |
else | |
{ | |
# Create a GUID | |
$clientRequestId = [GUID]::NewGuid().Guid | |
# Dummy Data | |
$lastVersion = '0000000000' | |
# Save the local info | |
try | |
{ | |
@($clientRequestId, $lastVersion) | Out-File -FilePath $datapath -ErrorAction Stop | |
} | |
catch | |
{ | |
# Write the complete error if we have verbose turned on | |
Write-Verbose -Message $_ | |
# Our Error test | |
Write-Error -Message ('Unable to write Datafile: {0}' -f $datapath) -ErrorAction Stop | |
# We should never reach this point! | |
Break | |
} | |
} | |
#region LocalVersionChecker | |
#region RemoteVersionChecker | |
# Call version method to check the latest version, and pull new data if version number is different | |
try | |
{ | |
$GetVersionParams = @{ | |
Uri = ($BaseURI + '/version/' + $Instance + '?clientRequestId=' + $clientRequestId) | |
Method = 'Get' | |
ErrorAction = 'Stop' | |
WarningAction = 'SilentlyContinue' | |
} | |
$version = (Invoke-RestMethod @GetVersionParams) | |
} | |
catch | |
{ | |
# Write the complete error if we have verbose turned on | |
Write-Verbose -Message $_ | |
# Our Error test | |
Write-Error -Message 'Unable to get the new Office 365 Endpoint Information' -ErrorAction Stop | |
# We should never reach this point! | |
break | |
} | |
#endregion RemoteVersionChecker | |
} | |
process | |
{ | |
#region VersionCompare | |
if ($version.latest -gt $lastVersion) | |
{ | |
Write-Verbose -Message ('New version of Office 365 {0} endpoints detected' -f $Instance) | |
# Write the new version number to the data file | |
try | |
{ | |
@($clientRequestId, $version.latest) | Out-File -FilePath $datapath -ErrorAction Stop | |
} | |
catch | |
{ | |
# Write the complete error if we have verbose turned on | |
Write-Verbose -Message $_ | |
# Our Error test | |
Write-Error -Message ('Unable to write Datafile: {0}' -f $datapath) -ErrorAction Stop | |
# We should never reach this point! | |
Break | |
} | |
#endregion VersionCompare | |
#region GetTheEndpoints | |
try | |
{ | |
# Set the default URI | |
$requestURI = ($BaseURI + '/endpoints/' + $Instance + '?clientRequestId=' + $clientRequestId) | |
switch ($Services) | |
{ | |
'All' | |
{ | |
# We get all | |
} | |
'Common' | |
{ | |
# Append to the URI | |
$requestURI = ($requestURI + '&ServiceAreas=Common') | |
} | |
'Exchange' | |
{ | |
# Append to the URI | |
$requestURI = ($requestURI + '&ServiceAreas=Exchange') | |
} | |
'SharePoint' | |
{ | |
# Append to the URI | |
$requestURI = ($requestURI + '&ServiceAreas=SharePoint') | |
} | |
'Skype' | |
{ | |
# Append to the URI | |
$requestURI = ($requestURI + '&ServiceAreas=Skype') | |
} | |
} | |
if ($Tenant) | |
{ | |
# Append to the URI - Build URL for the Tenant | |
$requestURI = ($requestURI + '&TenantName=' + $Tenant) | |
} | |
if ($NoIPv6) | |
{ | |
# Append to the URI - Exclude IPv6 addresses from the output | |
$requestURI = ($requestURI + '&NoIPv6') | |
Write-Verbose 'IPv6 addresses are excluded from the output! IPv6 is the future, think about an adoption soon.' | |
} | |
# Do our job and get the data via Rest Request | |
Write-Verbose -Message ('We request the following URI: {0}' -f $requestURI) | |
$endpointSetsParams = @{ | |
Uri = $requestURI | |
Method = 'Get' | |
ErrorAction = 'Stop' | |
WarningAction = 'SilentlyContinue' | |
} | |
$endpointSets = (Invoke-RestMethod @endpointSetsParams) | |
} | |
catch | |
{ | |
# Write the complete error if we have verbose turned on | |
Write-Verbose -Message $_ | |
# Our Error test | |
Write-Error -Message 'Unable to get the new Office 365 Endpoint Information' -ErrorAction Stop | |
# We should never reach this point! | |
break | |
} | |
#endregion GetTheEndpoints | |
#region FilterURLs | |
if ($outURLs) | |
{ | |
$flatUrls = $endpointSets | ForEach-Object -Process { | |
$endpointSet = $_ | |
$urls = $(if ($endpointSet.urls.Count -gt 0) | |
{ | |
$endpointSet.urls | |
} | |
else | |
{ | |
@() | |
} | |
) | |
# Cleanup | |
$urlCustomObjects = @() | |
if ($endpointSet.category -in ($Category)) | |
{ | |
$urlCustomObjects = $urls | ForEach-Object -Process { | |
# Ordered is slower, but we like it this way | |
[PSCustomObject][ordered]@{ | |
id = $endpointSet.id | |
serviceArea = $endpointSet.serviceArea | |
DisplayName = $endpointSet.serviceAreaDisplayName | |
url = $_ | |
tcpPorts = $endpointSet.tcpPorts | |
udpPorts = $endpointSet.udpPorts | |
expressRoute = $endpointSet.expressRoute | |
category = $endpointSet.category | |
required = $endpointSet.required | |
notes = $endpointSet.notes | |
} | |
} | |
} | |
# Only ExpressRoute enabled Objects? | |
if ($ExpressRoute) | |
{ | |
$urlCustomObjects = $urlCustomObjects | Where-Object -FilterScript { | |
$urlCustomObjects.expressRoute -eq $true | |
} | |
} | |
# Only required to have connectivity for Office 365 to be supported | |
if ($Required) | |
{ | |
$urlCustomObjects = $urlCustomObjects | Where-Object -FilterScript { | |
$urlCustomObjects.required -eq $true | |
} | |
} | |
# Dump | |
$urlCustomObjects | |
} | |
} | |
#endregion FilterURLs | |
#region FilterIPv4 | |
if ($outIPv4) | |
{ | |
$flatIpv4 = $endpointSets | ForEach-Object -Process { | |
$endpointSet = $_ | |
$ips = $(if ($endpointSet.ips.Count -gt 0) | |
{ | |
$endpointSet.ips | |
} | |
else | |
{ | |
@() | |
} | |
) | |
# IPv4 strings have dots while IPv6 strings have colons | |
$IPv4 = $ips | Where-Object -FilterScript { | |
$_ -like '*.*' | |
} | |
# Cleanup | |
$ipCustomObjects = @() | |
if ($endpointSet.category -in ($Category)) | |
{ | |
$ipCustomObjects = $IPv4 | ForEach-Object -Process { | |
# Ordered is slower, but we like it this way | |
[PSCustomObject][ordered]@{ | |
id = $endpointSet.id | |
serviceArea = $endpointSet.serviceArea | |
DisplayName = $endpointSet.serviceAreaDisplayName | |
ip = $_ | |
tcpPorts = $endpointSet.tcpPorts | |
udpPorts = $endpointSet.udpPorts | |
expressRoute = $endpointSet.expressRoute | |
category = $endpointSet.category | |
required = $endpointSet.required | |
notes = $endpointSet.notes | |
} | |
} | |
} | |
# Dump | |
$ipCustomObjects | |
} | |
} | |
#endregion FilterIPv4 | |
#region FilterIPv6 | |
if ($outIPv6) | |
{ | |
$flatIpv6 = $endpointSets | ForEach-Object -Process { | |
$endpointSet = $_ | |
$ips = $(if ($endpointSet.ips.Count -gt 0) | |
{ | |
$endpointSet.ips | |
} | |
else | |
{ | |
@() | |
} | |
) | |
# IPv4 strings have dots while IPv6 strings have colons | |
$IPv6 = $ips | Where-Object -FilterScript { | |
$_ -like '*:*' | |
} | |
# Cleanup | |
$ipCustomObjects = @() | |
if ($endpointSet.category -in ($Category)) | |
{ | |
$ipCustomObjects = $IPv6 | ForEach-Object -Process { | |
# Ordered is slower, but we like it this way | |
[PSCustomObject][ordered]@{ | |
id = $endpointSet.id | |
serviceArea = $endpointSet.serviceArea | |
DisplayName = $endpointSet.serviceAreaDisplayName | |
ip = $_ | |
tcpPorts = $endpointSet.tcpPorts | |
udpPorts = $endpointSet.udpPorts | |
expressRoute = $endpointSet.expressRoute | |
category = $endpointSet.category | |
required = $endpointSet.required | |
notes = $endpointSet.notes | |
} | |
} | |
} | |
# Dump | |
$ipCustomObjects | |
} | |
} | |
#endregion FilterIPv4 | |
} | |
} | |
end | |
{ | |
if ($version.latest -gt $lastVersion) | |
{ | |
#region DumpIPv4 | |
if ($outIPv4) | |
{ | |
Write-Verbose -Message 'Office 365 IPv4 IP Address Ranges' | |
($flatIpv4 | Sort-Object -Property id) | |
} | |
#endregion DumpIPv4 | |
#region DumpIPv6 | |
if ($outIPv6) | |
{ | |
Write-Verbose -Message 'Office 365 IPv6 IP Address Ranges' | |
($flatIpv6 | Sort-Object -Property id) | |
} | |
#endregion DumpIPv6 | |
#region DumpURLs | |
if ($outURLs) | |
{ | |
Write-Verbose -Message 'Office 365 URLs' | |
($flatUrls | Sort-Object -Property id) | |
} | |
#endregion DumpURLs | |
} | |
else | |
{ | |
#region DumpInfo | |
Write-Output -InputObject 'Office 365 worldwide commercial service instance endpoints are up-to-date' | |
#endregion DumpInfo | |
} | |
} | |
<# | |
CHANGELOG: | |
0.8.2 - 2018-08-19: | |
[ADD] Regions added to make the code more readable within code editors | |
[FIX] A few typos in the descriptions where fixed - No change to any code or logic | |
0.8.1 - 2018-08-19: | |
[FIX] Add missing OutputType | |
[CHANGE] datafile name tweaked | |
[ADD] Missing NoIPv6 switch funtion implemented | |
[ADD] New Example for NoIPv6 switch | |
[ADD] A few more links | |
[ADD] Info about the datafile | |
[ADD] Embed a few things as comment - Due to the separation from the Module | |
[ADD] This changelog within the code - Reflect the changes within the dedicated function | |
0.8.0 - 2018-08-18: | |
[INIT] Intitial public release | |
#> | |
<# | |
LICENSE: | |
Copyright 2018 by enabling Technology - http://enatec.io | |
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: | |
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. | |
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. | |
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. | |
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
By using the Software, you agree to the License, Terms and Conditions above! | |
#> | |
<# | |
DISCLAIMER: | |
- Use at your own risk, etc. | |
- This is a third-party Software! | |
- The developer of this Software is NOT sponsored by or affiliated with Microsoft Corp (MSFT) or any of its subsidiaries in any way | |
- The Software is not supported by Microsoft Corp (MSFT)! | |
- By using the Software, you agree to the License, Terms and Conditions above! | |
#> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment