Ubisecure Password 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.

Ubisecure Password Service Provider Activation

First install the Ubisecure SSO SAML IDP metadata by selecting first Home → Server and then the [SAML 2.0] link on the Ubisecure Server Management front page. Save the metadata file as metadata.xml in the directory ubilogin-sso/ubilogin/webapps/password/WEB-INF/saml2/sp/metadata. Note that the name of the metadata file must match another file metadata.href which should already be installed in the same directory.

Starting from SSO 8.9.0 the IDP metadata is automatically updated from the IDP metadata endpoint once every 60 seconds. The metadata file metadata.xml is used as the initial metadata, which is used only whenever the metadata endpoint cannot be accessed when the application is trying to read the metadata for the first time after boot. After the metadata gets successfully updated from the metadata endpoint, the initial metadata is no longer used for anything. It's still recommended to keep metadata.xml up-to-date, especially when the signing and/or encryption keys change, but it's not required.


Figure 1. Select SAML 2.0 to save IDP metadata file.

Then generate the SP identity and metadata. Use your public visible hostname in the Generate command URL parameter.

Generate SAML SP identity and metadata (in Windows use '\' instead of '/')

Listing 2. Generate SAML SP identity and metadata (in Windows use '\' instead of '/' and '.cmd' instead of '.sh')

ubilogin-sso> tools/ubisaml2.sh Generate https://idp.example.com/password/spsso -y -o ubilogin/webapps/password/WEB-INF/saml2/sp
ubilogin-sso> tools/ubisaml2.sh Metadata ubilogin/webapps/password/WEB-INF/saml2/sp -f password.xml

In Ubisecure Server Management, select System → Password. If there are no applications under Password, select first New Application and enter name Password and select OK. After Password is visible in the list, then select it and by clicking Activate. Upload the generated ubilogin-sso/password.xml file from the pop-up window. After setting everything, the window should look following:


Figure 2. Select Activate to upload SAML Metadata of the Password application

Configure Mail Settings

Ubisecure Password application uses email when performing the password reset functionality. Mail settings need to be configured to the ubilogin-sso/ubilogin/webapps/password/WEB-INF/web.xml file. Uncomment the context-param elements that contain mail.smtp.host and mail.smtp.from param-names. Edit the param-values according to your environment.

    <context-param>
        <param-name>mail.smtp.host</param-name>
        <param-value>smtp-gw.example.com</param-value>
    </context-param>
    <context-param>
        <param-name>mail.smtp.from</param-name>
        <param-value>password@example.com</param-value>

    </context-param>

If the SMTP server requires further values, such as authentication credentials, configure tomcat server mail/Session ( ubilogin -sso\ubilogin\config\tomcat\conf\context.xml ) like below. (In this case, the configuration instruction above can be ignored).

<?xml version='1.0' encoding='utf-8'?>
<Context reloadable="false" useHttpOnly="true" swallowOutput="true">
    <Manager pathname="" />
    <Resource name="mail/Session"
       auth="Container"
       type="javax.mail.Session"
        mail.smtp.host="host"
              mail.from="example@example.com"
              mail.user="example"
              mail.smtp.port="465"
              mail.smtp.auth="true"
              mail.smtp.user="example"
              password="password"
              mail.smtp.starttls.enable="true"
              mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"/>
</Context>

In both cases make sure that the following rows are uncommented in the ubilogin-sso/ubilogin/webapps/password/WEB-INF/web.xml file.

<context-param>
        <param-name>mail-session</param-name>
        <param-value>mail/Session</param-value>
    </context-param>    
       
    <resource-ref>
        <res-ref-name>mail/Session</res-ref-name>
        <res-type>javax.mail.Session</res-type>
        <res-auth>Container</res-auth>

    </resource-ref>

As an optional step, you can enable debug logging following the instructions in Password application logging.

Let user define password during password reset

It is possible to let user enter an own password in accordance with password policy settings by supplying the argument policy.password.resetWithUserDefinedPwd=true, to the authentication method's configuration string.

Hide information about user account status

Information related to account status, such as if it's invalid, can be hidden in password reset by setting configuration string parameter policy.dontRevealAccountStatus=true, to the authentication method's configuration string.

Note: A restart of SSO is required for the configuration to take affect.

Allow SSO session be created for user with successful password reset

By default users, who have reseted their password, are required to authenticate using the password credentials they just reset. This may seem like a mundane extra step, which could as well be skipped without compromising any security of the system, because the users must know their password already having set it a moment ago or have been given an automatically generated password in the user interface. To improve the user experience in this regard, it's possible to enable implicit authentication of the user in SSO Server after successful password reset, which is basically the same as if the user entered their password credentials explicitly in SSO Server's login screen. This functionality is called authentication injection, or AuthnInjection.

Activate the authentication provider for Password application

Create a new SAML authentication method with name saml.ap.password-reset with following configuration strings.

saml.ap.password-reset configuration string

OperationMode=shared
policy.hidden=true

Install the service provider metadata of saml.ap.password-reset authentication method by selecting the [Download Metadata] link on the SAML management page of the method. To navigate there select Home → Global Method Settings → saml.ap.password-reset → SAML. Save the metadata file in the directory ubilogin-sso/ubilogin/webapps/password/WEB-INF/saml2/ap/metadata .

Create a href file with a same name as the xml file in the same folder and insert following as its contents with correct values for entityId and url. For example, for metadata.xml the href file must be named metadata.href.

metadata.href

entityId = https://sso.example.com:8443/uas #Update to value of EntityDescriptor#entityID from metadata.xml
type = SP
url = https://sso.example.com:8443/uas/saml2/names/ac/saml.ap.password-reset/metadata.xml #Update to URL of the [Download Metadata] link for saml.ap.password-reset method
refreshInterval = 60

Generate the IDP identity and metadata by executing the commands in Listing 5 . Use your publicly visible hostname in the Generate command URL parameter.

Listing 5. Generate SAML IDP identity and metadata (in Linux use '\' instead of '/' and '.sh' instead of '.cmd')

ubilogin-sso> tools\ubisaml2.cmd Generate https://sso.example.com:8443/password/ap -compatibility LiteNoBackChannel -disable SingleLogoutService -disable SingleSignOnService -disable AssertionConsumerService -y -o ubilogin\webapps\password\WEB-INF\saml2\ap
ubilogin-sso> tools\ubisaml2.cmd Metadata ubilogin\webapps\password\WEB-INF\saml2\ap -idp -f saml.ap.password-reset.xml

In SSO Management, select Home → Global Method Settings → saml.ap.password-reset → SAML → Upload. Then upload the generated ubilogin-sso/saml.ap.password-reset.xml file.

Allow authentication injection on a password method for saml.ap.password-reset

With saml.ap.password-reset activated, password reset acts as an authentication provider to inject password authentication for the password method used in the password reset. However the injection fails unless it has been explicitly allowed for the password method in question. This is done by adding the following configuration string in the password method:

methodsAllowedForAuthnInjection = saml.ap.password-reset

Note that the configuration string above needs to be added to all password methods with whom this functionality needs to work.

Enable Access to Ubisecure Password

In Ubisecure Server Management, navigate to the Password site: select System → Password
Add the password.1 authentication method to the site: select Site Methods → Add… → password.1 → OK
Add Ubilogin Directory users to the Password Users group by using the dynamic members functionality. (The following configuration is just an example. You will probably have a more detailed definition for the included users.)

Select Groups → Password Users→ Dynamic Members → Add → Service(Ubilogin Directory , Select Template(All users) → OK


Figure 3. Password Users group controls access to the Password application

Password reset with AD

The minimum length for the system generated password must be specified in the method's configuration string settings. The default length is 6 characters, which may be less than group policy defined minimum lengths.


Figure 4. Method configuration for policy.password.length=8

Future changes to password length policies in AD must be updated manually to this value.

Enable Password Web Application

The Password application is disabled by default. To enable it, edit ubilogin-sso\ubilogin\config\tomcat\conf\server.xml

Edit server.xml in Windows

copy C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\config\tomcat\conf\server.xml C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\tomcat
C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\tomcat>notepad server.xml 
Uncomment <Context path="/password" docBase="${catalina.base}/webapps/password"/> by copying it above <!-- sign
as its in the list of not used applications by default
<!--
<Context path="/cdc" docBase="${catalina.base}/webapps/cdc"/>
<Context path="/password" docBase="${catalina.base}/webapps/password"/>
<Context path="/otpserver" docBase="${catalina.base}/webapps/otpserver"/>
-->

Edit server.xml in Linux

cp /usr/local/ubisecure/ubilogin-sso/ubilogin/config/tomcat/conf/server.xml /usr/local/ubisecure/ubilogin-sso/ubilogin/custom/tomcat 
/usr/local/ubisecure/ubilogin-sso/ubilogin/custom/tomcat/>vi server.xml 
Uncomment <Context path="/password" docBase="${catalina.base}/webapps/password"/> by copying it above <!-- sign
as its in the list of not used applications by default
<!--
<Context path="/cdc" docBase="${catalina.base}/webapps/cdc"/>
<Context path="/password" docBase="${catalina.base}/webapps/password"/>
<Context path="/otpserver" docBase="${catalina.base}/webapps/otpserver"/>
-->

To complete the password application installation, run Tomcat update to update and restart SSO.

Listing 4. Update Ubisecure Server in Windows

C:\Program Files\Ubisecure\ubilogin-sso\ubilogin> config\tomcat\update.cmd

Listing 5. Update Ubisecure Server in Linux

/usr/local/ubisecure/ubilogin-sso/ubilogin# ./config/tomcat/update.sh

Accessing the Password Web Application

The application can now be accessed at the host address used in Listing 2.

The password reset by email application is found at the address:
https://idp.example.com/password/reset

The password change application is found at the address:
https://idp.example.com/password/change

Additional Information: If a returnurl is provided as a query parameter, a Cancel button redirecting to that URL is displayed on the page like illustrated in Figure 5.

https://idp.example.com/password/reset?returnUrl=https://myApplication/home


Figure 5. Password reset

Selecting the authentication method

The reset application takes an optional query string argument, method, which contains the password method to be changed. The same application can thus be used for resetting multiple methods.

https://idp.example.com/password/reset?method=password.2

Selecting the user interface template

The password application uses the same CSS style templates that are defined in SSO Server. If the user transfers to the password application during logon, the template selection will be handled by SSO, but if it's required to transfer the user from another application, it is necessary to provide the used template as a query string parameter, called template. Refer to Templates - SSO for details of how to define and create user interface templates.

Example:
https://idp.example.com/password/reset?method=password.2&template=custom

Integration with Login UI or portal applications

By default, there are no links in the user interface of the login screens for the user to access this application. The reason for this is that many installations do not require password change or reset functionality. For example, if Ubisecure CustomerID is used in conjunction with Ubisecure SSO, password change and reset functionality is provided by the CustomerID application.

Use the above links within user applications, or include links to these activities from the login UI. Instructions for adding links to the login UI are found in Login screens - SSO .


Figure 6. Example links added to login UI help box

Ubisecure Password application uses email when performing the password reset functionality. Mail settings need to be configured to the ubilogin-sso/ubilogin/webapps/password/WEB-INF/web.xml file. Uncomment the context-param elements that contain mail.smtp.host and mail.smtp.from param-names. Edit the param-values according to your environment.

Security consideration

LDAPS should always be used for the connection to the user repository where a password reset is done.

See Configuring the connection for basic LDAP integration - SSO for LDAP connection configuration.

Browser not supported