Citrix ADC as initial IdP for Office365

This article is about setting up SAML authentication for Office365 through the Citrix ADC (version 12). The Citrix ADC serves as IdP and Office365 as SP. So that you do not have to enter your user name a hundred times, this is prevented by an initial IdP (SSO).

Terminology

In short, the important upcoming terms explained.

SAML

SAML (Security Assertion Markup Language) provides a common platform for web-based access to multiple, autonomous services without the need to reenter multiple credentials. Authentication takes place via an encrypted session cookie, transparent in the background. This session cookie, which is provided with an expiration date, is given to the user in the browser by an authentication service (Identity Provider – IdP) and can then subsequently use all connected services (Service Provider – SP) in the browser.

Principal

The principal is the actual user who authenticates himself via the browser.

Identity Provider (IdP)

The identity provider is the authentication service that provides a login mask to the user and then forwards the principal to the service provider.

SingleSignOnService

The SingleSignOnService is a URL used to log in to the identity provider. The identity provider offers a login mask for authentication. It can be a username and password, but it may also require a different form of authentication including multi-factor authentication. This link must be entered in all connected services (SP).

SingleLogoutService

The SingleLogoutService URL is used to log out of the IdP. When a principal signs off from a service, it should be routed to that endpoint of the identity provider so that they can log off the user too. This link can be registered with all connected service providers.

Public Certificate

The identity provider offers a public certificate, with which the service provider signs the saml:authnRequest. Therefore, this certificate must be made available to all connected services.

Metadata File

An XML file provided by the identity provider. This file contains the above content (SingleSignOnService URL, SingleLogoutService URL, Public Certificate). This file can be made available to all connected services.

Service Provider (SP)

The service provider (e.g., Office365) provides services that require authentication. However, he does not undertake this authentication himself, but forwards it transparently to the identity provider.

AssertionConsumerService

This URL specifies the location where the user should be returned after he has authenticated. This link must be entered at the identity provider.

SingleLogoutService

The SingleLogoutService URL is used to log off the other connected services if the user has been logged off from a service. This means that the identity provider sends a logout request to service 1 as soon as the user has logged out of service 2. The prerequisite for this is that the SingleLogoutService URL has been entered in advance at the Identity Provider for Service 1.

Sequence of a SAML authentication

1. The user accesses a resource of a service provider per URL (e.g. https://portal.office.com)
2. The service provider forwards the unauthenticated user to the identity provider via saml:authnRequest.
3. The identity provider points to its SingleSignOnService URL (e.g., https://auth.deyda.net/saml/login) and the user must authenticate.
4. The IdP checks the entered credentials against the User Database (e.g. Active Directory).
5. And sends a message about successful verification to the IdP.
6. The IdP sends a saml:response in the form of an XHTML form back to the SP. This XHTML form contains, among other things, the AssertionConsumerService URL, which is automatically opened for the user.

Setup SAML authentication

In my guide, I’m assuming a SAML authentication between the Citrix ADC (formerly NetScaler) Version 12 and Office365.

Requirements

I assume the following things and do not go into detail about them:

• Citrix ADC with successful base configuration and installed Enterprise or Platinum license
• Internal and external DNS entries for AAA-vServer (e.g., auth.deyda.net) and Unified Gateway-vServer (e.g., citrix.deyda.net)
• Certificates for DNS entries (wildcard certificates are the easiest)
• Configured Unified Gateway vServer
• Existing Office365 subscription with base configuration (domain, AAD sync)

Citrix ADC

First, create an Authentication LDAP Server, as well as an LDAP policy to connect to your local AD. Of course you can also extend an existing LDAP server with the required parameters.

• Click in the Citrix ADC Navigation Panel NetScaler Gateway > Policies > Authentication > LDAP
• In the Policies tab click on Add, to create a new LDAP policy
• Give this policy a name (e.g., Office365_LDAP_SSO_Policy) and click Add next to the Server drop-down menu to create a new server (Alternatively, select your existing server and go to Edit to customize it)

• In the following window you create the LDAP server:
  • Name (e.g. Office365_LDAP_SSO_Server)
  • Server IP (Checked)
  • IP Address (internal Active Directory Server)
  • Base DN (OU of the User Accounts)
  • Administrator Bind DN (FQDN of an administrative account)
  • Administrator Password / Confirm Administrator Password (Password of the administrative account)
  • Test LDAP Reachability (With configured Connection Settings, a test connection to the AD can be established here)

• Under Other Settings:
  • Server Logon Name Attribute (sAMAccountName)
  • Group Attribute (memberOf)
  • Sub Attribute Name (cn)
  • SSO Name Attribute (UserPrincipalName)
  • Email (mail)
  • User Required (Checked)
  • Referrals (Checked)

• Click on More to expand the view
  • Attribute 1 (mail)
  • Attribute 2 (objectGUID)

• Use Create to complete the setting of the LDAP server
• In the window Create Authentication LDAP Policy select the currently created/edited LDAP Server
• Under Expression enter NS_TRUE

• Use Create to complete the creation of the LDAP policy

Then the actual SAML authentication (identity provider) is set up.

• For this we navigate NetScaler Gateway > Policies > Authentication > SAML IDP
• In the Policies tab create a new policy via Add

• Give the SAML IDP Policy a name (e.g., Office365_SSO_Policy) and click
  Add next to the Action drop-down menu
• In the window Create Authentication SAML IDP Profile enter the following:
  • Name (e.g. Office365_SSO_Profile)
  • Import Metadata (Not checked)
  • Assertion Consumer Service Url (https://login.microsoftonline.com/login.srf)
  • SAML Binding (POST)
  • Logout Binding (POST)
  • IDP Certificate Name (Public certificate for signing, so it has to be made known to the SP Office365; e.g. wildcard certificate)
  • Sign Assertion (ASSERTION)
  • Issuer Name (Public FQDN for AAA-vServer; e.g. https://auth.deyda.net/saml/login)
  • Signature Algorithm (RSA-SHA1)
  • Digest Method (SHA1)

• Click on More to expand the view
  • Audience (urn:federation:MicrosoftOnline)
  • Skew Time (5)
  • Name ID Format (Persistent)
  • Name ID Expression (AAA.USER.ATTRIBUTE(2).B64ENCODE)
  • Attribute 1 (IDPEmail)
  • Attribute 1 Expression (AAA.USER.ATTRIBUTE(1))
  • Attribute 1 Format (URl)
  • Attribute 1 Friendly Name (mail)

• Use Create to complete the configuration of the SAML IDP profile
• In the Create Authentication SAML IDP Policy window, select the Action you just created
• Under Expression enter HTTP.REQ.HEADER(“Referer”).CONTAINS(“microsoft”)

• Use Create to complete the creation of the SAML IDP Policy

Now you create your AAA vServer (DNS auth.deyda.net) for the SAML authentication.

• Navigate to Security > AAA – Application Traffic > Virtual Servers and use Add to create a new Virtual Server
  • Name (e.g. Office365_auth_VS)
  • IP Address Type (IP Address)
  • IP Address (VIP; external FQDN to e.g. auth.deyda.net)
  • Port 443
  • Authentication (Checked)
  • State (Checked)

• Via Continue you will get the next mask
  • Click on No Server Certificate and attach in the following window a suitable certificate for the FQDN (most simply with wildcard)

• Via Continue you will get the next mask
  • On this click on No SAML IDP Policy and attach the previously created policy (Office365_SSO_Policy)

• And as always via Continue you will get the next mask
  • Under Basic Authentication Policies click on No LDAP Policy and link the previously created LDAP Policy (Office365_LDAP_SSO_Policy)

• Now you can use Done to save the configuration of the AAA-vServers

Office365

First we have to download the identity provider certificate stored in the Citrix ADC.

• Under Traffic Management > SSL click on Manage Certificates / Keys / CSR’s
• Now select the previously used certificate and click Download

To convert Office 365, after a successful sync with the local AD, from standard domain authentication to a single-sign on, we must do the following.

• Start Powershell with the Azure AD module installed
• Connect to Office365 using the following command

• To successfully switch the required domain to Federated (Single-Sign On), it must be first Managed. This can be checked with the following command

• To change it, this command must be executed

• Now we can change the domain to communicate with the Citrix ADC. First we define the variables for the later command.
  • $url, $uri & $ecpUrl (Address of IdP (AAA-vServer))
  • $dom (Affected Domain)
  • $fedBrandName (Freely selectable name of the federation)
  • $cert (Path to the downloaded certificate)

• The following command will switch the authentication domain from Managed (Username & Password) to Federated (Single-Sign On). Important points are therefore.
  • Create first an administrative user in Office365, which is not linked to a local AD user (login is only possible with managed domain, e.g. **.onmicrosoft.com)
  • Do not close PowerShell until access has been successfully tested, otherwise you will exclude yourself (access is only possible via the above-mentioned emergency admin)
  • If access via single-sign-on does not work, simply switch to managed via the above command

• The configuration can be checked via the following command

If we log in with our username via https://portal.office.com (e.g., manuel@deyda.net).

We will be forwarded directly to our AAA vServer and can authenticate ourselves there. Upon successful authentication, we will be redirected to Office365.

Citrix ADC – Unified Gateway

Now we can prepare our previously configured Unified Gateway for the Office365 bookmarks.

To get access to the different access methods (Clientless Access / Virtual Apps and Desktop Access / Network Access), we need to do the following.

• In the Citrix ADC Navigation Panel under Integrate with Citrix Products, click Unified Gateway
• There we choose the Gateway that we want to edit
• Under Portal Theme we click on the pencil icon and select the Portal Theme RfWebUl
• We confirm the selection with Continue

If we now select Clientless Access, we will not only see the connected Virtual Apps and Desktops, but also pre-defined bookmarks for SaaS applications and websites.

Now we want to add Office365 as a SaaS bookmark to give users single-sign-on access.

• In the Citrix ADC Navigation Panel, under Integrate with Citrix Products, click Unified Gateway
• There we choose the Gateway that we want to edit
• Now we click on the + symbol next to Applications
• Under Choose Type we select SaaS and confirm the selection with Continue

• Now we choose Choose from Catalog and search Office365 in the drop down menu
• As always, the selection is confirmed with Continue

• In the following window, you configure the Office365 Bookmark and confirm the configuration with Continue
  • Name (Display Name)
  • Service Provider Login URL (https://login.microsoftonline.com/login.srf)
  • Service Provider ID (https://login.microsoftonline.com/login.srf)
  • IDP Certificate Name (IdP Certificate)
  • Issuer Name (IdP Address, e.g. https://auth.deyda.net/saml/login)

• Confirm the following window with Done and you have added a bookmark for Office365

But if you log in to the Unified Gateway and open the Office365 bookmark, you will be asked for your username and then forwarded to the AAA-vServer.

This is not yet the desired single-sign-on result and therefore we need to adjust the bookmark again to set up an initial IdP.

• In the Citrix ADC Navigation Panel, click NetScaler Gateway > Resources > Bookmarks
• Now select the bookmark created with the wizard and click Edit

• Here you change the SSO Type to SAML Based Authentication and click Edit on SAML SSO Profile

• Adjustment of the SAML SSO Profiles
  • Relay State Expression (HTTP.REQ.COOKIE)
  • Name ID Expression (AAA.USER.ATTRIBUTE(2).B64ENCODE
• Click More for additional settings

• In the opened More menu the following must be edited
  • Attribute 1 (IDPEmail)
  • Attribute 1 Expression (AAA.USER.ATTRIBUTE(1))
  • Attribute 1 Format (URl)
  • Attribute 1 Friendly Name (mail)

If you now log into the Unified Gateway and the bookmark opens, you will be forwarded directly to Microsoft.

There you will be authenticated in the background via single-sign-on and forwarded directly to Office365.