PoC Guide: Secure Access to Office 365 with Citrix Secure Private Access
As users access confidential content within Microsoft 365 (Office 365), organizations must be able to simplify user login operations while still enforcing authentication standards. Organizations must be able to secure Microsoft 365 even though it exists beyond the confines of the data center. Citrix Workspace provides organizations with enhanced security controls for Microsoft 365.
In this scenario, a user authenticates to Citrix Workspace using either Active Directory as the primary user directory.
If the Citrix Secure Private Access service is assigned to the Citrix subscription, enhanced security policies, ranging from applying screen-based watermarks, restricting printing/downloading actions, screen grabbing restrictions, keyboard obfuscation, and protecting users from untrustworthy links, are applied on top of the Microsoft 365 applications.
The following animation shows a user accessing Microsoft 365 with SSO and secured with Citrix Secure Private Access.
This demonstration shows an IdP-initiated SSO flow where the user launches the application from within Citrix Workspace. This PoC guide also supports an SP-initiated SSO flow where the user tries to access the SaaS app directly from their preferred browser.
This proof of concept guide demonstrates how to:
- Setup Citrix Workspace
- Integrate a primary user directory
- Incorporate Single Sign-On for SaaS applications
- Define website filtering policies
- Validate the configuration
Setup Citrix Workspace
The initial steps for setting up the environment is to get Citrix Workspace prepared for the organization, which includes
- Setting up the Workspace URL
- Enabling the appropriate services
- Connect to Citrix Cloud and log in as your administrator account
- Within Citrix Workspace, access Workspace Configuration from the upper-left menu
- From the Access tab, enter a unique URL for the organization and select Enabled
From the Service Integration tab, enable the following services to support the secure access to SaaS apps use case.
- Secure Private Access
- Secure Browser
Citrix Workspace takes a few moments to update services and URL settings. From a browser, verify that the custom Workspace URL is active. However, logon will be available once a primary user directory gets defined and configured.
Integrate a Primary User Directory
Before users can authenticate to Workspace, a primary user directory must be configured. The primary user directory is the only identity the user requires as all requests for apps within Workspace utilize single sign-on to secondary identities.
An organization can use any one of the following primary user directories with Microsoft 365:
- Active Directory: To enable Active Directory authentication, a cloud connector must be deployed within the same data center as an Active Directory domain controller by following the Cloud Connector Installation guide.
- Active Directory with Time-Based One Time Password: Active Directory-based authentication can also include multifactor authentication with a Time-based One Time Password (TOTP). This guide details the required steps to enable this authentication option.
Azure Active Directory: Users can authenticate to Citrix Workspace with an Azure Active Directory identity. This guide details the required steps to enable this authentication option.
When using AAD as your primary authentication directory, you cannot federate the primary domain (user’s login domain) because this creates a loop. In such cases, you must federate a new domain.
AAD user accounts must have the attribute
immutableIDset; otherwise, the authentication will fail with the error message: AADSTS51004
Azure AD Connect synchronized accounts get this attribute set automatically.
- Citrix Gateway: Organizations can utilize an on-premises Citrix Gateway to act as an identity provider for Citrix Workspace. This guide provides details on the integration.
- Okta: Organizations can use Okta as the primary user directory for Citrix Workspace. This guide provides instructions for configuring this option.
Federate Azure Authentication to Citrix Workspace
To successfully federate Microsoft 365 with Citrix Workspace, the administrator needs to do the following:
- Configure SaaS App
- Authorize SaaS App
- Verify Authentication Domain
- Configure Domain Federation
With the domain verified within Azure, a Microsoft 365 SaaS app can get configured within Citrix Workspace.
- Within Citrix Cloud, select Manage from the Secure Private Access tile.
- Within Secure Private Access menu, select Applications
- In the Application section, select Add an app
- In the Choose a template wizard, select Office 365
- Select Next
- In the App details section, change the Name, Icon, and Description as needed while leaving all remaining entries unchanged.
Note: You can also route the traffic through the Connector Appliance deployed in your data center. Therefore you need to switch from “Outside my corporate network” to “Inside my corporate network”.
- Select Next
- In the Single Sign-On window, verify the Name ID Format=Persistent and Name ID=Active Directory GUID (1)
- Under Advanced attributes, verify Attribute Name=IDPEmail, Attribute Format=Unspecified, and Attribute Value=Email (2)
The second Advanced attribute option is added automatically to suppress the MFA authentication request when the user has already entered the MFA during user authentication to Citrix Workspace.
For Azure AD to accept this claim, we must add a parameter
-SupportsMfa $truewhen setting up the domain federation.
There are two options to proceed, manual or automated domain federation configuration.
If you want to use the automated process (PowerShell script), go to the section Automated domain federation configuration.
- Select Download to capture the CRT-based certificate. (3)
- Next to the Login URL, select the Copy button to capture the Login URL. This URL gets used later. (4)
- Select the SAML Metadata link (5)
- Within the SAML Metadata file, look for EntityID. Please copy the entire URL and store it for later use. Once captured, the SAML Metadata file can be closed.
- Select Next
- Skip the next section and proceed with Applications - App Connectivity
- Select Log in to Azure AD, a new tab opens, and you are directed to the Azure AD portal for authentication. (3)
- Specify a user account that has “Global Administrator” permissions assigned.
- You should see the following message if the login was successful
- Select end user MFA option is enabled, by default.
- Click Click here to retrieve Azure AD domains to view the list of all domains. (4)
- Select the domain that you want to federate from the drop-down list. (5)
- Click Federate domain (6)
- When you click Federate domain, the PowerShell scripts are running in the back end, and the domain is federated.
- If necessary, download the PowerShell scripts from the interface. In Domain federation PowerShell script, enter the Azure AD Domain (7) and click Download (8).
- Select Next
- In the App Connectivity window, verify how the traffic should be routed (in this case, direct from the client to the SaaS application)
- Select Next
- Select Finish to complete the configuration of the Microsoft Office 365 SaaS apps.
- Within Secure Private Access menu, select Access Policies
- In the Access Policy section, select Create policy
- In the Applications drop-down list, search for “Office365” and select it.
- Add the appropriate users/groups who are authorized to launch the app
- Specify if the app can be accessed with or without enhanced security.
The above screenshot has no enhanced security configured.
If enhanced security is needed, change “Allow access” to “Allow with restrictions” and enable all that should apply.
Note: For initial SSO testing, it is always a good idea to configure enhanced security with the option “Open in remote browser” set.
Azure must verify the fully qualified domain name to federate authentication to Citrix Workspace. Within the Azure Portal, do the following:
- Access Azure Active Directory
- Select Custom domain names in the navigation window
- Select Add custom domain
- Enter the fully qualified domain name
- Select Add domain
- Azure provides records to incorporate into your domain name registrar. Once done, select Verify.
- Once complete, the domain contains a verified mark
The final configuration is to have Azure use Citrix Workspace as the federated authority for the verified domain. Configuring federation must be done with PowerShell.
- Launch PowerShell
- Add the appropriate modules with the following commands
Install-Module AzureAD -Force Import-Module AzureAD -Force Install-Module MSOnline -Force Import-module MSOnline -Force <!--NeedCopy-->
- Connect to Microsoft Online via PowerShell and authenticate using a Microsoft cloud account (e.g.,
- Verify the domain is currently set to Managed within Azure by running the following PowerShell command
- Use the following code in a PowerShell script to make this domain Federated by changing the variables to align with your environment
$dom = "workspaces.wwco.net" # The fully qualified domain name verified within Azure $fedBrandName = "CitrixWorkspaceSAMLIdP" # A name to help remember the configuration purpose $uri = "https://app.netscalergateway.net/ngs/[entityID]/saml/login?APPID=[APPID]" # The Login URL from the Office365 app configuration $logoffuri = "https://app.netscalergateway.net/cgi/logout" # Standard entry for all. Do not change $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("<location of certificate downloaded from Citrix Secure Private Access service/filename.crt>") # Path to the downloaded certificate file from Office 365 app configuration (e.g., C:\temp\filename.crt) $certData = [system.convert]::tobase64string($cert.rawdata) $IssuerUri = "https://citrix.com/[entityID]" # The entityID taken from the Office365 app configuration SAML Metadata file Set-MsolDomainAuthentication ` -DomainName $dom ` –federationBrandName $fedBrandName ` -Authentication Federated ` -PassiveLogOnUri $uri ` -LogOffUri $logoffuri ` -SigningCertificate $certData ` -IssuerUri $IssuerUri ` -PreferredAuthenticationProtocol SAMLP To suppress an MFA authentication request when the user has already entered the MFA during user authentication to Citrix Workspace, use the following command: Set-MsolDomainAuthentication ` -DomainName $dom ` –federationBrandName $fedBrandName ` -Authentication Federated ` -PassiveLogOnUri $uri ` -LogOffUri $logoffuri ` -SigningCertificate $certData ` -IssuerUri $IssuerUri ` -PreferredAuthenticationProtocol SAMLP ` -SupportsMfa $true <!--NeedCopy-->
- Verify the domain is currently set to Federated within Azure by running the following PowerShell command
- Verify the federation settings in Azure by running the following PowerShell command
Get-MsolDomainFederationSettings -DomainName $dom <!--NeedCopy-->
If the federation settings need to be removed, run the following PowerShell command:
Set-MsolDomainAuthentication -DomainName $dom -Authentication Managed
- Log into Citrix Workspace as a user
- Select the Office365 application
- Observe the URL to see it briefly redirect through Azure
- The Office365 portal successfully launches
- Launch a browser
- Go to the company-defined URL for the SaaS application
- The browser redirects to Azure Active Directory and then to Citrix Workspace for authentication
- Once the user authenticates with the primary user directory, the SaaS app launches with Citrix providing single sign-on
Define website filtering policies
Citrix Secure Private Access provides website filtering within SaaS and Web apps to help protect users from phishing attacks. The following shows how to set up website filtering policies.
- From Citrix Cloud, Manage within the Secure Private Access tile
- If this guide was followed, the Set up end-user authentication step and the Configure end-user access to SaaS, web and virtual applications steps are complete. Select Settings
- Switch to the tab Web Filtering
- Select Edit
- Enable the Filter website categories option
- Within the Blocked categories box, select Add
- Select the categories to block users from accessing
- When all applicable categories are selected, select Add
- Do the same for allowed categories
- Do the same for redirected categories. These categories redirect to a Secure Browser instance
- If needed, admins can filter denied, allowed, and redirected actions for specific URLs following the same process used for defining categories. Website URLs take precedence over categories.
Validate the Configuration
- Log into Citrix Workspace as a user
- Select Office365.
If enhanced security is disabled, the app launches within the local browser. Otherwise, the enterprise browser is used.
- The user automatically signs on to the app
- The appropriate enhanced security policies are applied
- If configured, select a URL within the SaaS app that is in the blocked, allowed, and redirected categories
- If configured, select a URL within the SaaS app that is in the blocked, allowed, and redirected URLs
- The SaaS App successfully launches
- Launch a browser
- Go to the Office 365 website and select Sign In
- Enter the user name
- The browser redirects the browser to Citrix Workspace for authentication
- Once the user authenticates with the primary user directory, Office365 launches in the local browser if enhanced security is disabled.
If enhanced security is enabled, a Secure Browser instance launches Office365.
Microsoft 365 Related Domains
A related domain field is available when creating a new app within Citrix Secure Private service. The enhanced security policies utilize these related domains to determine when to enforce the policy.
The following list are the current domains associated with Microsoft 365 apps.
Note: These domains can change at any time
Microsoft 365 Apps
Suppose it is preferable to launch a specific Microsoft 365 app (Word, PowerPoint, or Excel) instead of the Microsoft 365 portal. In that case, the administrator must create a separate application instance within Citrix Secure Private Access service for each app. Each app has a unique URL, which must include the correct value for the federated domain configured in this guide. The federated domain entry informs Azure to redirect to the correct federated domain configuration.
Note: IdP-initiated flow does not honor the relay state. Use SP-initiated flow to land on the app directly.
- CRM/Dynamics Online:
- OneDrive for Business:
- Outlook Calendar:
- Outlook Web Access to Exchange Online:
- SharePoint Online:
Stay Signed In
In the default configuration, Azure Active Directory displays a dialog box during the logon process allowing the users to remain signed in.
This is an Azure setting that can be easily changed by doing the following:
- Within Azure, select Azure Active Directory
- Select Company Branding
- Select the enabled Locale
- In the Edit company branding pane, select No in the Show option to remain signed in
- Select Save
When trying to launch Microsoft 365, the user might receive the following error:
AADSTS51004: The user account "account name" does not exist in the "GUID" directory. To sign into this application, the account must be added to the directory.
The following are suggestions on how to solve this issue:
- Verify that the user is licensed to use Microsoft 365 within the Microsoft 365 administrator console
- Verify that the identified email address within the error matches the primary user directory, Azure Active Directory, and Microsoft 365.
Verify that the attribute
immutableIdis set at the user object.
(This is not the case in pure AAD environments!)
immutableIdcan be easily calculated and set using the following PowerShell commands:
$userUPN="firstname.lastname@example.org" #change the userPricipalName before executing Install-Module AzureAD -Force Import-Module AzureAD -Force Install-Module MSOnline -Force Import-module MSOnline -Force Connect-MsolService $userObjectID=(Get-MsolUser -UserPrincipalName $userUPN).objectId $userImmutableId=[System.Convert]::ToBase64String([System.Guid]::New($userObjectID).ToByteArray()) Set-MsolUser -UserPrincipalName $userUPN -ImmutableId $userImmutableId <!--NeedCopy-->
During validation, a user might receive the following error:
AADSTS50107: The requested federation realm object 'https://<ADFShostname>/adfs/services/trust' does not exist.
This is often caused by the domain not being verified or properly federated. Review the following sections of the PoC guide:
Users might experience enhanced security policy (watermark, printing, or clipboard access) failure. Typically, this happens because the SaaS application uses multiple domain names. Within the application configuration settings for the SaaS app, there was an entry for Related Domains.
The enhanced security policies are applied to those related domains. The Microsoft 365 Related Domains section of this PoC guide contains the initial set of related domains, which Microsoft can change at any time.
A related domain still needs to be added if the enhanced security policies fail to function within certain app sections. To identify missing domain names, an administrator can access the SaaS app with a local browser and do the following:
- Navigate to the section of the app where the policies fail
- In Google Chrome and Microsoft Edge (Chromium version), select the three dots in the upper right side of the browser to show a menu screen.
- Select More Tools.
- Select Developer Tools
- Within the developer tools, select Sources. This provides a list of access domain names for that application section. To enable the enhanced security policies for this portion of the app, those domain names must be entered into the related domains field within the app configuration. Related domains are added like the following
In this article
- Setup Citrix Workspace
- Integrate a Primary User Directory
- Federate Azure Authentication to Citrix Workspace
- Define website filtering policies
- Validate the Configuration
- Microsoft 365 Related Domains
- Microsoft 365 Apps
- Stay Signed In