Product Documentation

Self-service password reset support

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

You can obtain the following benefits by using the SSPR:

  • Increased productivity through automatic mechanism of changing the password, which eliminates the lead-time for users to wait for password resets and account unlocks.
  • At the same time, administrator can concentrate on other critical tasks.

The following figure illustrates the flow of SSPR to reset the password.

localized image

To use SSPR, a user must be registered either with a Citrix authentication, authorization, and auditing or with Citrix Gateway virtual server.

SSPR provides the following functionalities:

  • Reset forgotten password. User can reset their password by answering the knowledge-based questions. As an administrator, you can configure and store the questions.
  • Configure knowledge-based questions. As an administrator, you can configure a set of questions for users.
  • New user self-registration. You can self-register as a new user.

The SSPR provides you with 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 validation. As a user, you must provide alternate email ID while registration. The OTP is sent to the alternate email ID if the user has forgotten primary email ID.

    Note

    These authentication mechanisms can be used for the SSPR use cases, and for any authentication purposes similar to any of the existing authentication mechanisms.

Prerequisites

Before you configure the SSPR, review the following prerequisites:

  • Citrix ADC feature release 12.1-50.x.
  • Supported version is 2012 and 2008 AD domain function level.
  • Citrix ADC ldapbind username must have write access to the users AD path.

    Note

    SSPR is supported in nFactor authentication flow only. For more information, see nFactor Authentication through Citrix ADC.

Limitations

Following are some of the limitations:

  • SSPR is available only if authentication back-end is LDAP.
  • User cannot see the already registered alternate email ID.
  • User cannot only update the alternate email ID from knowledge-based question and answer registration page.
  • 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 browser.

Active directory setting

You must configure an AD attribute to store the questions and answers along with the alternate email ID. When configuring an AD attribute, consider the following:

  • Attribute length must be at least 128 characters.
  • 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, UnixHomeDirectory is an existing attribute within the AD user that you could 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 UnixHomeDirectory attribute is not set.

localized image

SSPR registration

To implement SSPR solution on a Citrix ADC appliance, you have to perform the following:

  • SSPR (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 question catalog is provided as a JSON file. As an administrator, you can select the questions and create SSPR registration login schema through Citrix ADC GUI. You can choose any of the following two 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

localized image

Note

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

To complete knowledge-based question and answer registration LoginSchema 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.

    localized image

  4. On the Create Authentication Login Schema page, specify a name in Schema Name field.
  5. Select the questions of your choice and move it to the Configured list.

    localized image

  6. In the User Defined Questions section, define two questions with answers.
  7. In the Email Registration section, provide an alternate email ID to receive notifications, and check the Register Alternate Email option.
  8. Click Create. The loginschema once generated will display 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 setup device registration and management page, you require an authentication virtual server. The following figure illustrates the user registration.

localized image

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 <name> SSL <ipaddress> <port>
    > bind authentication vserver <name> [-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

To 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

    > 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 ldap_logon_action -serverIP 1.2.3.4 -serverPort 636 -ldapBase "OU=Users,DC=server,DC=com" -ldapBindDn administrator@ctxnsdev.com -ldapBindDnPassword PASSWORD -ldapLoginName userprincipalname  -KBAAttribute unixHomeDirectory –alternateEmailAttr unixHomeDirectory

Display user registration and management screen

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

> 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 URL.

Note

You can bind loginSchemapolicy to check if the URL contains “register” keyword.

To create loginSchemapolicy

add authentication loginSchemaPolicy registration_by_url –rule “http.req.cookie.value(\”NSC_TASS\”).contains(\”register\”)” –action kba_register

To create and bind registration policy

> add authentication policylabel user_registeration -loginSchema LSCHEMA_INT
> add authentication policy ldap1 –rule true –action ldap1
> bind authentication policylabel user_registation –policy ldap1 –priority 1

To bind LoginschemaPolicy and authenticate policy to Authentication, authorization, and auditing virtual server

> add authentication policy ldap_logon –rule true –action ldap_logon
> bind authentication vserver authvs -policy registration_by_url -priority 10 -gotoPriorityExpression END
> bind authentication vserver authvs –policy ldap_logon –nextfactor user_registration –priority 1

To bind certificate to VPN global

bind vpn global –userDataEncryptionKey c1

Note

The certificate binding is required to encrypt the user data (knowledge-based question and answer and registered alternate email ID) stored in AD attribute.

Using attribute

You can bind authentication policy to the AAA 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 needs 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("1")” enforce new users to get registered for knowledge based questions and answer and alternate email.

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

add authentication policy switch_to_kba_register -rule  "!AAA.USER.ATTRIBUTE(\"kba_registered\").EQ(\"1\")" -action ldap1

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

> add authentication policylabel auth or switch register –loginSchema LSCHEMA INT

> bind authentication policylabel auth_or_switch_register –policy switch_to_kba_register –priority 1

To bind authentication policy to AAA virtual server

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

User registration and management validation

Once the configuration is complete, you can validate the registration flow.

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

    localized image

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

    localized image

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

Configure user logon page

In this example, administrator assumes that the first factor is 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 SSPR.

You can use any of the authentication mechanisms for SSPR. 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 delegates the authentication logic to authentication virtual server.

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

> bind ssl vserver lbvs https –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 lbvs https iis backendsso server com

Create knowledge-based question and answer validation action

For knowledge-based question and answer validation in SSPR flow, you need to configure 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 userprincipalname -KBAttribute unixHomeDirectory -alternateEmailAttr  unixHomeDirectory –authentication disabled

To authenticate policy for knowledge-based question and answer validation using CLI

add authentication Policy kba validation –rule true –action ldap 2

Create email validation action

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

To configure email ID 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 > Polices > Authentication > Advanced Policies > Actions > Authentication Email Action. Click Add.
  2. On the Create Authentication Email Action page, fill the details, and click Create.

To authenticate policy for email validation by using CLI

add authentication Policy email_validation –rule true –action email

To authenticate policy for password reset factor

add authentication Policy ldap_pwdreset –rule “aaa.LOGIN.VALUE(“passwdreset”).EQ(“1”)s” –action ldap_logon

Presenting UI through LoginSchema

There are three LoginSchema’s for SSPR to reset the password. Use the following CLI commands to view the three LoginSchema:

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 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_pwdreset -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 Authentication Policy for LDAP Logon. In this flow, user clicks on forgot password link presented on first LDAP logon page, then KBA validation followed by OTP validation and finally password reset page.

bind authentication vserver authvs –policy ldap_logon –nexrfactor 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 lb vserver URL; for example, https://lb1.server.com. The logon screen is displayed.

    localized image

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

    localized image

  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.

    localized image

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

    localized image

  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.

    localized image

You can now logon using the reset password.

Troubleshooting

Citrix provides an option to troubleshoot some of the basic issues that you might face while using SSPR. The following section guides you to troubleshoot the issues that might occur in specific areas.

NS Log

Before analyzing the log, it is better to set the log level to debug the following way:

> set syslogparams –loglevel DEBUG

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"