Configure O365

Prerequisites

To configure O365 apps in the Citrix Workspace app, make sure to complete the following:

  • If you have a primary domain available in Azure AD that is not federated with other services, you can use that domain to federate to Citrix Secure Private Access. Ensure that this domain, either the parent or the child domain of it is not already federated and the parent domain of it is not already added in the Azure Active Directory (AAD).

    For example, if your user login using user1@demo.citrix.com, then demo.citrix.com is primary domain, citrix.com is parent domain, and us.demo.citrix.com is child domain.

  • If you cannot federate the primary domain, add a new domain to Azure AD and federate it to Citrix Secure Private Access. Create the domain and complete the verification. For details, see https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/add-custom-domain.

    OR

    You can add a subdomain to Azure AD that can be leveraged to federate to Citrix Secure Private Access for SSO. For that, you must add and promote the subdomain to a root domain. For details, see https://docs.microsoft.com/en-us/azure/active-directory/enterprise-users/domains-verify-custom-subdomain.

    Note: You might need to use Azure AD Graph Explorer instead of Microsoft Graph Explorer for the POST request to change a subdomain to a root domain.

    For details on why you need a federated domain, see How domain federation works.

  • Confirm that the new domain or the subdomain that you have added is in the “Verified” state in the Azure AD.

  • Set up a trust between your SAML identity provider and Azure AD. To set up a trust, you must have a domain that is verified in AAD. When a federation is configured in AAD using a domain, AAD trusts the SAML provider for user authentication to AAD, even if the user is from a different domain than the federated domain. In the SP initiated flow when AAD must identify which IdP to use for authentication(accelerate user to federated IdP) it is identified using the whr query param or domain_hint passed to the URL https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-authentication-for-federated-users-portal.

    Adding a federation for a new domain does not impact an existing federation that you have in your setup. If you have ADFS already federated to a domain, it is not impacted as you are federating on a different domain that is neither sub domain or parent domain of an already federated domain.

    SSO can have the following two flows:

    IDP initiated flow: Typically used when you want to log in to the Azure AD portal. The Citrix Secure Private Access service posts the SAML assertion to the Azure AD (AAD). AAD validates it based on the federation setting that we did earlier. If the validation passes, it extracts the nameid attribute of SAML. The nameid attribute must match immutableId of the user which is present in the AAD.

    SP initiated flow: Typically used when you want to land to the app directly instead of the AAD portal. In this flow, the Citrix Secure Private Access service loads the URL that is configured in the app settings. The URL goes to AAD and because the URL has some indication of the federated domain, the user is redirected to the Citrix Secure Private Access service with a SAML request and a relay state. The Citrix Secure Private Access service posts the SAML assertion to AAD with the same relay state that came in the request. Once SAML is validated, AAD redirects a user to the context in the relay state and hence the user lands on the app directly.

  • Configure the O365 app in the Citrix Secure Private Access service. For details see Support for Software as a Service apps.

How domain federation works

The following figure illustrates a typical flow involved after a domain federation is complete.

How domain federation works

Consider that you want to add the Office 365 app into the Citrix Workspace and enable watermarking and restrict downloads. The typical flow is as follows:

  1. You launch the Office 365 app in the Citrix Workspace.
  2. The request goes to the Citrix Secure Private Access service.
  3. Citrix Secure Private Access service creates the SAML assertion and forwards it to Azure AD.
  4. As the request is coming from a trusted SAML IdP, Azure AD identifies it through the domain federation that is created and passes the SAML assertion to the Office 365 app.

    The Office 365 app is launched.

Authentication methods supported for the Office 365 app

By default, Citrix Cloud uses the Citrix identity provider to manage the identity information for all users in your Citrix Cloud account.

Citrix Workspace supports the following authentication methods for Office 365. Okta and Google IdP are not currently supported.

  • On-premises Active Directory
  • Active Directory plus Token
  • Azure Active Directory

    Note: If AAD is used to authenticate to the workspace, then you cannot federate the primary domain (user’s login domain) because this creates a loop. In such cases, you must federate a new domain

  • Citrix Secure Private Access
  • Active Directory plus RADIUS

For more details, see Identity and access management.

Configure the O365 app in the Secure Private Access service

The following are the high-level steps to configure the O365 app in the Secure Private Access service. For more details, see Support for Software as a Service app.

  1. Go to the Secure Private Access service in Citrix Cloud.
  2. Search for Office 365 and choose the Office365 template. For details on configuring an app using the template, see Support for Software as a Service apps.

    Note:

    Once you select the Office365 template, the following related domains are autopopulated in the App Details section.

    • *.office.com
    • *.office365.com
    • *.sharepoint.com
    • *.live.com
    • *.onenote.com
    • *.microsoft.com
    • *.powerbi.com
    • *.dynamics.com
    • *.microsoftstream.com
    • *.powerapps.com
    • *.yammer.com
    • *.windowsazure.com
    • *.msauth.net
    • *.msauthimages.net
    • *.msocdn.com
    • *.microsoftonline.com
    • *.windows.net
    • *.microsoftonline-p.com
    • *.akamaihd.net
    • *.sharepointonline.com
    • *.officescriptsservice.com
    • *.live.net
    • *.office.net
    • *.msftauth.net
  3. Enable enhanced security controls, if needed.
  4. Configure SSO.

    Note: The only change you must do is to make sure “Name ID” is the Active Directory GUID.

  5. Ensure that advanced attributes also send IDPEmail.
    • Attribute Name: IDPEmail
    • Attribute Format: Unspecified
    • Attribute Value: Email
  6. Click SAML metadata to open in a new tab.
    • Copy “entityID”
    • Copy “Login URL”
    • Download the Certificate in CRT format

Configure domain federation from Azure AD to Citrix Workspace

Prerequisites:

  • Enable PowerShell in Azure AD
  • Install Microsoft MSOnline module

The following are the PowerShell commands to install the required modules.

`PS> Install-Module AzureAD -Force`

`PS> Import-Module AzureAD -Force`

`PS> Install-Module MSOnline -Force`

`PS> Import-module MSOnline -Force`
<!--NeedCopy-->

If the modules are already installed, then run the following command.

PS> connect-msolservice
<!--NeedCopy-->

Note: A Microsoft cloud account is required to connect to msolservice. For example, admin.user@onmicrosoft.com

Steps to configure domain federation from Azure AD to Citrix Workspace

  1. Run the following commands in the PowerShell to configure the federation:

    • PS> $dom = "ad-domain.com"

    Note: ad-domain.com is the new domain added to Azure AD

    • PS> $IssuerUri = "https://citrix.com/[customerID]"

    Note: The customerID can be found from the following locations:

    • Citrix Cloud > Identity and Access Management > API Access
    • Citrix Cloud > Citrix Secure Private Access. the customer ID can be found in the app configuration details (Single sign > SAML Metadata file > entityID).

    • PS> $fedBrandName = “CitrixWorkspace”
    • PS> $logoffuri = "https://app.netscalergateway.net/cgi/logout"
    • PS> $uri = "https://app.netscalergateway.net/ngs/[customerID]/saml/login?APPID=[AppID]”

    Note: $uri can be copied from Citrix Secure Private Access Service > Add a Web/SaaSApp > Single sign on > Login URL or from SAML Metadata > Location.

    • PS> $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(“<location of certificate downloaded from Citrix Secure Private Access service/filename.crt>”)

      For example: PS> $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\cert\saml_idp.crt")

    PS> $certData = [system.convert]::tobase64string($cert.rawdata)

  2. Run the PS string to complete the Federation to Citrix Secure Private Access:

    PS> Set-MsolDomainAuthentication -DomainName $dom –federationBrandName $fedBrandName -Authentication Federated -PassiveLogOnUri $uri -LogOffUri $logoffuri -SigningCertificate $certData -IssuerUri $IssuerUri -PreferredAuthenticationProtocol SAMLP

  3. Verify domain federation settings by running the following command:

    Get-MsolDomainFederationSettings -DomainName <domain name>

Federation setting validation

Automated domain federation from Azure AD to Citrix Workspace

In the manual domain federation from Azure AD to Citrix Workspace as explained in the section Configure domain federation from Azure AD to Citrix Workspace, users have to switch between cloud portal and PowerShell to copy data and run the scripts. For example;

  • Copy data, such as customer ID and app ID from the cloud portal.
  • Download the certificate from the cloud portal.
  • Run the PowerShell scripts.

This manual copy-paste action might introduce errors because of which the federation might not be successful.

The steps to federate a domain are now integrated within the Citrix Secure Private service user interface making the federation process automated. The PowerShell scripts are run in the back end when users click the appropriate links in the interface. Users do not have to switch between cloud portal and PowerShell.

Steps to federate a domain automatically

  1. Configure the O365 app. For details, see Configure the O365 app in the Secure Private Access service.
  2. In Single sign on, select SAML.

    Domain federation in user interface

  3. Log on to Azure AD using your credentials. When you click Log in to Azure AD, you are directed to the Azure AD logon portal for authentication.
    • OAuth protocol is used for authentication. After the authentication is successful, you must provide consent for federating the domain.
    • Select end user MFA option is enabled, by default.
  4. Click Click here to retrieve Azure AD Domains to view the list of all domains.
  5. Select the domain that you want to federate and click Federate domain.

    Note:

    • When you click Federate domain, the PowerShell scripts are run in the back end and the domain is federated.
    • You can also download the PowerShell scripts, if necessary, from the interface. In Domain federation PowerShell script, click Download.

Suppress multifactor authentication (MFA)

An option is added to the advanced attributes of O365 apps that suppresses MFA when the user has already entered the MFA during user authentication to Citrix Workspace.

  • Attribute Name:http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod”,
  • Attribute Value:http://schemas.microsoft.com/claims/multipleauthn

For the AAD to accept this claim, federate using the following PowerShell command:

Set-MsolDomainAuthentication -DomainName $dom –federationBrandName $fedBrandName -Authentication Federated -PassiveLogOnUri $uri -LogOffUri $logoffuri -SigningCertificate $certData -IssuerUri $IssuerUri -PreferredAuthenticationProtocol SAMLP -SupportsMfa $true

Note:

IdP initiated flow does not honor relay state. Use SP initiated flow to land on the app directly.

Configuring individual Office suite applications in Citrix Workspace

Perform the following to configure individual office suite applications:

  1. Complete the domain federation as detailed in previous sections.
  2. Choose the O365 template.
  3. Change the name of the app to, for example, MS Word.
  4. Change the app URL to accordingly.

Word: https://login.microsoftonline.com/login.srf?wa=wsignin1%2E0&rver=6%2E1%2E6206%2E0&wreply=https%3A%2F%2Fwww.office.com%2Flaunch%2FWord%3Fauth%3D2&whr=<federated domain>

Powerpoint: <https://login.microsoftonline.com/login.srf?wa=wsignin1%2E0&rver=6%2E1%2E6206%2E0&wreply=https%3A%2F%2Fwww.office.com%2Flaunch%2Fpowerpoint%3Fauth%3D2&whr=<federated domain>

Excel: https://login.microsoftonline.com/login.srf?wa=wsignin1%2E0&rver=6%2E1%2E6206%2E0&wreply=https%3A%2F%2Fwww.office.com%2Flaunch%2FExcel%3Fauth%3D2&whr=<federated domain>

CRM/Dynamics Online: https://<tenant>.crm.dynamics.com/?whr=<federated domain>

OneDrive for Business: https://login.microsoftonline.com/login.srf?wa=wsignin1%2E0&rver=6%2E1%2E6206%2E0&wreply=https%3A%2F%2F<tenant>-my.sharepoint.com%2F&whr=<federated domain>

Outlook Calendar: https://outlook.office.com/owa/?realm=<federated domain>&path=/calendar/view/Month

Outlook Web Access to Exchange Online: https://outlook.com/owa/<federated domain>

SharePoint Online: https://login.microsoftonline.com/login.srf?wa=wsignin1%2E0&rver=6%2E1%2E6206%2E0&wreply=https%3A%2F%2F<tenant>.sharepoint.com%2F&whr=<federated domain>

Teams: https://login.microsoftonline.com/common/oauth2/authorize?client_id=cc15fd57-2c6c-4117-a88c-83b1d56b4bbe&response_mode=form_post&response_type=code+id_token&scope=openid+profile&redirect_uri=https%3a%2f%2fteams.microsoft.com%2f&domain_hint=<federated domain>

Third party apps integrated into Azure AD

If you have integrated third party applications like Box, Salesforce, ServiceNow, Workday, you can obtain the Smart Links for these apps from the Azure AD.

Perform the following steps.

  1. Log in to your Azure AD Portal https://portal.azure.com.

  2. Select All Services > Azure Active Directory, and select your directory.

    Select all services

  3. Select Enterprise Applications and then choose the application you want to generate a Smart Link to.

    Select enterprise applications

  4. Select Properties and copy the User access URL.

    Select properties

  5. After you append whr to the URL, the whr parameters appear as shown in the example URL.

    Example URL: https://myapps.microsoft.com/signin/Workday/1234567891234567891234567896d64b&whr=ctxnsqa.net

    Note: Append whr to the URL so that AAD knows which IdP to use to authenticate a user based on federation setting and auto redirect to that IdP.

  6. Set enhanced security controls.
  7. Configure SSO.
    • Name ID = AD GUID
    • Enable SP-initiated checkbox
    • Assertion URL = Login URL

      When you perform an IdP initiated flow, users are redirected to the Azure AD portal page. If you want to land directly on the app page, then SP initiated flow is needed as it sends the correct relay state in the SAML assertion.

Note:

  • When federation of the primary domain is enabled, all AAD users are redirected to Citrix Workspace when authenticating to any Office 365 applications. This might cause an outage/incident for customers if done without understanding the impact.
  • If users log on to Citrix Workspace using AAD, then the primary domain of the users that is used to log in must not be federated to the Citrix Gateway service. This results in a loop. In such cases, use another domain different from the domains of users login to AAD to federate to the Citrix Secure Private Access service.

  • If the primary domain is federated to the Citrix Secure Private Access service, then all user logins on that domain in AAD are redirected to the Citrix Secure Private Access service. For POC, if needed, you can federate a test domain before federating the primary domain.
  • If AAD has the location policy turned on, users must be from the list of allowed IP addresses of a corporate network only. In such cases, you can publish the O365 app as a Web app and route its traffic via the Connector Appliance.
  • When logging on to the AAD, if you want to avoid the Stay signed in? prompt, you can change this setting by using the AAD. Note the important message that appears when you change the setting and revert if necessary.

Select stay signed in

Message when reverting the setting

Azure PowerShell Module Reference

Azure PowerShell Command Reference

Deploy Office 365 Directory Synchronization in Microsoft Azure