Self-service password reset

Self-service password reset is a web-based password management solution. It is available in both the authentication, authorization, and auditing feature of Citrix ADC appliance and Citrix Gateway. It eliminates the user’s dependency on the administrator’s assistance for changing the password.

The self-service password reset provides the end user the ability to securely reset or create a password in the following scenarios:

• User has forgotten the password.
• User is unable to log on.

Until now, if an end user forgets an AD password, the end user had to contact the AD administrator to reset the password. With self-service password reset functionality, an end user can reset the password without an administrator’s intervention.

The following are some of the benefits of using self-service password reset:

• Increased productivity through an automatic password change mechanism, which eliminates the lead-time for users to wait for password resets.
• With an automatic password change mechanism, admins can concentrate on other critical tasks.

The following figure illustrates the self-service password reset flow to reset the password.

To use the self-service password reset, a user must be registered either with the Citrix authentication, authorization, and auditing or with Citrix Gateway virtual server.

Self-service password reset provides the following capabilities:

• New user self-registration. You can self-register as a new user.
• Configure knowledge-based questions. As an administrator, you can configure a set of questions for users.
• Alternate email ID registration. You must provide an alternate email ID while registration. The OTP is sent to the alternate email ID because the user has forgotten the primary email ID password.

  Note: Starting from version 12.1 build 51.xx, alternate email ID registration can be done as standalone. A new login schema, AltEmailRegister.xml is introduced to do only alternate email ID registration. Previously, alternate email ID registration can be done only while doing the KBA registration.

• Reset forgotten password. User can reset the password by answering the knowledge-based questions. As an administrator, you can configure and store the questions.

The self-service password reset provides the following two new authentication mechanisms:

• Knowledge based question and answer. You must register to Citrix authentication, authorization, and auditing or to a Citrix Gateway before selecting the knowledge-based question and answer schema.

• Email OTP authentication. An OTP is sent to the alternate email ID, which user has registered during self-service password reset registration.

Note

These authentication mechanisms can be used for the self-service password reset use cases, and for any authentication purposes similar to any of the existing authentication mechanisms.

Prerequisites

Before you configure the self-service password reset, review the following prerequisites:

• Citrix ADC feature release 12.1, build 50.28.
• Supported version is 2016, 2012, and 2008 AD domain function level.
• The ldapBind user name bound to the Citrix ADC must have write access to the users AD path.

  Note

  Self-service password reset is supported in nFactor authentication flow only. For more information, see nFactor Authentication through Citrix ADC.

Limitations

Following are some of the limitations of self-service password reset:

• Self-service password reset is available only if authentication back-end is LDAP.
• User cannot see the already registered alternate email ID.
• Knowledge-based question and answer, and email OTP authentication and registration cannot be the first factor in the authentication flow.
• For the native plug-in and receiver, registration is supported only through the browser.
• The minimum certificate size used for self-service password reset is 1024 bytes, and must follow x.509 standard.
• Only an RSA certificate is supported for self-service password reset.

Active directory setting

The Citrix ADC knowledge-based question and answer, and email OTP uses the AD attribute to store users data. You must configure an AD attribute to store the questions and answers along with the alternate email ID. The Citrix ADC appliance stores it in the configured KB attribute in the AD user object. When configuring an AD attribute, consider the following:

• The AD attribute must support 32k value of maximum length.
• Attribute type must be a ‘DirectoryString’.
• A single AD attribute can be used for knowledge-based question and answer and alternate email ID.
• A single AD Attribute cannot be used for Native OTP and knowledge-based question and answer or alternative email ID registration.
• Citrix ADC LDAP administrator must have write access to the selected AD attribute.

You can also use an existing AD attribute. However, make sure that the attribute you plan to use is not used for other cases. For example, userParameters is an existing attribute within the AD user that you can use. To verify this attribute, perform the following steps:

1. Navigate to ADSI > select user.
2. Right-click and scroll down to attribute list.
3. On the CN=testuser Properties window pane, you can see the userParameters attribute is not set.

Self-service password reset registration

To implement the self-service password reset solution on a Citrix ADC appliance, you have to perform the following:

• Self-service password reset (knowledge-based question and answer/email ID) registration.
• User Logon Page (for password reset, which includes knowledge-based question and answer and email OTP validation and final password reset factor).

A set of predefined questions catalog is provided as a JSON file. As an administrator, you can select the questions and create a self-service password reset registration login schema through the Citrix ADC GUI. You can choose any of the following options:

• Select a maximum of four system-defined questions.
• Provide an option for users to customize two questions and answers.

To view the default knowledge-based questions JSON file from CLI

Note

• Citrix Gateway includes the set of system-defined questions by default. Administrator can edit the “KBQuestions.json” file to include their choice of questions.

• System-defined questions are displayed only in English and language localization support is not available for these questions.

To complete knowledge-based question and answer registration Login Schema using GUI

1. Navigate to Security > AAA – Application Traffic > Login Schema.

   

2. On the Login Schema page, click Profiles.
3. Click Add KBA Registration Login Schema.

4. On the Create Authentication Login Schema page, specify a name in the Schema Name field.

   

   

5. Select the questions of your choice and move it to the Configured list.

6. In the User Defined Questions section, you can provide questions and answers in the Q1 and A1 fields.

   

7. In the Email Registration section, check the Register Alternate Email option. You can register the Alternate Email ID from user registration logon page to receive the OTP.

   

8. Click Create. The login schema once generated displays all the configured questions to the end user during registration process.

Create user registration and management workflow using CLI

The following are required before you begin the configuration:

• IP address assigned to the authentication virtual server
• FQDN corresponding to the assigned IP address
• Server certificate for authentication virtual server

To set up the device registration and management page, you require an authentication virtual server. The following figure illustrates the user registration.

To create authentication virtual server

1. Configure an authentication virtual server. It must be of type SSL and make sure to bind authentication virtual server with portal theme.

   > add authentication vserver <vServerName> SSL <ipaddress> <port>
   > bind authentication vserver <vServerName> [-portaltheme<string>]
   

2. Bind SSL virtual server certificate-key pair.

   > bind ssl vserver <vServerName> certkeyName <string>
   

   Example:

   > add authentication vserver authvs SSL 1.2.3.4 443
   > bind authentication vserver authvs -portaltheme RFWebUI
   > bind ssl vserver authvs -certkeyname c1
   

To create LDAP logon action

    > add authentication ldapAction <name> {-serverIP <ipaddr|ipv6\_addr|> \[-serverPort <port>] \[-ldapBase <BASE> ] \[-ldapBindDn <AD USER>] \[-ldapBindDnPassword <PASSWORD>] \[-ldapLoginName <USER FORMAT>]

Note

You can configure any authentication policy as the first factor.

Example:

    > add authentication ldapAction ldap_logon_action -serverIP 1.2.3.4 -serverPort 636 -ldapBase "OU=Users,DC=server,DC=com" -ldapBindDn administrator@ctxnsdev.com -ldapBindDnPassword PASSWORD -ldapLoginName samAccountName -serverport 636 -sectype SSL -KBAttribute userParameters

To create authentication policy for LDAP logon

    > add authentication policy <name> <rule> [<reqAction]

Example:

    > add authentication policy ldap_logon -rule true -action ldap_logon_action

To create knowledge-based question and answer registration action

Two new parameters are introduced in ldapaction. “KBAttribute” for KBA Authentication (Registration and validation) and “alternateEmailAttr” for registration of user’s alternate email ID.

    > add authentication ldapAction <name> {-serverIP  <ipaddr|ipv6\_addr|> \[-serverPort <port>] \[-ldapBase <BASE> ] \[-ldapBindDn <AD USER>] \[-ldapBindDnPassword <PASSWORD>] \[-ldapLoginName <USER FORMAT>] \[-KBAttribute <LDAP ATTRIBUTE>] \[-alternateEmailAttr <LDAP ATTRIBUTE>]

Example:

    > add authentication ldapAction ldap1 -serverIP 1.2.3.4 -sectype ssl -serverPort 636 -ldapBase "OU=Users,DC=server,DC=com" -ldapBindDn administrator@ctxnsdev.com -ldapBindDnPassword PASSWORD -ldapLoginName samAccountName -KBAttribute userParameters -alternateEmailAttr userParameters

Display user registration and management screen

The “KBARegistrationSchema.xml” login schema is used to display the user registration page to the end user. Use the following CLI to display the login schema.

> add authentication loginSchema <name> -authenticationSchema <string>

Example:

> add authentication loginSchema kba_register -authenticationSchema /nsconfig/loginschema/LoginSchema/KBARegistrationSchema.xml

Citrix recommends two ways of displaying the user registration and management screen: URL or LDAP Attribute.

Using the URL

If the URL path contains ‘/register’ (for example, https://lb1.server.com/register) then the user registration page is displayed using URL.

To create and bind a registration policy

> add authentication policylabel user_registration -loginSchema kba_register
> add authentication policy ldap1 -rule true -action ldap1
> bind authentication policylabel user_registration -policy ldap1 -priority 1

To bind authentication policy to authentication, authorization, and auditing virtual server when the URL contains ‘/register’

> add authentication policy ldap_logon -rule "http.req.cookie.value(\"NSC_TASS\").contains(\"register\")" -action ldap_logon
> bind authentication vserver authvs -policy ldap_logon -nextfactor user_registration -priority 1

To bind certificate to VPN global

bind vpn global -userDataEncryptionKey c1

Note

You must bind the certificate to encrypt the user data (KB Q&A and registered alternate email ID) stored in the AD attribute.

Using attribute

You can bind authentication policy to the authentication, authorization, and auditing virtual server to check if the user is already registered or not. In this flow, any of the preceding policies before knowledge-based question and answer registration factor need to be LDAP with KBAattribute configured. This is to check if the AD user is registered or not using an AD attribute.

Important

The rule “AAA.USER.ATTRIBUTE(“kba_registered”).EQ(“0”)” enforces new users to register for knowledge-based questions and answer and alternate email.

To create an authentication policy to check if the user is not already registered

> add authentication policy switch_to_kba_register -rule "AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"0\")" -action NO_AUTHN
> add authentication policy first_time_login_forced_kba_registration -rule true -action ldap1

To create a registration policy label and bind to the LDAP registration policy

> add authentication policylabel auth_or_switch_register -loginSchema LSCHEMA_INT
> add authentication policylabel kba_registration -loginSchema kba_register

> bind authentication policylabel auth_or_switch_register -policy switch_to_kba_register -priority 1 -nextFactor kba_registration
> bind authentication policylabel kba_registration -policy first_time_login_forced_kba_registration -priority 1

To bind authentication policy to authentication, authorization, and auditing virtual server

bind authentication vserver authvs -policy ldap_logon -nextfactor auth_or_switch_register -priority 2

User registration and management validation

Once you have configured all the steps mentioned in the previous sections, you must see the following screens.

1. Enter the load balancing virtual server URL; for example, https://lb1.server.com. The logon screen is displayed.

   

2. Enter the user name and password. Click Submit. The User Registration screen is displayed.

   

3. Select the preferred question from the drop-down list and enter the Answer.
4. Click Submit. The user registration successful screen is displayed.

Configure user logon page

In this example, the administrator assumes that the first factor is the LDAP logon (for which the end user has forgotten the password). The user then follows the knowledge-based question and answer registration and email ID OTP validation, and finally resets the password using self-service password reset.

You can use any of the authentication mechanisms for self-service password reset. Citrix recommends having either a knowledge-based question and answer, and email OTP or both to achieve strong privacy, and to avoid any illegitimate user password resets.

The following are required before you start configuring the user logon page:

• IP for load balancer virtual server
• Corresponding FQDN for the load balancer virtual server
• Server certificate for the load balancer

Create load balancer virtual server by using CLI

To access the internal website, you have to create an LB virtual server to front the back-end service and delegate the authentication logic to authentication virtual server.

> add lb vserver lb1 SSL 1.2.3.162 443 -persistenceType NONE -cltTimeout 180 -AuthenticationHost otpauth.server.com -Authentication ON -authnVsName authvs

> bind ssl vserver lb1 -certkeyname c1

To represent the backend service in load balancing:

> add service iis_backendsso_server_com 1.2.3.4 HTTP 80

> bind lb vserver lb1 iis_backendsso_server_com

Create LDAP action with authentication disabled as first policy

> add authentication ldapAction ldap3 -serverIP 1.2.3.4 -serverPort 636 -ldapBase "OU=Users,DC=server,DC=com" -ldapBindDn administrator@ctxnsdev.com -ldapBindDnPassword PASSWORD -ldapLoginName samAccountName -authentication disabled

> add authentication policy ldap3 -rule aaa.LOGIN.VALUE("passwdreset").EQ("1") -action ldap3

Create knowledge-based question and answer validation action

For knowledge-based question and answer validation in the self-service password reset flow, you need to configure an LDAP server with authentication disabled.

> add authentication ldapAction <LDAP ACTION NAME> -serverIP <SERVER IP> -serverPort <SERVER PORT> -ldapBase <BASE> -ldapBindDn <AD USER> -ldapBindDnPassword <PASSWORD> -ldapLoginName <USER FORMAT> -KBAttribute  <LDAP ATTRIBUTE> - alternateEmailAttr <LDAP ATTRIBUTE> -authentication DISABLED

Example:

> add authentication ldapAction ldap2 -serverIP 1.2.3.4 -serverPort 636 -ldapBase "OU=Users,DC=server,DC=com" -ldapBindDn administrator@ctxnsdev.com -ldapBindDnPassword PASSWORD -ldapLoginName samAccountName -KBAttribute userParameters -alternateEmailAttr userParameters -authentication disabled

To create an authentication policy for knowledge-based question and answer validation using CLI

add authentication policy kba_validation -rule true -action ldap2

Create email validation action

LDAP must be a prior factor to the email validation factor because you need the user’s email ID or alternate email ID as part of self-service password reset registration.

To configure email action using CLI

add authentication emailAction emailact -userName sender@example.com -password <Password> -serverURL "smtps://smtp.example.com:25" -content "OTP is $code"

Example:

add authentication emailAction email -userName testmail@gmail.com -password 298a34b1a1b7626cd5902bbb416d04076e5ac4f357532e949db94c0534832670 -encrypted -encryptmethod ENCMTHD_3 -serverURL "smtps://10.19.164.57:25" -content "OTP is $code" -emailAddress "aaa.user.attribute(\"alternate_mail\")"

Note

The “emailAddress” parameter in the configuration is a PI expression. Hence, this is configured to take either the default user email ID from the session or the already registered alternative email ID.

To configure email ID using GUI

1. Navigate to Security > AAA – Application Traffic > policies > Authentication > Advanced Policies > Actions > Authentication Email Action. Click Add.

2. On the Create Authentication Email Action page, fill the details, and click Create.

   

To create authentication policy for email validation by using CLI

add authentication policy email_validation -rule true -action email

To create authentication policy for password reset factor

add authentication policy ldap_pwd -rule true -action ldap_logon_action

Presenting UI through Login Schema

There are three LoginSchema’s for self-service password reset to reset the password. Use the following CLI commands to view the three Login Schema:

root@ns# cd  /nsconfig/loginschema/LoginSchema/
root@ns# ls -ltr | grep -i password
-r--r--r--  1 nobody  wheel  2088 Nov 13 08:38 SingleAuthPasswordResetRem.xml
-r--r--r--  1 nobody  wheel  1541 Nov 13 08:38 OnlyUsernamePasswordReset.xml
-r--r--r--  1 nobody  wheel  1391 Nov 13 08:38 OnlyPassword.xml

To create single authentication password reset by using CLI

> add authentication loginSchema lschema_password_reset -authenticationSchema "/nsconfig/loginschema/LoginSchema/SingleAuthPasswordResetRem.xml"

> add authentication loginSchemaPolicy lpol_password_reset -rule true -action lschema_password_reset

Create knowledge-based question and answer and email OTP validation factor through policy label

If the first factor is LDAP logon, you can create a knowledge-based question and answer and email OTP policy labels for the next factor using the following commands.

> add authentication loginSchema lschema_noschema -authenticationSchema noschema

> add authentication policylabel kba_validation -loginSchema lschema_noschema

> add authentication policylabel email_validation -loginSchema lschema_noschema

Create password reset factor through policy label

You can create the password reset factor through policy label by using the following commands.

> add authentication loginSchema lschema_noschema -authenticationSchema noschema

> add authentication policylabel password_reset -loginSchema lschema_noschema

> bind authentication policylabel password_reset -policyName ldap_pwd -priority 10 -gotoPriorityExpression NEXT

Bind the knowledge-based question and answer and email policy to the previous created policies using the following commands.

> bind authentication policylabel email_validation -policyName email_validation -nextfactor password_reset -priority 10 -gotoPriorityExpression NEXT

> bind authentication policylabel kba_validation -policyName kba_validation -nextfactor email_validation -priority 10 -gotoPriorityExpression NEXT

Bind the flow

You must have the LDAP logon flow created under the authentication policy for LDAP Logon. In this flow, the user clicks the forgot password link presented on the first LDAP logon page, then KBA validation followed by OTP validation and finally the password reset page.

`bind authentication vserver authvs -policy ldap3 -nextfactor kba_validation -priority 10 -gotoPriorityExpression NEXT`

To bind all the UI flow

`bind authentication vserver authvs -policy lpol_password_reset -priority 20 -gotoPriorityExpression END`

User logon workflow to reset password

Following is a user logon workflow if the user needs to reset password:

1. Enter the load balancing virtual server URL; for example, https://lb1.server.com. The logon screen is displayed.

   

2. Click Forgot Password. A validation screen displays two questions out of the maximum of six questions and answers registered against an AD user.

   

3. Answer the questions, and click Log on. An email OTP Validation screen where you must enter the OTP received on the registered alternate email ID, is displayed.

   

4. Enter the email OTP. Once the email OTP validation is successful, the password reset page is displayed.

   

5. Enter a new password and confirm the new password. Click Submit. After the password reset is successful, the password reset successful screen is displayed.

   

You can now log on using the reset password.

Troubleshooting

Citrix provides an option to troubleshoot some of the basic issues that you might face while using self-service password reset. The following section helps you troubleshoot some of the issues that might occur in specific areas.

NS Log

Before analyzing the logs, we recommend you to set the log level to debug using the set syslogparams -loglevel DEBUG command. When this parameter is enabled, the logs are printed in the ns.log file.

Registration

The following message indicates 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=="

Knowledge-based question and answer validation

The following message indicates successful knowledge-based question and answer validation.

"NFactor: Successfully completed KBA Validation, nextfactor is email"

Email ID validation

The following message indicates successful password reset.

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