Problem
You need to federate your Office 365 domain with PortalGuard for Single Sign-On.
...
IMPORTANT NOTE - If you have multiple Office 365 domains and wish to federate them with a single PortalGuard instance, then you must use PG_IdP.dll version v5.4.0.4 or later. Microsoft's Set-MsolDomainAuthentication PowerShell cmdlet is used to federate Office 365 domains but it does not allow more than one domain to be federated to the same “Issuer” value. The newer version of PortalGuard works around this limitation by allowing the “Issuer” value returned in SAML to be overridden at the Relying Party level. Please see the instructions below for more details.
Users will only be able to access ONE O365 Domain in this scenario, as this setup requires the use of an ACL on each configuration that is mutually exclusive.
Access by Outlook Clients and Mobile Apps
...
You must be using PortalGuard version 5.2.0.0 or later (released in August 2015).
The server name used to reach the PortalGuard server (e.g. “logon.acme.com”) must be resolvable in public and private DNS and be reachable by both internet and LAN-based users.
The PortalGuard IIS website must use a SSL certificate issued by a trusted Certificate Authority (e.g. Digicert, Verisign).
The User Search Filter must allow users to authenticate to PortalGuard using their full email address. This change must be made in both the User Repository through PG_Config and the Attribute Store through IdP_Config. To allow users to logon with either sAMAccountName or email address, the following User Search Filter can be used:
(&(|(sAMAccountName={USER})(mail={USER}))(objectclass=person))
The HTTPS/SSL port on the PortalGuard IIS website must be the “default” SSL site. The HTTPS binding cannot use a specific hostname. Windows Server 2012 and later allows Server Name Indication (SNI) to host multiple HTTPS sites on the same port. However, some mobile devices are not SNI-capable so they are not be able to connect to the PortalGuard server. On Win2012 and up, the Require Server Name Indication setting also must not be enabled. The screenshot below shows the two settings that cannot be used if you wish to support all client devices.
If IIS on your Windows 2012 server or later has a potential configuration HTTPS issue, you may also see this warning in IIS Manager.
...
.
Procedure
The name of the new Office 365 domain is highlighted in the steps below as “portalguard.us”. Replace this with the name of your own domain.
On PortalGuard server
Launch Identity Provider Configuration Editor (IdP_Config.exe)
On the top-level Attribute Stores tab, create an Attribute Store for your local Active Directory domain/forest. This will match nearly all the settings from the User Repository configuration in PG_Config.exe.
On the “SAML Websites” tab, create a new Relying Party configuration.
Go to the WS-Fed tab and click the Office 365 button. This will set nearly all of the fields for you. The settings you must manually change are:
On the Identity Claims tab, choose the “Attribute Store” configuration that points to your Active Directory
On the IdP-Initiated tab, choose an appropriate Display Image if users will be using the PortalGuard SSO jump page.
Also on the IdP-Initiated tab, the “Default URL” should be changed to a “smart link” to improve the user experience. You should be able to use the following format:
https://www.outlook.com/owa/YOUR.DOMAIN
This works in later revisions of Office 365. If it does not, follow the instructions from Using smart links or IdP initiated authentication with Office 365 to determine & build the appropriate URL.
If you are federating multiple Office 365 domains, enter a unique Issuer value in the “Override IdP Issuer” field on the Response tab, e.g.:
org.acme.sso.mySecondDomain
This value must match what is provided to our “federate-office365.ps1” PowerShell script in the next section.
If you are not federating multiple Office 365 domains, then leave this field blank in the configuration.
Click the Save button to commit the changes to the Relying Party configuration
Apply the changes to the IdP using the button with red text
Launch a text editor such as Notepad++ (link) as an administrator
Open the root PortalGuard web.config file (found in C:\InetPub\PortalGuard)
Search for the “httpErrors” element. It should look like this initially:
In the image above, remove the XML comments at the beginning (“”) of line 115. This is the line that contains the word PassThrough. These two subtractions are shown in pink highlight in the image above and are marked with the numbers 1 and 2.
Using the line numbers in the previous image, add a new XML comment (“”) at the very end of line 128. The resulting file section should now look like below with the two additions shown in green highlight and marked with the numbers 1 and 2:
Save and close the file
Launch an administrative command prompt and run the command: iisreset
On the “DirSync” Active Directory Domain Controller
Copy the PortalGuard IdP signing certificate to the server, e.g. C:\PGIdP.cer
Copy the _Optional\Office365 folder from the PortalGuard kit to the DC. This folder contains PowerShell scripts such as federate-office365.ps1 and backup-ADFS-Fed-Settings.ps1.
Launch Windows Azure Active Directory Module for Windows PowerShell. This shortcut to PowerShell should have been installed while configuring Directory Synchronization.
Change directory using the “cd” command to the _Optional\Office365 folder copied over in the previous step.
Connect to Microsoft Online using the command below. Enter an Office 365 administrator username and password when prompted:
Connect-MsolService
If the target Office 365 domain currently set to “Managed” authentication, then skip the remainder of this step. If the domain is already federated with your local ADFS, then run following PowerShell command to save the current ADFS settings to a local XML file if you need to revert back to them:
.\backup-ADFS-Fed-Settings.ps1
The settings will be saved in adfs-fed-settings.xml in the current directory.
NOTE: If you receive an error about script execution, run the following command to fix it for this prompt:
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
You must also revert the domain back to a “Managed” domain temporarily. Use the following PowerShell command:
Set-MsolDomainAuthentication -Authentication Managed
Enter your domain name when prompted (as shown below):
You are now ready to attempt federation with PortalGuard. Type the command below and hit Enter:
.\federate-office365.ps1
IMPORTANT NOTE: If you receive an error about script execution, run the following command to fix it for this prompt:
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
The PowerShell script will prompt for the following:
The full Office 365 domain name to federate, e.g.:
portalguard.us
The full base URL of your PortalGuard server (without a path), e.g.:
The full URL where users are redirected after signing out of Office 365 in a browser:
IMPORTANT NOTE: If this URL is a server other than PortalGuard, a new value must be added in C:\InetPub\PortalGuard\web.config using the “<add>” element:
If you are federating a single Office 365 domain, then use the Issuer value from the Response tab in the General IdP Settings. The screenshot below shows where to find this:
If you are federating a second Office 365 domain, then use the value you put in the “Override IdP Issuer” field in the Relying Party configuration in step 5 of the previous PortalGuard Configuration section.
IMPORTANT NOTE: This Issuer value must contain any domain name specific to your environment, e.g. “your.domain/idp”. Office 365 requires all Issuer values to be globally unique across the world so you cannot use a generic value like “PortalGuard” or “IdP”. If you must change this value in PortalGuard’s General IdP Settings, be sure to notify any other Service Providers you may have already federated with -OR- change the corresponding SP-side configurations if you have access.
The full file path to the signing certificate used by the PortalGuard IdP. This was copied to the current server in step #1 above:
C:\PGIdP.cer
The image below shows an example run of the federate-office365.ps1 script. When this script is finished, it runs the Get-MsolDomain and Get-MsolDomainFederationSettings commands for the provided domain for confirmation. It should show “Federated” in the Authentication column if the conversion was successful.
NOTE: If you have already federated an Office 365 domain with PortalGuard, then running the federation script a second time with the same settings will result in an “Unable to convert the domain. The settings you selected are already in use.” error.
This occurs because Office365 requires ALL “Issuer” values in the world to be unique. So when you run the federate-office365.ps1 PowerShell script for the additional domain, be sure to use all the same settings except use the “Override IdP Issuer” value you entered in the PortalGuard Relying Party configuration in step 5 of the previous section.
Example:
Initial IdP Issuer | org.acme.sso |
Second IdP Issuer | org.acme.sso.mySecondDomain |
Third IdP Issuer | org.acme.sso.myThirdDomain |
Enabling OAuth for Outlook and Mobile App Access (July 2019)
...
After these steps, if a user goes directly to Office 365 using http://portal.microsoftonline.com or https://outlook.office365.com, they will be redirected to your PortalGuard server login page after entering their email address/username. They will typically see a transient message about this redirection as shown below.
...
IMPORTANT NOTE: You can skip this redirection altogether by directing users to use the following URL (swap in your own Office 365 domain where shown):
...
Launch a Windows Powershell on the AD domain controller with DirSync installed and run the following commands:
Change directory using the “cd” command to the _Optional\Office365 folder in the PortalGuard kit.
Connect to Microsoft Online using the command below. Enter an Office 365 administrator username and password when prompted:
Connect-MsolService
Enter the command below and enter the Office 365 domain name when prompted:
.\ restore-ADFS-Fed-Settings.ps1
IMPORTANT NOTE: The script will fail if the “adfs-fed-settings.xml” file is not found in the current directory.