How-to configure Citrix NetScaler as a SAML Identity Provider for Microsoft Office 365
Since I got some spare time I thought it would be cool to upgrade my Lab Environment and add the SAML Identity Provider Role to my Citrix NetScaler so that my Microsoft Office365 Account would be able to authenticate against the Citrix NetScaler IdP.
Before we start this little how-to, I assume that you already got a Citrix NetScaler up and running. The same goes for your Microsoft Office365 Account and the sync of your Users between your On-Premise Active Directory and the Azure Active Directory. DirSync and Azure AD Connect are both fine. You will need a Citrix NetScaler AAA vServer or a Citrix NetScaler Gateway vServer which is public available through SSL and a SSL Certificate which is trusted by a public CA. Additional you need another SSL Certificate which will be used to sign the SAML Tokens. This Certificate can be self signed or you can use the same public Certificate which is used for the AAA / Gateway vServer. It´s up to you.
Let´s start with the Citrix NetScaler Part. First we create a AAA or Gateway vServer. Make it public available and bind the public SSL Certificate to the vServer. Because I’m quite limited on public IPs and it´s not possible to bind more than one VPN Server to a Content Switch, I am “forced” to use my NetScaler Unified Gateway.
We have to create an LDAP Server and an LDAP Policy. The important part here is that you have to set a Value for Attribute 1. With this setting the Mail Address will be extracted from LDAP Request, which is needed by Microsoft Office 365. My LDAP Server looks like this:
You also have to create a LDAP Policy and bind the created LDAP Server to it. Nothing fancy here
In the next step we will create the SAML IdP Profile. Go to Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Polices -> SAML IdP and switch to the Profiles Tab. You need to create a Profile like this:
The complete URL within Assertion Consumer Service URL is https://login.microsoftonline.com/login.srf. In the IDP Certificate Name you will have to choose your SSL Certificate with which you will sign your SAML Tokens. Make sure the Private Key for this Certificate is present on the NetScaler! The Issuer Name should represent the Public URL of your AAA / Gateway Server. https://aaa.fqdn.com/saml/ replace aaa.fqdn.com with your public AAA / Gateway vServer. The other Values should match the Screenshots.
Of course we have to create the corresponding Policy.
Because it´s possible to bind multiple SAML IdP Policies to one AAA / Gateway Server which most certainly have different settings, I do check the Referer if it matches the Microsoft Login Page. This way you are able to create different SAML Identity Provider for different Service Providers with only one AAA / Gateway. To end the NetScaler Configuration Part it is necessary to bind the LDAP Policy and the SAML IdP Policy to our vServer. Make sure the SAML IdP Policy has the lower Priority. Your AAA / Gateway vServer should look something like this:
We will now switch to the Microsoft Office365 Part. You need to open the Windows Azure Active Directory Modul for Windows Powershell. Connect to your Azure AD using the command Connect-MsolService. In Case your Domain is already Federated to have to undo this. You do this by set the Authentication back to Managed Set-MsolDomainAuthentication -DomainName domain.com -Authentication Managed. After that it is possible to Convert the Domain back to Standard with the following command Convert-MSOLDomainToStandard –DomainName domain.com -SkipUserConversion $false -PasswordFile c:\userpasswords.txt. For more Information please read this Microsoft Documentation
We will set a few variables in the Powershell Session:
- $url = “https://aaa.fqdn.com/saml/login”
- $uri = “https://aaa.fqdn.com /saml/login”
- $ecpUrl = “https:// aaa.fqdn.com /saml/login”
- $dom = “fqdn.com”
- $fedBrandName = “Company Name”
- $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(“C:\pathtocertificate\certificate.cer”) $certData = [system.convert]::tobase64string($cert.rawdata)
You will have to replace aaa.fqdn.com with the URL of you AAA / Gateway vServer. Now you have to run the following command to switch your Domain to use your SAML IdP Set-MsolDomainAuthentication -DomainName $dom -federationBrandName $fedBrandName -Authentication Federated -PassiveLogOnUri $url -SigningCertificate $certData -IssuerUri $uri -ActiveLogOnUri $ecpUrl -LogOffUri $url –PreferredAuthenticationProtocol SAMLP
After a few Moments the changes should have been applied and Microsoft Online will redirect you to your AAA / Gateway vServer for Authentication
Some Tips and Resources:
- Microsoft Reference Article How-to Build your SAML IdP with Office365
- A List of Error Codes which can occur
- If you need to decode a SAML Requests and Response in case of intense Troubleshooting, you can of course use my SimpleSAML Debugger Modul. Link
- It´s also possible to decode the SAML Requests and Responses with the following Google Chrome Addon SAML Chrome Panel
- If you get thisError AADSTS20012: An error occurred when we tried to process a WS-Federation message. The message was invalid. Then double Check if the Users Azure ImmutableID matches the On-Premise objectGUID.