HowTo: Azure MFA SAML and Citrix Gateway with SSO Without FAS

Introduction and Background

NOTE: As of June 8th, 2021, Citrix has identified two vulnerabilities covered in CTX297155. Upon remediation with appropriate firmware, SAML configurations require adjustment as per CTX316577. This article’s examples do not contain those adjustments and readers are encouraged to modify their deployments accordingly to mitigate the security risk.

As an introductory disclaimer, I alone did not devise this solution, but merely completed its development in its latest iteration. Much of the legwork was developed by an expert team of Citrix Consulting and Citrix ADC Engineering professionals over several iterations for a customer with unique constraints, which prevented them from deploying Citrix Federated Authentication Service (FAS).

Update April 27th 2020, I’ve released a similar article on Okta SAML auth at Citrix Gateway without FAS, but using Okta’s LDAP POST via SWA functions instead of an ADC-hosted IDP.

I should note before we get too far along that this alternative solution has a hard requirement of Citrix ADC standing in as an on-prem IDP (in lieu of ADFS for example), and is therefore not universally suitable for all customers. With that said, this requirement is easy enough to work around by using another custom domain with the Azure AD tenant and federating that domain with the ADC-hosted IdP. The “Login URL” string we would set in the SAML SP configuration on the ADC would be appended with the following after /saml2  “?whr=customDomain”  i.e. …/saml2?whr=customDomain where customDomain matches the custom domain added to the Azure AD tenant and federated to the ADC-hosted IdP. We are in effect “directing” Azure AD to use a specific WS-Federation realm we have set up, and leave the default configuration of Azure AD to continue authentication users as normal, and not impacting non-Citrix SAML authentication flows, be they federated elsewhere (ADFS, another IdP, etc.) or not.

Furthermore, this guide should work for other SAML solutions beyond Azure AD, but I have yet to test-drive this. I have been advised that this method has seen use outside of Citrix altogether, to allow conditional access and SAML to front applications that cannot support SAML natively. Cool stuff.

Starting off with a little bit of background, customers seeking to leverage SAML authentication at Citrix Gateway by default tend to need some additional Citrix components. Citrix FAS enables users to authenticate via SAML in order to maintain a single sign-on (SSO) experience to their Citrix resources once logged in, just as when using LDAP.

Why do we need FAS? Because SAML isn’t natively spoken by Windows. So if it’s your only authentication method at Citrix Gateway (i.e you’re not using it in combo with LDAP) you’re not going to log into Citrix Gateway and SSO into your Citrix resources. A user authenticating via SAML at Citrix Gateway would be passed through to Citrix StoreFront but would get a second Windows login prompt when launching the app or desktop in absence of FAS. If you’re interested in Citrix FAS (which remains the “lead with” strategy for SAML auth to Citrix resources), I suggest checking out Carl Stalhood’s FAS article, which is as always, a thorough walkthrough.

Side note The Beer Drinker’s Guide to SAML provides a hilarious and layman’s term overview of SAML for those who do not yet fully grasp its constructs or how it works. Highly recommended.

SAML not providing SSO out of the box with Citrix isn’t a Citrix issue, it’s a Windows limitation. That’s why FAS was conceived. It bridges the gap between SAML and Windows-native authentication methods. In the case of FAS, it’s using certificates as that mechanism (or more specifically virtual smart cards).

For some customers, FAS may not be possible due to various direct or indirect reasons. In the case of the particular customer this solution was developed for, they had the following challenges for their SAML solution of choice (Azure AD \ Azure MFA):

• Due to corporate policy, cannot sync passwords nor password hashes into Azure AD.
• Due to an Active Directory limitation in their environment, unable to leverage ADFS as an IDP for Azure AD to interface with, which could help overcome the prior point.
• Not able to use Microsoft Network Policy Server (NPS) with the Azure MFA extension. This legacy mode does not allow for conditional access policies which is a non-starter for some customers.

On account of the first two points, a solution was devised using a Citrix ADC-hosted IDP AAA-TM vServer to stand in for ADFS, and federating Azure AD with this domain using the IDP. With this in place, we have means to capture the user’s LDAP credentials when authenticating to the IDP and replay them during a later authentication sequence in an LDAP policy, thus achieving SSO to Citrix resources. We achieve this store and retrieval logic by using the Citrix ADC variables and assignment function which stores data in memory (encrypted if specified) for later retrieval.

The purpose of this article is to walk through the setup of this solution. ADC CLI commands to build out the configuration (swapping in one’s own IPs, certs, names, etc.) are included at the end of the article.

Authentication Flow

For the purposes of this article, I have labbed out the solution with gateway.ferroque.dev as the Citrix Gateway, and idp.ferroque.dev as the Citrix ADC-hosted IDP (AAA-TM vServer). The authentication flow is as so:

1. User connects to https://gateway.ferroque.dev.
2. Citrix ADC evaluates the first authentication policy bound to the authentication vServer in the authentication profile associated to the Citrix Gateway vServer.
3. Citrix ADC sends a SAML request to Azure AD (SAML Request # 1). In this initial sequence, the Citrix ADC is acting as a SAML Service Provider (SP) and Azure AD is acting as an Identity Provider (IdP).
4. Azure AD upon receiving SAML Request # 1 sends a new SAML request to Citrix ADC. (SAML Request # 2). Here, Azure AD is acting as a SAML SP and Citrix ADC is acting as an IDP.
5. Azure AD redirects the user to https://idp.ferroque.dev as per the federation configurations for the domain, and is prompted for AD credentials (sAMAccountName format in this scenario, but could accommodate for UPN as well). Citrix ADC validates LDAP credentials.
6. Citrix ADC invokes a global variable and assignment configuration to store the user credentials for up to 1 hour before expiring them. These credentials are stored in a map in memory and are encrypted so they remain obfuscated in event for a core dump.
7. Upon successful authentication, Citrix ADC evaluates SAML IdP policy.
8. Citrix ADC sends a SAML response or assertion to Azure AD (Response to SAML Request #2).
9. Azure AD applies conditional access policies, multi-factor authentication, etc.
10. If MFA is successful, Azure AD sends a SAML assertion to Citrix ADC as a (Response to SAML Request #1).
11. Citrix ADC evaluates LDAP credentials (using a second LDAP server using UPN) such that they are the last credentials checked for SSO, using a login schema configured to extract the previously stored password from step #6.
12. User is authenticated to https://gateway.ferroque.dev and passes through to StoreFront.

A high-level flow looks like this:

LDAP Auth –> Store Credentials –> MFA –> Retrieve Credentials –> SSO to Citrix Gateway (and subsequently to StoreFront and Citrix apps)

As you might have guessed, this solution will use nFactor in Citrix ADC on the AAA vServers. The diagram below outlines the various authentication components involved in this solution which will be built out later in this guide:

Pre-Requisites

For the purposes of this article, the following assumptions are being made:

• A Citrix ADC 13.0 and Citrix Gateway vServer already built and integrated into a Citrix Virtual Apps & Desktops (CVAD) environment (StoreFront, Citrix Site).
• Functional Windows domain and a service account for LDAP.
• A domain not yet enabled for federation added to Azure AD (custom domain) and has been ‘verified’.
• The ability to have Citrix ADC act as an IDP for the user domain (i.e. another solution such as ADFS is not already doing this for the domain).
• TLS certificate (SAN, named, or wildcard) to cover two AAA-TM vServers, Citrix Gateway vServer.
• Public key certificate for the IDP AAA-TM vServer for use in IDP federation process between Azure AD and Azure MFA
• Sufficient rights in Azure AD to federate a domain.
• An IP for the IDP AAA-TM.
• An Enterprise Application configured for SAML authentication for use by our Citrix Gateway.
• Citrix ADC Advanced (formerly Enterprise) or above license.

Step 1 – Create Variables and Assignments

Variables are a powerful AppExpert function on Citrix ADC which allows the storing of data within memory for a period of time and can be called upon by referencing an assignment corresponding to the variable. In our use case, we’re building a variable map for username and password, captured from the initial LDAP authentication the user experiences at the Citrix-owned IDP. Using variables allows us to call on credentials for re-use between authentication sessions. For more information on variables, please reference Configuring and Using Variables.

We’ll first start by creating the variable itself. The following screens detail the key inputs needed. The values will be stored in appliance memory so be mindful of this when sizing inputs. In the below example, we have a key and value length totalling 512 bytes, and up to 1,000 entries permitted within a 1 hour period max. As we’ll be encrypting and there will surely be some metadata and overhead, multiplying by 1.1x should give us enough of a buffer. 512 x 1000 x 1.1 = 563,200 bytes or 0.5 MB.

We’ll now create the assignment to pair with the variable. The variable shown below will be what we use to call upon the key data for credential replay later. We are encrypting the stored credentials within appliance memory to obfuscate the passwords should a core dump need to be sent to a third party for analysis (Citrix Support, etc.). The key expression will use the sAMAccountName the user enters into the first LDAP prompt at the ADC-owned IDP.

Step 2 – Create LDAP Servers

This solution uses two different LDAP servers for two different phases of the authentication sequence. The customer this was developed for wanted to permit users to log in with UPN or sAMAccountName. For the purposes of this article, we’re sticking with sAMAccoutName for simplicity. Adding UPN as a secondary authentication server for initial login is not a significant ordeal, however.

The second LDAP server we call the “SSO” server. Assuming we’re getting a NameID\UPN from the Azure AD to Citrix Gateway AAA vServer in the second half of the auth sequence we use an LDAP server configured with the Server Logon Attribute of userPrincipalName to correctly look up and authenticate the user. This will also be the credential pair passed over to StoreFront.

Step 3 – Create SAML IDP Profile, SAML SP Server, and IDP Policies

We’ll now build the SAML IDP configuration the ADC will use. We will bind this to the appropriate IDP AAA-TM vServer in the subsequent step.

• Assertion Consumer Service Url will always be for Azure: https://login.microsoftonline.com/login.srf
• Service Provider Logout URL will be FQDN of your IDP followed by cgi/tmlogout
• For the IDP Certificate Name, bind the IDP certificate (i.e. one you have a private key for, the same one you will bind to your ADC-owned IDP AAA vServer. This is NOT the Azure IDP signing certificate!).
• Audience: Will always be: urn:federation:MicrosoftOnline
• Leave skew time default at 5 minutes
• Set Name ID Expression to: AAA.USER.ATTRIBUTE(2).B64ENCODE
• Set Sign Assertion to Assertion
• Change Signature Algorithm to RSA-SHA256, SHA256
• Define the Attribute 1 values as shown below
• 

We’ll then create a SAML IDP policy linking to our newly created IDP profile. The expression will look explicitly the Microsoft Online URL:

HTTP.REQ.HEADER("Referer").CONTAINS("login.microsoftonline.com")

If not already completed, go ahead and build out the Azure AD enterprise application configuration as one would if federating Citrix ADC with FAS. This article will not go through those details, plenty others do, but here is a screenshot of the lab config. Be sure to assign users. Be sure to configure the SAML SP server to use the certificate downloaded from Azure for the IDP certificate (not the certificate of the ADC-owned IDP).

Now we move on to create the SAML SP profile which the Citrix Gateway’s AAA vServer will use as the first authentication factor. This is where the enterprise app details created previously will be used. The Azure enterprise app IDP certificate should be downloaded and installed on the ADC. It may show up under the “Unknown” certificate store once installed.

• Redirect URL is the Azure enterprise application’s “Login URL” provided at the time of app creation. Append ?whr=yourdomain.com after /saml2 if you have more than one domain and need to auto-select the domain for the user to reduce login steps such as hitting Azure, being asked for email, then being redirected to IDP and asked to enter email again plus password.
• Bind the Signing Certificate provided by the Azure enterprise application config as “IDP Certificate Name”.
• Although the config will default to NameID for the user field, enter it anyway.
• Select the signing certificate which in this case will be the same TLS certificate you bound to the Citrix Gateway and its non-addressable vServer.
• Input the Issuer Name and Audience parameters, which should be the URL of the Citrix Gateway users are logging into.
• Tune the Signature Algorithms as shown.
• Check off Force Authentication.
• Implement the attributes as shown.

With the SAML SP server out of the way, we’ll create the advanced authentication SAML SP policy linking to the server of type “SAML”. In this example, we’re calling it saml_sp_policy_to_aad_idp. The expression to be used is “HTTP.REQ.COOKIE.NAME_VALUE(“NSC_TASS”).CONTAINS(“idp.ferroque.dev”).NOT” and the policy will link to SAML_MSFT_SRV as the action.

Step 4 – Building AAA-TM vServers and Auth Profiles

The solution requires two AAA-TM vServers. The first one is a non-addressable AAA vServer which will be linked to the Citrix Gateway vServer. This AAA flow uses Azure AD SAML policy, followed by an LDAP factor (second LDAP aka SSO LDAP) that seamlessly passes through credentials stored in a variable.

The second AAA vServer needs to have an IP address and be reachable by users. It performs the role of SAML IDP, as well as the first LDAP factor. Post-LDAP authentication, the last, invisible factor stores the credentials in a variable value.

Build out two generic AAA vServers as shown below and harden to org. standards. Use the server certificate of the Citrix Gateway on the AAA_GATEWAYNOFAS vServer, and use an appropriate server certificate on the AAA_IDP vServer. Note the public key of the AAA_IDP’s certificate will be needed to create the Azure AD federation task in step 10.

Then create the authentication profile.

Step 5 – Create Login Schemas

Create two Login Schema profiles. Both will use a noschema schema. Both are used on LDAP factors, and one is used to store the LDAP credentials from the initial LDAP authentication (sAMAccountName in our example) and the second one for retrieval of those credentials and used in conjunction with the second LDAP authentication (for SSO using UPN).

StoreCreds_LS does not require any user or password expression entire and could just as easily be substituted for built-in LSCHEMA_INT.

The “PreFillUsernamePassword_LS” however, is our value retrieval schema and does require additional configuration in order to grab the previously stored password. This expression in the password field looks up the username in the variable map. The string looks for the username before the @ symbol, as Azure AD will be sending back UPN. It is assumed that the username portion of UPN matches that of sAMAccountName. If it does not in your organization, modifications to SAML and LDAP server properties for user attributes may be needed. The expression also decrypts the stored password for use.

$idp_usercreds_var[AAA.USER.NAME.TO_LOWER.BEFORE_STR("@")].DECRYPT

Step 6 – Create Authentication Policies

Two authentication policies (for our two LDAP factors) are needed. They will respectively link with the previously created LDAP servers. In both cases, the expression of ‘true’ is sufficient.

We also need to create the policies for our store credential procedures when authenticating at the ADC-owned IDP. Note that “store_creds_policy” cannot be created in the GUI as of ADC 13.0 b55.24. The command has to be run from CLI to create an authentication policy that can reference a variable assignment (which will thus store the credentials as configured earlier). This command only seems to work on 13.0, in testing on 12.1 b56.22 it crashes the appliance forcing a reboot. Have not tried on earlier builds of 12.1 as we require 13.0 regardless.

add authentication Policy store_creds_policy -rule true -action idp_usercreds_assign

Step 7 – Create Authentication Policy Labels

We must create two policy labels to accommodate for “second factors” on the respective AAA vServers.

For the Citrix Gateway’s corresponding vServer, the first factor is Azure MFA, followed by the auto-filled credential LDAP (SSO UPN) authentication as a second factor which we’ll configure on a policy label in order to set the right login schema.

For the IDP’s vServer, the first factor is LDAP (SAM) followed by a policy label with an initial policy to store the username and password credentials and a second policy that passes through and gives a success state as no “success state” response consumable by nFactor when calling the assignment.

Step 8 – Create nFactor Flows on AAA-TM vServers

Edit the properties of the non-addressable AAA vServer used by Citrix Gateway (AAA_GATEWAYNOFAS). Bind the SAML SP policy created earlier by clicking “Authentication Policy”, and select the PreFillUsernamePassword_PL policy label as the next factor. Bind a “noschema” loginschema to the AAA vServer itself. Click “Done” to accept changes and get back to the previous screen.

Edit the properties of the AAA_IDP vServer (the one with the routable IP) and we will bind two policies here; SAML IDP and LDAP.

For LDAP, click “Authentication Policy” and bind the sAMAccountName LDAP policy and select the next factor as the Assign_StoreCreds_PL policy label.

Next, let’s bind the SAML IDP policy. Note that if you make changes to the SAML IDP policy expression after binding to the vServer, you may need to unbind and re-bind in order for it to take effect.

Step 9 – Link Auth Profile to Citrix Gateway

The easiest step of all, binding the authentication profile we created earlier to the Citrix Gateway vServer. This authentication profile should link to the non-addressable AAA vServer for the Gateway.

Step 10 – Federate Domain with Azure AD using Citrix ADC IDP

We’ll now create our federation in Azure AD for the domain, in our case ferroque.dev which was previously added and validated in Azure AD (as a prerequisite) under the Azure > Custom domain name section of the Azure portal. Once the commands are invoked, note that it can take 15 minutes or so for the changes to replicate.

Note: If Azure AD SAML authentication is already in use, it is important this be the last step as you’ll effectively be changing the way users authenticate to Azure AD for their SaaS apps at this point. Prior to this, authenticating directly at the IDP to verify no errors are encountered is important (ignore the “Target URL not found for redirect after successful login.” message can be ignored in such a test).

First, from an administrative prompt on a Windows system, run the following commands to install and log into the Azure PowerShell cmdlets.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Install-Module -Name MSOnline

You should get an output like this:

Next, run the following command to authenticate to Azure AD.

Connect-MsolService

Log in with the global admin account or another account with sufficient rights to conduct domain federation.

For the next step you’ll want to grab the public key from the certificate you’ll be using to secure the IDP. In my case I was using a wildcard certificate for all the vServers in the lab and just exported the certificate without private key in DER format. In the example below, the federation commands will look for the file in C:\. This is needed for Azure AD to trust the IDP’s assertions.

The following variables and commands will invoke the federation of Azure AD to the domain which in this example is ferroque.dev. Note the URIs used in this configuration, which should match URIs used previously in the various SAML configurations on the ADC. Note that $dom variable references the “verified” domain you will have added to Azure as a prior pre-requisite.

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\idp_publicKey.crt")
$certData = [system.convert]::tobase64string($cert.rawdata)
$dom = "ferroque.dev"
$fedBrandName = "Ferroque Dev Domain"
$logoffuri = "https://idp.ferroque.dev/cgi/tmlogout"
$logonuri = "https://idp.ferroque.dev/saml/login"
$issueruri= "https://idp.ferroque.dev/"
$ecpUrl = "https://idp.ferroque.dev/saml/login"

Set-MsolDomainAuthentication -DomainName $dom -federationBrandName $fedBrandName -Authentication Federated -PassiveLogOnUri $logonuri -SigningCertificate $certData -IssuerUri $issueruri -ActiveLogOnUri $ecpUrl -LogOffUri $logoffuri –PreferredAuthenticationProtocol SAMLP

Also an important note, the $issueruri variable must match the “Issuer Name” on the SAML IDP profile exactly or Azure SAML authentication issues will occur (AADSTS50107 error) as shown below once configuration is complete and you are testing the flow. In my case, the trailing slash was not present in my SAML IDP profile to match the federation configs. Easy fix.

Running the following command will give you an output to validate your configurations.

Get-MsolDomainFederationSettings -DomainName ferroque.dev

For reference, the output of the above commands should look something like this. If your trusted signing certificate did not present itself in a Base64 blob, you have an issue needing correcting for your certificate.

Examing the Azure AD GUI properties for custom domains should now show the domain as federated as well.

Moment of Truth – Validation

At this point all necessary configurations should be in place. Attempting to log into the Citrix Gateway should have the user redirected briefly to Azure AD, then to the Citrix ADC-hosted IDP. Upon successful authentication via LDAP, the user should be redirected back to Azure AD where presumably some form of MFA (token, push, etc.) will take place, at which point the user should be directed back to the Citrix Gateway and seamlessly passed through to StoreFront.

Accessing Gateway Page, Redirected to Azure and to Citrix ADC IDP. First LDAP Auth (sAMAccoutName)

Successful Response from IDP AAA to Azure – Azure Auth (MFA, etc.)

Successful Response from Azure to Citrix Gateway AAA and Passthrough to StoreFront

Successful Launch of Citrix App – No Second Authentication Prompt

Citrix ADC Configuration

Below you will find all the necessary config params to build the configs mentioned above on the ADC. You’ll naturally want to adjust object names, certificate names, IPs.

## Variable and Assignment ##
add ns variable idp_usercreds_var -type "map(text(256),text(256),1000)" -ifFull undef -ifValueTooBig undef -expires 3600
add ns assignment idp_usercreds_assign -variable "$idp_usercreds_var[AAA.USER.NAME]" -set AAA.USER.PASSWD.ENCRYPT


## Certificate Certkeys and Linking ##
add ssl certKey MSFT_IDP_CERT -cert Ferroque-CitrixGateway-NOFAS-TEST.cer -passcrypt @@@@@@@@@@@ -encrypted -encryptmethod ENCMTHD_3
add ssl certKey wildcard_ferroque_dev -cert wildcard_ferroque_dev.pfx -key wildcard_ferroque_dev.pfx -inform PFX -passcrypt @@@@@@@@@@@ -encrypted -encryptmethod ENCMTHD_3
add ssl certKey SectigoINTER -cert SectigoINTER.cer -inform DER
add ssl certKey SectigoROOT -cert SectigoROOT.cer -inform DER
link ssl certKey wildcard_ferroque_dev SectigoINTER
link ssl certKey SectigoINTER SectigoROOT


## LDAP, SAML IDP, SAML SP Actions ##
add authentication samlIdPProfile SAML_IDP_PROF -samlIdPCertName wildcard_ferroque_dev -assertionConsumerServiceURL "https://login.microsoftonline.com/login.srf" -samlIssuerName "https://idp.ferroque.dev/" -rejectUnsignedRequests OFF -audience urn:federation:MicrosoftOnline -NameIDFormat persistent -NameIDExpr "AAA.USER.ATTRIBUTE(2).B64ENCODE" -Attribute1 IDPEmail -Attribute1Expr "AAA.USER.ATTRIBUTE(1)" -Attribute1FriendlyName mail -Attribute1Format URI -SPLogoutUrl "https://idp.ferroque.dev/cgi/tmlogout"

add authentication ldapAction LDAP_FERROSYS -serverIP 1.1.1.1 -serverPort 636 -ldapBase "OU=your,DC=domain,DC=DEV" -ldapBindDn yourldap@ferroque.dev -ldapBindDnPassword @@@@@@@@@@@  -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberOf -subAttributeName cn -secType SSL -passwdChange ENABLED -Attribute1 mail -Attribute2 objectGUID -Attribute9 sAMAccountName -Attribute10 userPrincipalName

add authentication ldapAction LDAP_FERROSYS_SSO -serverIP 1.1.1.1  -serverPort 636 -ldapBase "OU=your,DC=domain,DC=DEV" -ldapBindDn yourldap@ferroque.dev -ldapBindDnPassword @@@@@@@@@@@ -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName userPrincipalName -groupAttrName memberOf -subAttributeName cn -secType SSL -ssoNameAttribute userPrincipalName -passwdChange ENABLED -Attribute1 mail -Attribute2 objectGUID -Attribute9 sAMAccountName -Attribute10 userPrincipalName

add authentication samlAction SAML_MSFT_SRV -samlIdPCertName MSFT_IDP_CERT -samlSigningCertName wildcard_ferroque_dev -samlRedirectUrl "https://login.microsoftonline.com/xxxxxxxxxxxxxxxxxxxx/saml2?whr=ferroque.dev" -samlUserField NameID -samlIssuerName "https://gateway.ferroque.dev/" -Attribute1 NameID -Attribute2 email -enforceUserName OFF -forceAuthn ON -audience "https://gateway.ferroque.dev/"


## AAA-TM Servers ##
add authentication vserver AAA_IDP SSL 1.1.1.2 443 -maxLoginAttempts 10 -failedLoginTimeout 15
add authentication vserver AAA_GATEWAYNOFAS SSL 0.0.0.0 -maxLoginAttempts 10 -failedLoginTimeout 15
set ssl vserver AAA_IDP -ssl3 DISABLED -tls1 DISABLED -tls11 DISABLED -dtls1 DISABLED -HSTS ENABLED -maxage 157680000
set ssl vserver AAA_GATEWAYNOFAS -ssl3 DISABLED -tls1 DISABLED -tls11 DISABLED -dtls1 DISABLED -HSTS ENABLED -maxage 157680000
bind authentication vserver AAA_IDP -portaltheme RfWebUI
bind authentication vserver AAA_GATEWAYNOFAS -portaltheme RfWebUI
bind authentication vserver AAA_GATEWAYNOFAS -policy noschema -priority 100 -gotoPriorityExpression END
bind authentication vserver AAA_GATEWAYNOFAS -policy saml_sp_policy_to_aad_idp -priority 100 -nextFactor PreFillUsernamePassword_PL -gotoPriorityExpression NEXT
bind authentication vserver AAA_IDP -policy SAML_IDP -priority 100 -gotoPriorityExpression NEXT
bind authentication vserver AAA_IDP -policy authsrv_ldaps_authOn_sAMAccountName -priority 100 -nextFactor Assign_StoreCreds_PL -gotoPriorityExpression NEXT
bind ssl vserver AAA_IDP -certkeyName wildcard_ferroque_dev
bind ssl vserver AAA_GATEWAYNOFAS -certkeyName wildcard_ferroque_dev
add authentication authnProfile AAA_GATEWAY-NOFAS_authprof -authnVsName AAA_GATEWAYNOFAS -AuthenticationHost gateway.ferroque.dev -AuthenticationDomain ferroque.dev


## Gateway Server ##
add vpn vserver gateway.ferroque.dev SSL 1.1.1.3 443 -downStateFlush DISABLED -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -maxLoginAttempts 10 -failedLoginTimeout 15 -authnProfile AAA_GATEWAY-NOFAS_authprof
add vpn sessionAction BASELINE_SESSION_WEB_PROF -sessTimeout 60 -clientSecurityLog ON -splitTunnel OFF -transparentInterception ON -defaultAuthorizationAction ALLOW -ssoCredential PRIMARY -icaProxy ON -wihome "https://storefront.ferroque.dev/Citrix/StoreWeb" -ntDomain ferroque.dev -clientlessVpnMode OFF
add vpn sessionPolicy BASELINE_SESSION_WEB_POL true BASELINE_SESSION_WEB_PROF
bind vpn vserver gateway.ferroque.dev -staServer "https://xdc1.ferroque.dev"
bind vpn vserver gateway.ferroque.dev -staServer "https://xdc2.ferroque.dev"
set ssl vserver gateway.ferroque.dev -ssl3 DISABLED -tls1 DISABLED -tls11 DISABLED -dtls1 DISABLED -HSTS ENABLED -maxage 157680000
bind vpn vserver gateway.ferroque.dev -portaltheme RfWebUI
bind vpn vserver gateway.ferroque.dev -policy BASELINE_SESSION_WEB_POL -priority 100 -gotoPriorityExpression NEXT -type REQUEST
bind ssl vserver gateway.ferroque.dev -certkeyName wildcard_ferroque_dev


## Login Schemas, Policies, Policy Labels ##
add authentication loginSchema PreFillUsernamePassword_LS -authenticationSchema noschema -passwdExpression "$idp_usercreds_var[AAA.USER.NAME.TO_LOWER.BEFORE_STR(\"@\")].DECRYPT" -userCredentialIndex 5 -passwordCredentialIndex 6 -SSOCredentials YES
add authentication loginSchema StoreCreds_LS -authenticationSchema noschema -SSOCredentials YES
add authentication samlIdPPolicy SAML_IDP -rule "HTTP.REQ.HEADER(\"Referer\").CONTAINS(\"login.microsoftonline.com\")" -action SAML_IDP_PROF
add authentication noAuthAction NO_AUTHN
add authentication loginSchemaPolicy noschema -rule true -action LSCHEMA_INT
add authentication Policy authsrv_ldaps_authOn_sAMAccountName -rule true -action LDAP_FERROSYS
add authentication Policy store_creds_policy_finish -rule true -action NO_AUTHN
add authentication Policy saml_sp_policy_to_aad_idp -rule "HTTP.REQ.COOKIE.NAME_VALUE(\"NSC_TASS\").CONTAINS(\"idp.ferroque.dev\").NOT" -action SAML_MSFT_SRV
add authentication Policy store_creds_policy -rule true -action idp_usercreds_assign
add authentication Policy authsrv_ldaps_authOn_SSO -rule true -action LDAP_FERROSYS_SSO
add authentication policylabel Assign_StoreCreds_PL -loginSchema StoreCreds_LS
add authentication policylabel PreFillUsernamePassword_PL -loginSchema PreFillUsernamePassword_LS
bind authentication policylabel Assign_StoreCreds_PL -policyName store_creds_policy -priority 100 -gotoPriorityExpression NEXT
bind authentication policylabel Assign_StoreCreds_PL -policyName store_creds_policy_finish -priority 110 -gotoPriorityExpression NEXT
bind authentication policylabel PreFillUsernamePassword_PL -policyName authsrv_ldaps_authOn_SSO -priority 100 -gotoPriorityExpression NEXT

Troubleshooting Tools

As this is an elaborate configuration, there are many opportunities for things to go wrong. Having three PuTTy sessions open with the following commands at the ready are quite useful, all executed from shell. Note that it may be worth enabling DEBUG logging on the global internal Syslog configuration of the appliance while troubleshooting, and disabling it afterward. System > Auditing > Settings > Change Auditing Syslog Settings > Log Levels = ALL.

Examining authentication logs:

shell
cat /tmp/aaad.debug

Examining Syslog events during authentication (note you can append ‘| grep -i xxx’ where xxx us a key term such as SAML or AAA to filter on:

shell
tail -f /var/log/ns.log

Examining policy hits on nFactor configuration:

shell
nsconmsg -d current  -g pcb_hits

The SAML-Tracer extension for Chrome or FireFox is also an invaluable tool for debugging SAML authentication.

Additionally, an error message such as this below may indicate the variable is not successfully finding a matching user ID in the map in order to pull the password, or the user ID itself is not being passed through correctly. The former would show up as an error in the aaad.debug logs about a null password error. The latter may indicate the user was not found when performing the SSO LDAP config (the second LDAP auth in the sequence). In such case there may be an issue with the SSO LDAP server config such as sAMAccountName used instead of userPrincipalName for Server Logon Name Attribute, or some other mismatch between NameID received back from Azure’s assertion and the Server Logon Name Attribute defined on the SSO LDAP server on the ADC.

Thank You!

Special thanks to Citrites including Rene Gamache, Florin Bejan, Maude Courcy, Blair Parker, Saman Salehian, and Citrix Alumni Jay Chandrasekar. And an especially huge shout out to Citrix’s Dileep Reddem for his mastery on the “under the hood” internals of ADC. Without his generous assistance this solution would likely have taken much longer.