Citrix Federated Authentication Service (FAS) allows SAML based authentication tokens to be used when accessing StoreFront resources via Citrix Gateway.
In many established installations the certificates issued to the FAS server(s) will eventually expire, typically after 2 years. A simple GUI tool can be used to ‘Reauthorize’ an expired domain registration authorization certificate in this event, but an alternative PowerShell route is available to Citrix administrators so that certificates can be renewed in advance.
Citrix’s documentation proposes the following sequence of commands, without referencing the required parameters or source of information:
- Create a new authorization certificate:
New-FasAuthorizationCertificate
- Note the GUID of the new authorization certificate, as returned by:
Get-FasAuthorizationCertificate
- Place the FAS server into maintenance mode:
Set-FasServer –Address <FAS server> -MaintenanceMode $true
- Swap the new authorization certificate:
Set-FasCertificateDefinition –AuthorizationCertificate <GUID>
- Take the FAS server out of maintenance mode:
Set-FasServer –Address <FAS server> -MaintenanceMode $false
- Delete the old authorization certificate:
Remove-FasAuthorizationCertificate
Whilst this might be sufficient if you have a fair degree of confidence with PowerShell it might not be enough if you’re faced with an expired certificate and hundreds of users trying to log in.
I have used the following sequence successfully recently and hope that it will be useful to others.
NB – this example is provided ‘as-is’ and you remain responsible for understanding the effect of each command and detecting when the output doesn’t match your own scenario.
The following colourised convention applies throughout, ensure that you do not copy and paste these values without updating them:
Original FAS certificate ID reference
New FAS certificate ID reference
Certificate authority reference
- Open PowerShell on the FAS server for which you want to update the registration certificate.
- Add the Citrix commandlets into the PowerShell session:
Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
- Create a variable to hold the local FAS server’s address (if this is the second FAS server in a group of more than one, replace [0] with [1] below:
$CitrixFasAddress=(Get-FasServer)[0].Address
Address : yourfasnode01.yourdomain.com
Index : 0
Version : 1
MaintenanceMode : False
AdministrationACL : O:BAG:DUD:P(A;OICI;SW;;;BA)
- Get the existing FAS certificate ID
Get-FasAuthorizationCertificate
Id : 1c67270b-d2f4-4543-919b-519cb5470612
Address : yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA
TrustArea : bb6b4e47-c5b3-4a6a-9a50-eb6a02a05c3c
CertificateRequest :
Status : MaintenanceDue
- Generate a new FAS certificate request against the CA. Both the existing certificate and new certificate request IDs will be shown.
New-FasAuthorizationCertificate -CertificateAuthority yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA -CertificateTemplate Citrix_RegistrationAuthority
Id : 1c67270b-d2f4-4543-919b-519cb5470612
Address : yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA
TrustArea : bb6b4e47-c5b3-4a6a-9a50-eb6a02a05c3c
CertificateRequest :
Status : MaintenanceDue
Id : 2c113327-1c73-2ca4-44a3-3c12da3963b5
Address : yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA
TrustArea : 66a8d3fe-7bdb-4003-8220-cd11f7685b92
CertificateRequest :
Status : WaitingForApproval
- Log in to the certificate authority and locate the pending certificate request. Select the item, right click and choose and choose ‘Issue’. Wait a minute or two then continue.
- Repeat the process to retrieve the FAS authorisation certificates and notice that the status of the newly issued one should have changed from ‘WaitingForApproval’ to ‘Ok’.
Get-FasAuthorizationCertificate
Id : 1c67270b-d2f4-4543-919b-519cb5470612
Address : yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA
TrustArea : bb6b4e47-c5b3-4a6a-9a50-eb6a02a05c3c
CertificateRequest :
Status : MaintenanceDue
Id : 2c113327-1c73-2ca4-44a3-3c12da3963b5
Address : yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA
TrustArea : 66a8d3fe-7bdb-4003-8220-cd11f7685b92
CertificateRequest :
Status : Ok
- Set the local FAS server into maintenance mode:
Set-FasServer -Address $CitrixFasAddress -MaintenanceMode $true
- Get the FAS certificate definition rule, this points at the existing FAS authorisation certificate:
Get-FasCertificateDefinition
Name : default_Definition
CertificateAuthorities : {yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA}
MsTemplate : Citrix_SmartcardLogon
AuthorizationCertificate : 1c67270b-d2f4-4543-919b-519cb5470612
PolicyOids : {}
InSession : False
- Create a variable to store the FAS certificate authority address:
$DefaultCA=(Get-FasMsCertificateAuthority -Default).Address
- Update the existing FAS certificate definition to use the new FAS certificate ID
Set-FasCertificateDefinition -Name default_Definition -AuthorizationCertificate 2c113327-1c73-2ca4-44a3-3c12da3963b5
- Get the FAS certificate definition rule, this should now point at the new FAS authorisation certificate:
Get-FasCertificateDefinition
Name : default_Definition
CertificateAuthorities : {yourdomainca01.yourdomain.com\yourcompany-yourdomainca01-CA}
MsTemplate : Citrix_SmartcardLogon
AuthorizationCertificate : 2c113327-1c73-2ca4-44a3-3c12da3963b5
PolicyOids : {}
InSession : False
- Remove the maintenance mode flag on the local FAS server:
Set-FasServer -Address $CitrixFasAddress -MaintenanceMode $false
- Remove the original FAS authorisation certificate (no longer required)
Remove-FasAuthorizationCertificate -Id 1c67270b-d2f4-4543-919b-519cb5470612