Native OTP support for authentication
Citrix ADC appliance supports one-time passwords (OTPs) without having to use a third-party server. One-time password is a highly secure option for authenticating to secure servers as the number or passcode generated is random. Previously, OTPs are offered by specialized firms, such as RSA with specific devices that generate random numbers. This system must be in constant communication with client to generate a number expected by the server.
In addition to reducing capital and operating expenses, this feature enhances the administrator’s control by keeping the entire configuration on the Citrix ADC appliance.
Since third-party servers are no longer needed, the Citrix ADC administrator has to configure an interface to manage and validate user devices.
User must be registered with a Citrix ADC appliance virtual server to use the OTP solution. Registration is required only once per unique device, and can be restricted to certain environments. Configuring and validation of a registered user is similar to configuring an extra authentication policy.
Advantages of having native OTP support
- Reduces operating cost by eliminating the need to have an extra infrastructure on an authenticating server in addition to the Active Directory.
- Consolidates configuration only to Citrix ADC appliance thus offering great control to administrators.
- Eliminates client’s dependence on an extra authentication server for generating a number expected by clients.
Native OTP workflow
The native OTP solution is a two-fold process and the workflow is classified as following:
- Device registration
- End user login
You can skip the registration process if you are using third-party solutions or managing other devices apart from Citrix ADC appliance. The final string that you add must be in the Citrix ADC specified format.
The following figure depicts the device registration flow to register a new device to receive OTP.
The device registration can be done using any number of factors. The single factor (as specified in the previous figure) is used as an example to explain the device registration process.
The following figure depicts the verification of OTP through the registered device.
To use the native OTP feature, make sure the following prerequisites are met.
- Citrix ADC feature release version is 12.0 build 53.13 and later.
- Advanced or Premium edition license is installed on Citrix Gateway.
- Citrix ADC appliance is configured with management IP and the management console is accessible both using a browser and command line.
- Citrix ADC is configured with authentication, authorization, and auditing virtual server to authenticate users.
- Citrix ADC appliance is configured with Unified Gateway and the authentication, authorization, and auditing profile is assigned to the Gateway virtual server.
- Native OTP solution is restricted to nFactor authentication flow. Advanced policies are required to configure the solution. For more details, see article CTX222713.
Also ensure the following for Active Directory:
- A minimum attribute length of 256 characters.
- Attribute type must be ‘DirectoryString’ such as UserParameters. These attributes can hold string values.
- Attribute string type must be Unicode, if device name is in non-English characters.
- Citrix ADC LDAP administrator must have write access to the selected AD attribute.
- Citrix ADC appliance and client machine must be synced to a common Network Time Server.
Configure Native OTP using the GUI
The native OTP registration is not just a single factor authentication. The following sections help you to configure the single and second factor authentication.
Create Login Schema for first factor
- Navigate to Security AAA > Application Traffic > Login Schema.
- Go to Profiles and click Add.
- On the Create Authentication Login Schema page, enter lschema_first_factor under Name field and click Edit next to noschema.
- Click the LoginSchema folder.
- Scroll down to select SingleAuth.xml and click Select.
- Click Create.
- Click Policies and Click Add.
On the Create Authentication Login Schema Policy screen, enter the following values.
Name: lschema_first_factor Profile: select lschema_first_factor from the list. Rule: HTTP.REQ.COOKIE.VALUE(“NSC_TASS”).EQ(“manageotp”)
Configure authentication, authorization, and auditing virtual server
- Navigate to Security > AAA – Application Traffic > Authentication Virtual Servers. Click to edit the existing virtual server.
- Click the + icon next to Login Schemas under Advanced Settings in the right pane.
- Select No Login Schema.
- Click the arrow and select the lschema_first_factor policy.
- Select the lschema_first_factor policy and Click Select.
- Click Bind.
- Scroll up and select 1 Authentication Policy under Advanced Authentication Policy.
- Right-click the nFactor Policy and select Edit Binding.
- Click the + icon present under Select Next Factor, create a Next Factor, and click Bind.
On the Create Authentication PolicyLabel screen, enter the following, and click Continue:
Login Schema: Lschema_Int
On the Authentication PolicyLabel screen, click the + icon to create a Policy.
On the Create Authentication Policy screen, enter the following:
- Select the Action type using the Action Type list.
- In the Action field, click the + icon to create an Action.
In the Create Authentication LDAP server page, select Server IP radio button, deselect the check box next to Authentication, enter the following values, and select Test Connection.
IP Address: 192.168.10.11
Base DN: DC=training, DC=lab
Scroll down to the Other Settings section. Use the list to select the following options.
Server Logon Name Attribute as New and type userprincipalname.
- Use the list to select SSO Name Attribute as New and type userprincipalname.
- Enter “UserParameters” in the OTP Secret field and click More.
Enter the following Attributes.
Attribute 1 = mail Attribute 2 = objectGUID Attribute 3 = immutableID
- Click OK.
- On the Create Authentication Policy page, set the Expression to true and click Create.
- On the Create Authentication Policylabel page, click Bind, and click Done.
- On the Policy Binding page, click Bind.
- On the Authentication policy page, click Close and click Done.
The authentication virtual server must be bound to RFWebUI portal theme. Bind a server certificate to the server. The server IP ‘18.104.22.168’ must have a corresponding FQDN that is, otpauth.server.com, for later use.
Create login schema for second factor OTP
- Navigate to Security > AAA - Application Traffic > Virtual Servers. Select the virtual server to be edited.
- Scroll down and select 1 Login Schema.
- Click Add Binding.
- Under Policy Binding section, click the + icon to add a policy.
- On the Create Authentication Login Schema Policy page, enter Name as OTP, and click the + icon to create a profile.
- On the Create Authentication Login Schema page, enter Name as OTP, and click the icon next to noschema.
- Click the LoginSchema folder, select DualAuth.xml, and then click Select.
- Click Create.
- In the Rule section, enter True. Click Create.
- Click Bind.
- Notice the two factors of authentication. Click Close and click Done.
Configure content switching policy for manage OTP
The following configurations are required if you are using Unified Gateway.
Navigate to Traffic Management > Content Switching > Policies. Select the content switching policy, right click, and select Edit.
Edit the expression to evaluate the following OR statement and click OK:
Configure Native OTP using the CLI
You must have the following information to configure the OTP device management page:
- IP assigned to authentication virtual server
- FQDN corresponding to the assigned IP
- Server certificate for authentication virtual server
Native OTP is a web-based solution only.
To configure the OTP device registration and management page
Create authentication virtual server
add authentication vserver authvs SSL 22.214.171.124 443
bind authentication vserver authvs -portaltheme RFWebUI
bind ssl vserver authvs -certkeyname otpauthcert
The authentication virtual server must be bound to RFWebUI portal theme. You must bind a server certificate to the server. The server IP ‘126.96.36.199’ must have a corresponding FQDN that is, otpauth.server.com, for later use.
To create LDAP logon action
add authentication ldapAction <LDAP ACTION NAME> -serverIP <SERVER IP> - serverPort <SERVER PORT> -ldapBase <BASE> -ldapBindDn <AD USER> -ldapBindDnPassword <PASSWO> -ldapLoginName <USER FORMAT>
add authentication ldapAction ldap_logon_action -serverIP 188.8.131.52 -serverPort 636 -ldapBase "OU=Users,DC=server,DC=com" -ldapBindDn firstname.lastname@example.org -ldapBindDnPassword PASSWORD -ldapLoginName userprincipalname
To add authentication policy for LDAP Logon
add authentication Policy auth_pol_ldap_logon -rule true -action ldap_logon_action
To present UI via LoginSchema
Show user name and password fields to users upon logon
add authentication loginSchema lschema_single_auth_manage_otp -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuthManageOTP.xml"
Display device registration and management page
Citrix recommends two ways of displaying the device registration and management screen: URL or host name.
When the URL contains ‘/manageotp’
add authentication loginSchemaPolicy lpol_single_auth_manage_otp_by_url -rule "http.req.cookie.value("NSC_TASS").contains("manageotp")" -action lschema_single_auth_manage_otp
bind authentication vserver authvs -policy lpol_single_auth_manage_otp_by_url -priority 10 -gotoPriorityExpression END
When the host name is ‘alt.server.com’.
add authentication loginSchemaPolicy lpol_single_auth_manage_otp_by_host -rule "http.req.header("host").eq("alt.server.com")" -action lschema_single_auth_manage_otp
bind authentication vserver authvs -policy lpol_single_auth_manage_otp_by_host -priority 20 -gotoPriorityExpression END
To configure the user login page using the CLI
You must have the following information to configure the User Logon page:
- IP for a load balancing virtual server
- Corresponding FQDN for the load balancing virtual server
- Server certificate for the load balancing virtual server
Reuse the existing authentication virtual server (authvs) for the two-factor authentication.
To create load balancing virtual server
add lb vserver lbvs_https SSL 184.108.40.206 443 -persistenceType NONE -cltTimeout 180 - AuthenticationHost otpauth.server.com -Authentication ON -authnVsName authvs
bind ssl vserver lbvs_https -certkeyname lbvs_server_cert
Back-end service in load balancing is represented as follows:
add service iis_backendsso_server_com 220.127.116.11 HTTP 80
bind lb vserver lbvs_https iis_backendsso_server_com
To create OTP passcode validation action
add authentication ldapAction <LDAP ACTION NAME> -serverIP <SERVER IP> -serverPort <SERVER PORT> -ldapBase <BASE> -ldapBindDn <AD USER> -ldapBindDnPassword <PASSWORD> -ldapLoginName <USER FORMAT> -authentication DISABLED -OTPSecret <LDAP ATTRIBUTE>`
add authentication ldapAction ldap_otp_action -serverIP 18.104.22.168 -serverPort 636 -ldapBase "OU=Users,DC=server,DC=com" -ldapBindDn administrator@ctxnsdev. com -ldapBindDnPassword PASSWORD -ldapLoginName userprincipalname -authentication DISABLED -OTPSecret userParameters
The difference between LDAP logon and OTP action is the need to disable the authentication and introduce a new parameter “OTPSecret.” The AD attribute value must not be used.
To add authentication policy for OTP passcode validation
add authentication Policy auth_pol_otp_validation -rule true -action ldap_otp_action
To present the two-factor authentication through LoginSchema
Add the UI for two factor authentication.
add authentication loginSchema lscheme_dual_factor -authenticationSchema "/nsconfig/loginschema/LoginSchema/DualAuth.xml"
add authentication loginSchemaPolicy lpol_dual_factor -rule true -action lscheme_dual_factor
To create passcode validation factor via policy label
Create a manage OTP flow policy label for next factor (first factor is LDAP logon)
add authentication loginSchema lschema_noschema -authenticationSchema noschema
add authentication policylabel manage_otp_flow_label -loginSchema lschema_noschema
To bind the OTP policy to the policy label
bind authentication policylabel manage_otp_flow_label -policyName auth_pol_otp_validation -priority 10 -gotoPriorityExpression NEXT
To bind the UI flow
Bind the LDAP logon followed by the OTP validation with authentication virtual server.
bind authentication vserver authvs -policy auth_pol_ldap_logon -priority 10 -nextFactor manage_otp_flow_label -gotoPriorityExpression NEXT
bind authentication vserver authvs -policy lpol_dual_factor -priority 30 -gotoPriorityExpression END
Register your device with Citrix ADC
- Navigate to your Citrix ADC FQDN (first public facing IP), with a /manageotp suffix. For example,
https://otpauth.server.com/manageotpLogin with user credentials.
Click the + icon to add a device.
- Enter a device name and press Go. A barcode appears on screen.
- Click Begin Setup and then click Scan Barcode.
Hover the device camera over the QR code. You can optionally enter the 16 digit code.
The displayed QR code is valid for 3 minutes.
Upon successful scan, you are presented with a 6 digit time sensitive code that can be used to log in.
- To test, click Done on the QR screen, then click the green check mark on the right.
- Select your device from the list and enter the code from Google Authenticator (must be blue, not red) and click Go.
- Make sure to log out using the list at the top right corner of the page.
Log in to Citrix ADC using the OTP
- Navigate to your first public facing URL and enter your OTP from Google Authenticator to log on.
Authenticate to the Citrix ADC splash page.
OTP integration with third-party solutions using hardware tokens
- You don’t have to register the Citrix ADC appliance to use it as hardware token support.
- This feature is supported from Citrix ADC version 12.1 build 51.16 and later.
Citrix ADC OTP system now conforms the TOTP RFC 6238. That means, Citrix ADC uses current time in seconds along with a shared secret to compute TOTP code. Citrix ADC uses a time slice of 30 seconds and HMAC-SHA1 algorithm.
Starting from Citrix ADC version 12.1 build 51.16, ADC supports third-party solutions that use extended key size or SHA2 algorithm. Users can now configure the active directory object with larger seed value and different algorithm.
Citrix ADC stores the information on user object in active directory in the following format:
The text in capitals is the seed for TOTP. The algorithm is assumed to be HMAC-SHA1 and time slice is assumed to be 30 seconds.
For interoperability with Citrix ADC using hardware tokens or third party solutions, you can customize the string as follows:
#@mobile1=<variable length seed>&alg=sha2&,
The ‘sha2’ seed must be base32 encoded secret.
You can provide a variable length seed value. Also, you can specify “alg=sha2&,” towards the end, preceding the comma. That is, “alg=sha2” should be added after “&” but before “,.” End delimiter must always be “&,.”
Any misconfiguration apart from what is described might result in unexpected results.
Securing OTP management
There are different ways of presenting OTP management page to end users. The most common way is to present the standalone OTP management page. However, care must be taken to ensure that OTP management page is served after meeting security requirements. A minimum of two factors must be validated before presenting user with OTP management page externally. This section describes best practices for presenting the OTP management page.
Marking active directory attributes as confidential
The OTP solution natively uses user’s active directory object to store certain information used in computation of OTP codes. Although the OTP solution is highly flexible and saves significant savings for the customers, the OTP attribute carries sensitive information that is critical for OTP. Customers must ensure that only users with explicit rights are able to view contents of this attribute.
- The Citrix ADC version 13.0 build 41.20 and later offers native OTP encryption of the data that is stored on the active directory and thus provides enhanced security.
- For customers who are on earlier versions of Citrix ADC, it is recommended to mark certain attributes as confidential to protect the OTP attribute on the active directory. When the attributes are marked as confidential, only users with explicit permissions can view those attributes.
For more information on marking attributes as confidential, see;
Note: The ability to mark AD attributes as confidential was introduced in Windows Server 2003 but is available in all subsequent Windows Server versions.
Single factor registration internally
Often times, customers do not use any third party vendor for two factor authentication. If such customers want to move to Citrix ADC’s OTP, users might have only AD credentials available. In these cases, an internal site can be hosted that uses just AD or Kerberos for registration of OTP devices. SingleAuthManangeOTP.xml login schema can be used to present this page based on the source.
Dual factor registration externally
When users access OTP management page externally, users must be prompted to present a second factor for even registering their devices. If customers have other OTP solutions (RSA token or others), they must be prompted to validate that before accessing self-service portal. If customers do not use any third party tokens, then the first device can be registered only from within the premises. Subsequent devices use one of the previously registered devices’ OTP. DualAuthManageOTP.xml can be used to show two password fields to end users.
Challenges with dual factor registration externally
The challenge that customers often face is to figure out when users are external. Users can alter parts of HTTP headers such as “Host” headers. Therefore, integral part of OTP management check is identifying the source. Usually, deployments have a NAT device facing internet along with firewall. All external accesses usually happen through that NAT device’s source IP (when seen from gateway). Internal accesses typically happen directly. Customers can apply this fact to identify the source.
OTP management flow
The following flow chart illustrates a typical OTP management flow for dual factor registration.
As mentioned above, the challenge with the flow diagram is identifying whether the user is external or not. Different organizations have different network configurations to identify that. In this example, assume that the user is coming from 10.x.x.x network, and therefore the user is considered internal. However, this needs to be corrected as per customer’s network.
Steps to configure dual factor registration externally:
- Configure log in form view
add expression is_external_user “CLIENT.IP.SRC.IN_SUBNET(10.0.0.0/8).NOT && http.req.cookie.value("NSC_TASS").eq("manageotp")” add authentication loginSchema dualauth_registerotp -authenticationSchema DualAuthManageOTP.xml add authentication loginSchemaPolicy dualauth_registerotp –rule “is_external_user && http.req.cookie.value("NSC_TASS").eq("manageotp")” –action dualauth_registerotp add authentication loginSchema lschema_single_auth_manage_otp -authenticationSchema "LoginSchema/SingleAuthManageOTP.xml" add authentication loginSchemaPolicy lschema_single_auth_manage_otp -rule "!is_external_user && http.req.cookie.value("NSC_TASS").eq("manageotp")" -action lschema_single_auth_manage_otp add authentication vserver nfactor_gateway_auth SSL x.x.x.x 443
- Bind appropriate certificates
bind authentication vserver nfactor_gateway_auth -policy lschema_single_auth_manage_otp -priority 85 -gotoPriorityExpression END bind authentication vserver nfactor_gateway_auth -policy dualauth_registerotp -priority 80 -gotoPriorityExpression END
Note: Customers can also have other login schema policies at this point for actual login. These are omitted for brevity.
- Configure login factors
To configure login factors, add AD actions.
AD action for logon:
add authentication ldapAction ldap_action_login -serverIP <SERVER IP> - serverPort <SERVER PORT> -ldapBase <BASE> -ldapBindDn <AD USER> -ldapBindDnPassword <PASSWO> -ldapLoginName <USER FORMAT>
AD action for OTP validation and registration:
add authentication ldapAction ldap_action_otp -serverIP <SERVER IP> - serverPort <SERVER PORT> -ldapBase <BASE> -ldapBindDn <AD USER> -ldapBindDnPassword <PASSWO> -ldapLoginName <USER FORMAT> -authentication disabled –OTPSecret UserParameters
- Add policies
add authentication policy ldap_login_policy_internal –rule ‘!is_external_user’ –action ldap_action_login add authentication policy ldap_login_otp_validation –rule ‘is_external_user -action ldap_action_otp add authentication policy ldap_login_policy_external –rule ‘true’ –action ldap_action_login add authentication policy ldap_login_otp_management –rule ‘true’ -action ldap_action_otp
- Add the OTP factor first
add authentication policylabel otp_management_factor bind authentication policylabel otp_management_factor –policy ldap_login_otp_management –pri 100
- Add the AD validation factor for external users
add authentication policylabel ldap_login_external_factor bind authentication policylabel ldap_login_external_factor –policy ldap_login_policy_external –pri 100 –nextFactor otp_management_factor
- Bind policies to virtual server
bind authentication vserver nfactor_gateway_auth –policy ldap_login_policy_internal –pri 100 –nextFactor otp_management_factor bind authentication vserver nfactor_gateway_auth –policy ldap_login_otp_validation –pri 110 –nextFactor ldap_login_external_factor
Native OTP support for authentication
In this article
- Advantages of having native OTP support
- Native OTP workflow
- Configure Native OTP using the GUI
- Configure Native OTP using the CLI
- Display device registration and management page
- Register your device with Citrix ADC
- Log in to Citrix ADC using the OTP
- OTP integration with third-party solutions using hardware tokens
- Securing OTP management