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 the 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 an 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 the automatic password change mechanism, which eliminates the lead-time for users to wait for password resets.
• With the 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 the 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 the 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 supported on LDAPS. Self-service password reset is available only if the authentication back-end is LDAP (LDAP protocol).
• 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 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 the 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 an 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 a maximum length of 32k value.
• 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 the 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 the 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 an 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 URL

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

To create and bind 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.

• If the certificate expires, you must bind a new certificate and perform the registration again.

Using attribute

You can bind an 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 the knowledge-based question and answer registration factor must be LDAP with the KBA attribute 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 UI screen.

1. Enter the lb 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 the 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 back-end 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 the 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 an 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 the self-service password reset registration.

Note:

For the Email OTP solution to work, ensure that the login based authentication is enabled on the SMTP server.

To ensure that the 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.

root@ns# telnet <IP address of the SMTP server><Port number of the server>
ehlo

Example:

root@ns# telnet 10.106.3.66 25
Trying 10.106.3.66...
Connected to 10.106.3.66.
Escape character is '^]'.
220 E2K13.NSGSanity.com Microsoft ESMTP MAIL Service ready at Fri, 22 Nov 2019 16:24:17 +0530
ehlo
250-E2K13.NSGSanity.com Hello [10.221.41.151]
250-SIZE 37748736
250-PIPELINING
250-DSN
250-ENHANCEDSTATUSCODES
250-STARTTLS
250-X-ANONYMOUSTLS
250-AUTH LOGIN
250-X-EXPS GSSAPI NTLM
250-8BITMIME
250-BINARYMIME
250-CHUNKING
250 XRDST

For information on how to enable login based authentication, see https://support.microfocus.com/kb/doc.php?id=7020367.

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 an authentication policy for email validation by using CLI

add authentication policy email_validation -rule true -action email

To create an 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 the 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 log on workflow to reset password

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

1. Enter the lb 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 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"

Configure SSPR using nFactor visualizer

Before we begin the SSPR configuration using the nFactor visualizer, we need to add the following LDAP servers:

1. Standard LDAP server with authentication enabled for user authentication and AD attribute specified.

2. LDAP server for user parameter extraction with no auth.

3. LDAP server for password reset on SSL with no auth. Also, the AD attribute to be used for storing the user details must be defined in this server.

4. LDAP server for user registration, with authentication enabled, and AD attribute specified.

5. The following figure displays the complete flow:

   

6. Bind the certificate globally using the following CLI command:

   bind vpn global -userDataEncryptionKey Wildcard
   

Now that the LDAP servers are added, proceed with the nFactor configuration using the visualizer

1. Navigate to, Security > AAA > Application Traffic > nFactor Visualizer > nFactor Flows, click Add and click the plus icon inside the box.

2. Give the flow a name.

3. Click Add Schema that serves as the default schema. Click Add on the login schema page.

4. After giving the schema a name, select the schema. Click Select on the top right corner for the schema to be selected.

   

5. Click Create and click OK.

Once the default Schema is added, then we have to configure the following three flows:

• User registration: For explicit user registration
• Password reset: For password reset
• Normal login + Registered user check: In case the user is registered and enters the correct password, the user is logged in. In case the user is not registered it takes the user to the registration page.

User Registration

Let us continue from where we left after adding the schema.

1. Click Add Policy, this checks if the user is trying to explicitly register.

2. Click Create and then click Add.

3. Click the green ‘+’ icon, to add the next authentication factor to the user-registration flow.

   

4. Click Create.

5. Click Add Policy for User-Registration-1 factor.

6. Create the authentication policy. This policy extracts the user information and validates it before redirecting it to the registration page.

7. Click Create and then click Add.

8. Now click the green ‘+’ icon to create another factor for the user registration and click Create. Click Add Schema.

   

9. Create the authentication login schema for user registration.

10. Click Add Policy and create the authentication policy.

11. Click Create and click Add.

Password reset

1. Click the Blue ‘+’ icon to add another policy (Password reset flow) for the parent SSPR factor.

   

2. In the Choose Authentication Policy page, click Add to create an authentication policy or select an existing policy in the drop-down list. This policy is triggered if the user clicks “Forgot password” on the login page.

3. Click Add.

4. Click the green ‘+’ icon for the password reset authentication policy to add the next factor.

   

5. Click Create.

6. Click Add policy to create an authentication policy for the earlier created factor. This factor is for validating the user.

7. Click Add.

8. Click the green ‘+’ icon to add the next factor for the password factor flow. This validates the answers provided for resetting the password. Click Create.

9. Click Add Policy to add an authentication policy for the factor.

10. Select the same authentication policy from the drop-down list and click Add.

    

Normal login + Registered user check

1. Click the blue ‘+’ icon to add another authentication policy (Normal login flow) to the parent SSPR factor.

   

2. Click Add, to create an authentication policy for normal user login.

3. Click Create and then click Add.

   

4. Click the green ‘+’ icon for the earlier created policy to add the next factor and select the Create decision block option and provide a name to the decision block.

5. Click Create.

6. Click Add Policy to create an authentication policy for this decision factor.

7. Click Create then click Add. This checks if the user is registered or not.

8. Click the green ‘+’ icon on the decision block tile to point the user to the registration policy and select the Connect to existing factor option.

   

9. Select the registration factor from the Connect to drop-down list and click Create.

10. Now click the blue ‘+’ icon on the decision block tile to add another policy to the decision block. This policy is for the registered user to complete the authentication.

11. Click Add Policy to create an authentication policy.

12. Click Create and click Add.