Ubisecure Password Reset application is included in the Ubisecure SSO installation package. During a standard installation the software is partially installed. The application is not ready for use without explicit activation and further configuration.

Required steps

The following steps are mandatory for activating the Password Reset application.

Add SSO Server Certificate to Java Trust Store

Password Reset connects to the TLS secured SSO endpoints, so the SSO server certificate needs to be added to the trust store of the Java Runtime Environment.

How to add the SSO server certificate to JRE trust store.

Enable Password Reset web application

The Password Reset application is disabled by default. To enable it:

Run ubilogin-sso/ubilogin/tools/activate-password-reset.[sh|cmd]
Update Tomcat ubilogin-sso/ubilogin/config/tomcat/update.[sh|cmd]

The activate-password-reset script creates a new file ubilogin-sso/ubilogin/custom/password-reset/conf/server-context.xml, which contains the server context description for password-reset web application, and will be included in ubilogin-sso/ubilogin/config/tomcat/conf/server.xml file during Tomcat install or update.

If a customized version of ubilogin-sso/ubilogin/config/tomcat/conf/server.xml is used, then it is necessary to add the following line in the customized server.xml.

<Context path="/password-reset" docBase="${catalina.base}/webapps/password-reset"/>

or alternatively the following XML comment, which would then be replaced with the server-context.xml during Tomcat install or update:

<!-- BEGIN SERVER CONTEXT BLOCK FOR password-reset

END SERVER CONTEXT BLOCK FOR password-reset -->

Running the activate-password-reset script does also the following:

Enables the password method password.1 for Password Reset application.
Creates a new OTP (One Time Password) method smtp-otp.unregistered.1 of type Unregistered SMTP method.
- By default the OTP method uses "mail/Session" mail context for sending the SMTP message, that must be defined in ubilogin/custom/tomcat/mail-resources.xml. Please see configuration instructions here: Configuration of unregistered SMTP method.
Enables the OTP method smtp-otp.unregistered.1 for Password Reset application.

If you want to use Password Reset for other passwords methods than password.1, or if you want to use SMS OTP instead of / in addition to SMTP OTP, please follow the instructions below.

Enable a password method for Password Reset

To enable a password method password.x for resetting passwords with Password Reset application, do the following in SSO Management Console:

Navigate to the Password Reset site.
- Select System → Password Reset.
Add the password.x method to the Password Reset site.
- Select Site Methods → Add Method… → password.x → OK.
Add the password.x method to the allowed methods of Password Reset application.
- Select Applications → Password Reset → Allowed Methods → Check password.x → Update.

Enable an OTP method for Password Reset

Password Reset supports using Unregistered SMTP OTP and Unregistered SMS OTP method for authenticating users who have initiated the password reset.

To enable an OTP method x-otp.unregistered.y for authenticating password reset users, do the following in SSO Management Console:

Navigate to the Password Reset site.
- Select System → Password Reset.
Add the x-otp.unregistered.y method to the Password Reset site.
- Select Site Methods → Add Method… → x-otp.unregistered.y → OK.
Add the x-otp.unregistered.y method to the allowed methods of Password Reset application.
- Select Applications → Password Reset → Allowed Methods → x-otp.unregistered.y → Update.
Add the x-otp.unregistered.y method to the allowed methods of Password Reset Users group.
- Select Groups → Password Reset Users → Allowed Methods → x-otp.unregistered.y → Update.

Optional configurations

The following steps are not required to get the Password Reset activated, but can be done to activate configurations other than the default configuration - such as using Unregistered SMS OTP instead of Unregistered SMTP OTP method for user identification.

Define the OTP method used for authenticating Password Reset users

The OTP method used for authenticating users for password reset is set by configuration parameter password.reset.otpGrantTypes for the password method, which contains the grant types of the required OTP method. Each OTP method maps to a specific grant type (that is used as a grant_type attribute for OAuth 2.0 token requests). The currently supported grant types for Password Reset are:

http://globalsign.com/iam/sso/oauth2/grant-type/smtp-otp for Unregistered SMTP OTP
http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp for Unregistered SMS OTP

This parameter is optional. If omitted the default value is http://globalsign.com/iam/sso/oauth2/grant-type/smtp-otp.

Note that the respective OTP method must also be enabled for Password Reset application and Password Reset Users group, as instructed above in Enable an OTP method for Password Reset.

Example 1: To use SMS OTP with password.x, set following configuration string in password.x:

password.reset.otpGrantTypes = http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp

Require more than one OTP method before allowing password reset

It's also possible to define a comma-separated list of required grant types in password.reset.otpGrantTypes, which means that user must be authenticated with all OTP methods before password reset is allowed. The OTP methods are executed in sequence so that the method which is first in the list, if done first. Only after one is finished, the next in the list is executed.

Example 2: To use first Unregistered SMTP OTP and then Unregistered SMS OTP with password.x, set following configuration string in password.x:

password.reset.otpGrantTypes = http://globalsign.com/iam/sso/oauth2/grant-type/smtp-otp, http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp

Force system generated passwords

In some environments it may be a requirement, that users are not allowed to define the password during reset, but instead the password must be generated by the system. That's possible with Password Reset by setting the following configuration string in the password method.

policy.password.resetWithUserDefinedPwd=false

This parameter is optional. If omitted the default value is true.

Define the account attribute used for sending email with Unregistered SMTP OTP method

The name of the account attribute, whose value is used for sending the email when using Unregistered SMTP OTP method, can be set for the password method or its directory service by setting a configuration string directory.attribute.mail.

This parameter is optional. If omitted the default value is mail.

The parameter supports setting multiple values as a white-space separated list. The first attribute in the list is the primary attribute which is used if it contains a value. Only if the primary attribute doesn't contain a value, is the secondary attribute used.

directory.attribute.mail=mail secondaryMail

SQL Directory

With SQL Directory, the default value is the mail attribute in the SQL view UbiloginAccountStatus.

Setting a value for the directory.attribute.mail changes the behavior, so that the value is searched from the SQL view UbiloginAuthorizer with the given attribute name (or names) as the name.

Define the account attribute used for sending SMS with Unregistered SMS OTP method

The name of the account attribute, whose value is used for sending the SMS when using Unregistered SMS OTP method, can be set for the password method or its directory service by setting a configuration string directory.attribute.mobile.

This parameter is optional. If omitted the default value is mobile.

The parameter supports setting multiple values as a white-space separated list. The first attribute in the list is the primary attribute which is used if it contains a value. Only if the primary attribute doesn't contain a value, is the secondary attribute used.

directory.attribute.mobile=mobile secondaryMobile

SQL Directory

With SQL Directory, the default value is the mobile attribute in the SQL view UbiloginAccountStatus.

Setting a value for the directory.attribute.mobile changes the behavior, so that the value is searched from the SQL view UbiloginAuthorizer with the given attribute name (or names) as the name.

Do not reveal existence of user account when initiating password reset

By default, after a user has initiated password reset by entering their login name, they are asked to enter their OTP only if the account exists. This behavior can be changed so that the OTP is asked in any case by setting the following configuration string in the password method (SSO Management Console → Global Method Setting → Password.x). Note that this parameter affects only password reset and will not have effect on any other SSO UI screen or API call.

policy.password.dontRevealAccountStatus=true

This parameter is optional. If omitted the default value is false.

Define allowed hostnames in returnurls

By default only the hostname of password reset url is allowed to be used as the hostname for a returnurl. This behavior can be changed by setting the property returnUrl.allowedHostnames to have a white-space separated list of allowed hostnames in file ubilogin/custom/password-reset/application.properties. Note that when this property is set, then the hostname of the password reset url must be included or it would not be allowed.

Using a disallowed hostname in returnurl causes "HTTP Status 403 – Forbidden" error page to be shown.

ubilogin/custom/password-reset/application.properties

returnUrl.allowedHostnames = sso.example.com acme.com anvilcoding.com

Changes to this file require updating tomcat (ubilogin-sso/ubilogin/config/tomcat/update.[sh|cmd]).

Browser not supported