PortalGuard Support for Office 365

Problem

You need to federate your Office 365 domain with PortalGuard for Single Sign-On.

Solution

PortalGuard supports federation with Office 365.

How to Federate Office 365 with PortalGuard

An up-to-date version of this walkthrough can always be found in the PortalGuard Admin Guide, Located HERE

Prerequisites

Directory synchronization from your local AD domain to Azure AD in the cloud must be correctly configured. Please see the Microsoft TechNet article, Prepare for directory synchronization, for more information.

IMPORTANT NOTE: The “password synchronization” DirSync option is not required for SSO to work correctly. Password synchronization is now supported by Microsoft for federated accounts so you can enable it if you wish (see the May 5, 2014 update at this link).

The Office 365 domain marked as the “default” (e.g. company.onmicrosoft.com) cannot be federated for SSO purposes. You must have created a new domain and associated user accounts with it. Please see the article Add your domain to Office 365 or use the Add Domain wizard within the Office 365 Administrator portal for more information. If the new, custom domain you want to federate is currently set as the default, you must set a different domain as the default. Please see this Office 365 forum post for details on how to do this.
You must create and maintain a separate Office 365 administrator account that resides in your onmicrosoft.com domain. This is important to ensure that you can undo domain federation if you encounter a problem. This backup account must NOT be under a custom/vanity domain that can be federated – it must be in the onmicrosoft.com domain which Microsoft does not allow to be federated.

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

If your organization accesses Office 365 using Outlook clients or the native email app on mobile devices like iOS, Android, then the following pre-requisites also apply to support these “active” clients:

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.:
  - https://malt.pistolstar.com
- The full URL where users are redirected after signing out of Office 365 in a browser:
  - http://your.main.portal
- 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)

By default, Office 365 may not be configured to allow federated SSO for the Outlook desktop app or mobile apps. After following all the steps above, if browser-based SSO works but Outlook access displays a popup authentication dialog (instead of your PG website's login page), then please follow the steps below to address this. These steps are largely taken from Microsoft's own Office 365: Enable Modern Authentication wiki.

1) Set “OAuth2ClientProfileEnabled” to $True via PowerShell Launch an administrative PowerShell prompt and run the following commands: Connect to Exchange Online using Powershell (three (3) commands):

$ExchOnlineCred = Get-Credential
$ExchOnlineSession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.outlook.com/PowerShell -Credential $ExchOnlineCred -Authentication Basic -AllowRedirection
Import-PSSession $ExchOnlineSession -AllowClobber | Out-Null

Check whether or not Modern Authentication is enabled on the actual Exchange Online tenant:

Get-OrganizationConfig | ft OAuth*

Enable Modern Authentication if the above returns ‘false’

Set-OrganizationConfig -OAuth2ClientProfileEnabled $True

Please note, this change may take some time to replicate through Microsoft's environment.

Verification

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):

https://www.outlook.com/owa/YOUR.DOMAIN

This will take the users directly to your PortalGuard server’s logon screen.

If you use “active” clients like Microsoft Outlook or native mobile email apps, they can be added as per Microsoft’s documentation.

Troubleshooting

If the steps above succeeded but users are not able to access their Office 365 email, please run Microsoft’s Connectivity Analyzer: https://testconnectivity.microsoft.com/

Choose the Office 365 tab and the Office 365 Single Sign-On Test radio button then click Next.

Enter the email address of a test account in your domain and its password. Leave the “Windows Azure Active Directory (default)” radio button checked. Check the “I understand…” checkbox, answer the CAPTCHA below it and click the Perform Test button.

The test will either succeed or fail. If it fails, you can expand the top-level “Test Steps” element to see which step failed.

If you need help interpreting the results, use the Copy To Clipboard icon in the upper right corner to copy all the results and email them to us at techsupport@portalguard.com.

Reverting to Prior ADFS Federation

If your Office 365 domain had been federated with ADFS before attempting to federate it with PortalGuard, then you should be able to easily revert back to using ADFS if you backed up the ADFS federation settings as described in the steps above. The ADFS settings are stored in adfs-fed-settings.xml in the _Optional\Office365 folder you copied to the DirSync domain controller.

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.