Citrix ADC as initial IdP for Office365

Citrix ADC Version 12 initial IdP 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.
SAML-Authentifizierung

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)
Configure Authentication LDAP Policy
  • 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)
Configure Authentication LDAP Server
  • 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)
Configure Authentication LDAP Server Other Settings
  • Click on More to expand the view
    • Attribute 1 (mail)
    • Attribute 2 (objectGUID)
Configure Authentication LDAP Policy Attribute Fields
  • 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
Create Authentication LDAP Policy
  • 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
Create Authentication SAML IDP Policy
  • 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)
Create Authentification SAML IDP Profile
  • 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)
Configure Authentication SAML IDP Profile
  • 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”)
Configure Authentication SAML IDP Policy
  • 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)
Create Authentication Virtual Server
  • 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)
Authentication Virtual Server Certificate
  • 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)
Authentication SAML IDP 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)
Authentication LDAP Policy
  • Now you can use Done to save the configuration of the AAA-vServers
Authentication Virtual Server

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
Offce365 Connect Powershell
  • To successfully switch the required domain to Federated (Single-Sign On), it must be first Managed. This can be checked with the following command
Get-MsolDomain
  • 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
Get-MsolDomainFederationSettings

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

Weiterleitung zu ihrem Anmeldeseite

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 AAA vServer

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
Unified Gateway Client Choice

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
Unified Gateway Bookmark Choose Type
  • Now we choose Choose from Catalog and search Office365 in the drop down menu
  • As always, the selection is confirmed with Continue
Unified Gateway Bookmark SaaS Choose from Catalog
  • 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)
SaaS-Application
  • 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.

SaaS Office365 Bookmark without Single-Sign On

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
Edit Bookmark SaaS Office365
  • Here you change the SSO Type to SAML Based Authentication and click Edit on SAML SSO Profile
Bookmark SSO Type SAML Based Authentication
  • 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
Create SAML SSO Profile
  • 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)
Create SAML SSO Profile Attribute 1

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

Office365 Single-Sign On

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

Single-Sign On Office365

3 thoughts on “Citrix ADC as initial IdP for Office365”

  1. Hello Manuel, thanks for the great article.

    Is this configuration still valid for ADC 13.0? We managed to authenticate through netscaler but then we are ending up on the landing page of office.com.

    on the SAML profile we also tried using the XML metadata url from Microsoft with the same result.

    Have you ever experienced such behavior (the rideraction to the login screen of microsoft after succesfully logon onto the ADC login page?)

    Thanks – ps: I added you to my Linkedin.

Leave a Reply

Your email address will not be published. Required fields are marked *

* I consent to having this website store my submitted information so they can respond to my inquiry.