Citrix ADC

Email OTP

Email OTP is introduced with Citrix ADC 12.1 build 51.x. The Email OTP method enables you to authenticate using the one-time password (OTP) that is sent to the registered email address. When you try to authenticate on any service, the server sends an OTP to the registered email address of the user.

To use the Email OTP feature, you must first register your alternate email ID. An alternative email ID registration is needed so that the OTP can be sent to that mail ID since you would not be able to access the primary email ID if there was an account lockout or in the event of you forgetting the AD password.

You can use Email OTP validation without email ID registration if you have provided the alternate email ID already as part of some AD attribute. You can refer to the same attribute in the email action instead of specifying the alternate email ID in the email address section.

Prerequisites

Before you configure the Email OTP feature, review the following prerequisites:

Active directory setting

  • Supported version is 2016/2012 and 2008 Active Directory domain function level
  • Citrix ADC ldapBind user name must have write access to the user’s AD path

Email Server

  • For Email OTP solution to work, ensure that the login based authentication is enabled on the SMTP server. Citrix ADC supports only Auth login based authentication for Email OTP to work.

  • To ensure that the Auth login based authentication is enabled, type the following command on the SMTP server. If the login based authentication is enabled, you notice that the text AUTH LOGIN appears in bold in the output.

Enable login based auth on SMTP server

Limitations

  • This feature is supported only if authentication back-end is LDAP.
  • Already registered alternate email ID cannot be seen.
  • Only the alternate email ID from the KBA Registration page cannot be updated.
  • KBA and Email OTP Authentication and Registration cannot be the first factors in the authentication flow. This is by design to achieve a robust authentication.
  • Same AD attribute must be configured for KBA and Alternate email ID if using the same authentication LDAP action.
  • For native plug-in and Receiver, registration is supported only through a browser.

Active Directory Configuration

  • Email OTP uses Active Directory attribute as user data storage.

  • After you register the alternate email ID, they are sent to the Citrix ADC appliance and the appliance stores it in the configured KB attribute in the AD user object.

  • The alternate email ID is encrypted and stored in the configured AD attribute.

When configuring an AD attribute, consider the following:

  • Attribute name length supported must be at least 128 characters.
  • Attribute type must be ‘DirectoryString’.
  • Same AD attribute can be used for Native OTP and KBA Registration data.
  • LDAP administrator must have write access to the selected AD attribute.

Using existing attributes

The attribute used in this example is ‘Userparameters’. As this is an existing attribute within the AD user, you do not need to make any changes to the AD itself. However, you have to make sure that the attribute is not being used.

To ensure that the attribute is not used, navigate to ADSI and select user, right-click on the user, and scroll down to the attribute list. You must see the attribute value for UserParameters as not set. This indicates that the attribute is not being used at the moment.

AD attribute settings

Configuring Email OTP

Email OTP solution consists of the following two parts:

  • Email Registration
  • Email Validation

Email Registration

There are two ways of registering a user’s alternate email ID:

  1. Along with KBA Registration
  2. Only Email ID Registration - This method is supported from 13.0 build 61.x and above; and 12.1 build 58.x and above.

Along With KBA Registration

KBA Registration LoginSchema

  1. Navigate to Security > AAA – Application Traffic > Login Schema > Profiles and click Add KBA Registration LoginSchema.

    KBA registration login schema

  2. Configure KBA Registration Authentication Schema. This loginschema once generated shows all the Questions configured for the end user during the registration process. In Email Registration section, check the Register Alternate Email option to Register user’s alternate email ID.

    Authentication login schema

    User defined questions

  3. In the Email Registration section, check Register Alternate Email to register an alternate email ID.

    Register Alternate Email

Do the following configuration using the CLI command prompt after the aforementioned KBA Registration schema is created successfully.

  1. Bind Portal Theme and Certificate to VPN global.

    bind authentication vserver authvs -portaltheme RfWebUI
    bind vpn global -userDataEncryptionKey c1
    

    Preceding certificate binding is required to encrypt the user data (KB Q&A and alternate email ID registered) stored in the AD attribute

  2. Create an LDAP Authentication policy.

    add authentication ldapAction ldap -serverIP 10.102.2.2 -serverPort 636 -ldapBase "dc=aaatm-test,dc=com" -ldapBindDn administrator@aaatm-test.com -ldapBindDnPassword freebsd -ldapLoginName samAccountName -secType SSL
    add authentication Policy ldap -rule true -action ldap
    
  3. Create a KBA Registration Loginschema and PolicyLabel.

    add authentication loginSchema Registrationschema -authenticationSchema /nsconfig/loginschema/LoginSchema/KBARegistrationSchema.xml [This is the authentication schema created in the previous section.]
    add authentication policylabel Registrationfactor -loginSchema Registrationschema
    add authentication ldapAction ldap_registration -serverIP 10.102.2.2 -serverPort 636 -ldapBase "dc=aaatm-test,dc=com" -ldapBindDn administrator@aaatm-test.com -ldapBindDnPassword freebsd -ldapLoginName samAccountName -secType SSL  -KBAttribute userParameters -alternateEmailAttr userParameters
    add authentication Policy ldap_registration -rule true -action ldap_registration
    bind authentication policylabel Registrationfactor -policyName ldap_registration -priority 1 -gotoPriorityExpression NEXT
    
  4. Bind Authentication policy to authentication virtual server.

    bind authentication vserver authvs – policy ldap -priority 1 -nextFactor Registrationfactor -gotoPriorityExpression NEXT
    
  5. Once you have configured all the steps mentioned in the previous sections, you must see the following GUI screen. Upon accessing via a URL for example, https://lb1.server.com/ you are presented with an initial login page that only requires the LDAP logon credential.

    Two factor login page

  6. After login with a valid credential, you see the user registration page as follows.

    KBA registration logon

  7. Click Submit for user registration to be successful and session to be created.

Only Email ID Registration

Do the following configuration using the CLI command prompt after the aforemention KBA registration schema is created successfully:

  1. Bind Portal Theme and Certificate to VPN global.

    bind authentication vserver authvs -portaltheme RfWebUI
    bind vpn global -userDataEncryptionKey c1
    

    Preceding Cert binding is required to encrypt the userdata (KB Q&A and alternate mail ID Registered) stored in AD attribute.

  2. Create an LDAP authentication policy.

    add authentication ldapAction ldap -serverIP 10.102.2.2 -serverPort 636 -ldapBase "dc=aaatm-test,dc=com" -ldapBindDn administrator@aaatm-test.com -ldapBindDnPassword freebsd -ldapLoginName samAccountName -secType SSL
    add authentication Policy ldap -rule true -action ldap
    
  3. Create an LDAP authentication policy for Email Registration.

    add authentication ldapAction ldap_email_registration -serverIP 10.102.2.2 -serverPort 636 -ldapBase "dc=aaatm-test,dc=com" -ldapBindDn administrator@aaatm-test.com -ldapBindDnPassword freebsd -ldapLoginName samAccountName -secType SSL -KBAttribute userParameters -alternateEmailAttr userParameters
    add authentication Policy ldap_email_registration -rule true -action ldap_email_registration
    
  4. Create an Email Registration Loginschema and PolicyLabel.

    add authentication loginSchema onlyEmailRegistration -authenticationSchema /nsconfig/loginschema/LoginSchema/AltEmailRegister.xml
    add authentication policylabel email_Registration_factor -loginSchema onlyEmailRegistration
    bind authentication policylabel email_Registration_factor -policyName ldap_email_registration -priority 1 -gotoPriorityExpression NEXT
    
  5. Bind Authentication policy to authentication virtual server.

    bind authentication vserver authvs –policy ldap -priority 1 -nextFactor email_Registration_factor -gotoPriorityExpression NEXT
    
  6. Once you have configured all the steps mentioned in the previous sections, you must see the following GUI screen. Upon accessing via URL for example, https://lb1.server.com/ you are presented with an initial login page that only requires LDAP logon credential followed by an alternate email registration page.

    Two factor login page

    Email registration logon

Email Validation

Do the following steps for Email validaition.

  1. Bind Portal Theme and Certificate to VPN global

    bind authentication vserver authvs -portaltheme RfWebUI
    bind vpn global -userDataEncryptionKey c1
    

    Preceding certificate binding is required to decrypt the userdata (KB Q&A and alternate email ID registered) stored in AD attribute.

  2. Create an LDAP Authentication policy. LDAP must be a prior factor to email validation factor because you need the user’s email ID or alternate email ID for Email OTP Validation

    add authentication ldapAction ldap1 -serverIP 10.102.2.2 -serverPort 636 -ldapBase "dc=aaatm-test,dc=com" -   ldapBindDn administrator@aaatm-test.com -ldapBindDnPassword freebsd -ldapLoginName samAccountName -secType SSL -KBAttribute userParameters -alternateEmailAttr userParameters
    add authentication Policy ldap1 -rule true -action ldap1
    
  3. Create an Email authentication policy

    add authentication emailAction email -userName sqladmin@aaa.com -password freebsd-encrypted -encryptmethod ENCMTHD_3 -serverURL "smtps://10.2.3.3:25" -content "OTP is $code" -defaultAuthenticationGroup emailgrp -emailAddress "aaa.user.attribute(\"alternate_mail\")"
    add authentication Policy email -rule true –action email
    

    In the previously mentioned command, email address is the alternate email ID user provided during KBA Registration.

  4. Create an Email OTP validation policyLabel.

    add authentication policylabel email_Validation_factor
    bind authentication policylabel email_Validation_factor -policyName email -priority 1 -gotoPriorityExpression NEXT
    
  5. Bind Authentication policy to authentication virtual server

    bind authentication vserver authvs – policy ldap1 -priority 1 -nextFactor email_Validation_factor -gotoPriorityExpression NEXT
    
  6. Once you have configured all the steps mentioned in the previous sections, you must see the following GUI screen for EMAIL OTP Validation. Upon accessing via URL for example, https://lb1.server.com/ you are presented with an initial login page that only requires the LDAP logon credential followed by the EMAIL OTP Validation page.

    In the LDAP policy it is important to configure alternateEmailAttr to be able to query the user’s email id from the AD attribute.

    Two factor login page

    OTP from email

Troubleshooting

Before analyzing the log, it is better to set the log level to debug as follows.

set syslogparams -loglevel DEBUG

Registration – Successful Scenario

The following entries indicate a successful user registration.

"ns_aaa_insert_hash_keyValue_entry key:kba_registered value:1"
Nov 14 23:35:51 <local0.debug> 10.102.229.76 11/14/2018:18:05:51 GMT  0-PPE-1 : default SSLVPN Message 1588 0 :  "ns_aaa_insert_hash_keyValue_entry key:alternate_mail value:eyJ2ZXJzaW9uIjoiMSIsICJraWQiOiIxbk1oWjN0T2NjLVVvZUx6NDRwZFhxdS01dTA9IiwgImtleSI6IlNiYW9OVlhKNFhUQThKV2dDcmJSV3pxQzRES3QzMWxINUYxQ0tySUpXd0h4SFRIdVlWZjBRRTJtM0ZiYy1RZmlQc0tMeVN2UHpleGlJc2hmVHZBcGVMZjY5dU5iYkYtYXplQzJMTFF1M3JINFVEbzJaSjdhN1pXUFhqbUVrWGdsbjdUYzZ0QWtqWHdQVUI3bE1FYVNpeXhNN1dsRkZXeWtNOVVnOGpPQVdxaz0iLCAiaXYiOiI4RmY3bGRQVzVKLVVEbHV4IiwgImFsZyI6IkFFUzI1Nl9HQ00ifQ==.oKmvOalaOJ3a9z7BcGCSegNPMw=="

Registration – Failed Scenario

On the user login page, you see the following error message, “Cannot Complete your request”. This indicates that certkey to be bounded to VPN global for encrypting the user data is missing.

Jul 31 08:51:46 <local0.info> 10.102.229.79 07/31/2020:03:21:4 6 GMT  0-PPE-1 : default SSLVPN Message 696 0 :  "Encrypt UserData: No Encryption cert is bound to vpn global"
Jul 31 08:51:46 <local0.info> 10.102.229.79 07/31/2020:03:21:46 GMT  0-PPE-1 : default SSLVPN Message 697 0 :  "KBA Register: Alternate email id Encrypted blob length is ZERO aaauser"

Email Validation – Successful Scenario

The following entries indicates a successful Email OTP Validation.

"NFactor: Successfully completed email auth, nextfactor is pwd_reset"

Email Validation – Failed Scenario

On the user login page, “Cannot Complete your request” error message is displayed. This indicates login based authentication is not enabled on the email server and the same needs to be enabled.

" /home/build/rs_130_36_15_RTM/usr.src/netscaler/aaad/pocomail.cpp[100]: void ThreadWorker_SendMailJob(SMTPJob*) 0-215: [POCO][JobID: 8]SMTP Configuration is Secure..
/home/build/rs_130_36_15_RTM/usr.src/netscaler/aaad/pocomail.cpp[108]: void ThreadWorker_SendMailJob(SMTPJob*) 0-215: [POCO][JobID: 8] First login succeeded
Wed Mar  4 17:16:28 2020
/home/build/rs_130_36_15_RTM/usr.src/netscaler/aaad/naaad.c[697]: main 0-0: timer 2 firing...
/home/build/rs_130_36_15_RTM/usr.src/netscaler/aaad/pocomail.cpp[127]: void ThreadWorker_SendMailJob(SMTPJob*) 0-0: [POCO-ERROR][JobID: 8] Poco SMTP Mail Dispatch  Failed. SMTP TYPE:1, SMTPException: Exception occurs. SMTP Exception: The mail service does not support LOGIN authentication: 250-smtprelay.citrix.com Hello [10.9.154.239]
250-SIZE 62914560
250-PIPELINING
250-DSN
250-ENHANCEDSTATUSCODES
250-8BITMIME
250-BINARYMIME
250 CHUNKING

Email OTP