AD password method

The AD password authentication method allows you to authenticate with username and password when the credentials are stored in Active Directory. LDAPS is used to access the Active Directory. The authentication method also allows the user to change an expiring or expired password. The same Ubisecure SSO Server can connect to multiple AD directories.

To add an AD Password Method, use the Ubisecure Management application with an Administrator account:

Select Home → Global Method Settings (see Figure 1)
Select New Method…
Complete the Add New Method dialog
1. Title: A human readable name describing this method. Shown in the management user interface and possibly in the end user interface if no localization is available
2. Name: A unique system reference to this directory. This is used by administrators to identify this authentication method. Typically values are for example: password.ad, password.ad.prod, password.ad.test, password.customer1
3. Method Type: Select SPI Password
  1. Method Class: This will be automatically filled in.
4. Directory: Select the AD directory made in the previous step.
Press OK

Figure 1. Adding an AD Password Method
The method configuration screen is shown, see Figure 2.
SAML Authentication Context and SAML NameID Policy related configurations are described in the Management user interface - SSO documentation. Changes to these settings are typically not required.
Tick Enabled to enable the method
Hidden will remove this method from any system generated authentication method selection menus. This is described in more detail in the Management user interface - SSO. By default this is unselected.
Limit Method Visibility specifies to which IP netmask ranges this method will be shown in any system generated authentication method selection menus. Leave blank to show to all IP address. For AD password methods in a corporate environment, typically this is set to the netmask of domain users. This is described in more detail in the Management user interface - SSO documentation. By default this is unselected.
The Account Lockout Policy settings are ignored for AD installations. All account policy changes are performed in the Active Directory Group Policy settings of Windows.
Further configuration can be made using the Configuration String settings. Default settings are adequate for most installations. Possible configurations are described below.
Press Update to record the settings.

Figure 2. Configuring AD Password Method
Listing 1. Example Configuration string settings that can be used on the authentication method level if not already defined in the Directory Service (AD Directory)
```
directory.account.login=mail
policy.password.protocol=ActiveDirectoryLds
policy.password.expiring=36000
```
- Configuration string settings
The SPI Password tab is not used for AD Integration. Password encoding is configured in Active Directory. This value is ignored.
The Sites tab lists which sites may use this method. To activate the method for a site:
1. Open a site from the Site Navigator
2. Select the Site Methods tab
3. Press Add Method…
4. Select the newly created AD Method and press OK (See Figure 3)
5. The AD Method is now added to the site, and the site is visible from the AD Method's Sites tab (see Figure 4)
  
  Figure 3. Activating the AD Password Method for a site
  
  Figure 4. The AD Password Method can only be in the Sites shown in sites tab
The Groups tab lists which Ubilogin groups users of this method will be assigned to. Group Members settings are described in more detail in the Management user interface - SSO documentation. These settings are made from within the Methods tab of Groups.

AD OTP method

The Active Directory One-Time-Password authentication method allows you to authenticate with username, password and a one-time-password. The password is stored in Active Directory and the one-time-password list is stored in Ubisecure Directory.

This authentication method is not installed by default and must be added to Ubisecure Management application

To add the AD OTP Method, use the Ubisecure Management application with an Administrator account:

Select Home → Global Method Settings (see Figure 5)
Select New Method…
Complete the Add New Method dialog
1. Title: A human readable name describing this method. Shown in the management user interface and possibly in the end user interface if no localization is available.
2. Name: A unique system reference to this directory. This is used by administrators to identify this authentication method. Typically values are for example: otp.ad.1, otp.ad.prod, otp.ad.test, otp.customer1, ubikey.otp.1
3. Method Type: Select SPI Ubikey OTP Printout
  1. Method Class: This will be automatically filled in.
4. Directory: Select the AD directory made in the previous step.
Press OK

Figure 5. Adding an AD OTP Printout Method
The method configuration screen is shown, see Figure 6.
SAML Authentication Context and SAML NameID Policy related configurations are described in the Management user interface - SSO. Changes to these settings are typically not required.
Tick Enabled to enable the method
Hidden will remove this method from any system generated authentication method selection menus. This is described in more detail in the Management user interface - SSO documentation. By default this is unselected.
Limit Method Visibility specifies to which IP netmask ranges this method will be shown in any system generated authentication method selection menus. Leave blank to show to all IP address. For AD password methods in a corporate environment, typically this is set to the netmask of domain users. This is described in more detail in the Management user interface - SSO documentation. By default this is unselected.
The Account Lockout Policy settings here apply to the OTP code entry part of the login process.
1. Lockout Threshold (attempts): How many times an incorrect OTP number can be entered before the account is locked.
2. Lockout Duration (minutes): How many minutes an account is locked for, if the lockout threshold is exceeded. You can specify that the account will be locked out until a System Administrator or a Site Manager explicitly unlocks it by setting the value to 0.
Set the password method to use with this OTP method in the Configuration string section. Note that this is not mandatory if the password method name has already been set in the used Directory Service (AD Directory).
```
password-name=password.ad.1
```
Further configuration can be made using the Configuration String settings described below.
Press Update to record the settings. Some settings are updated to the Configuration String section.


Figure 6. Configuring AD OTP Printout Method

Select the SPI Ubikey OTP Printout tab to set the OTP list configuration options as seen in Figure 7.


Figure 7. Configuring AD OTP Printout Method OTP and Email Configuration

Set the following options:

- OTP Window Size → This configuration option defines the look-ahead window for acceptable passwords. If this option is set to 1 then only entering the next unused one-time password will result in a successful validation. MANDATORY.
- OTP Length in Digits → This configuration option defines the default length of the one-time password. MANDATORY.
- OTP List Length → This configuration option defines the default list length for the one-time passwords. This is the number of passwords in a single password list. MANDATORY.
- Mail Session JNDI Name → This configuration option specifies the application server specific mail session configuration. Email is used optionally for sending OTP lists to users. OPTIONAL.

Configuration String Settings

The following settings must be made in the Configuration String section. An example of values is shown in Listing 2 and visible in the user interface in Figure 6.

- password-name → This configuration parameter contains the name of the password method that is used by the OTP method. MANDATORY (if not set in the used Directory Service).
- policy.password.expiring → As the AD OTP authentication method uses the AD password authentication method, configuration options can also be defined for the password authentication part. So the password expiry warning can be defined here as well. If user's password is older than this he/she is given a chance to change the password. Setting value is in minutes. OPTIONAL.
- directory.account.login → Specifies the name of the user attribute to be used for the username lookup. OPTIONAL. Any user attribute which uniquely defines the user may be used. If more than one user has the same value in the attribute, login will fail with an error.
  For example, to allow an AD user to login using their email address as the username, set this value to mail.
  For example, to allow an AD user to login using their mobile phone number as the username, set this value to mobile.
  By default, SAMAccountName is used. Other typical values include:

Listing 2. Example configuration string settings for OTP printout

policy.password.expiring=36000 
password-name=password.ad.1 
directory.account.login=mail

AD SMS method

The Active Directory SMS Password authentication method allows you to authenticate with username, password and a one-time password sent to a mobile phone. The password used is stored in Active Directory.

This authentication method is not installed by default and must be added to Ubisecure Management application.

To add the AD SMS Method, use the Ubisecure Management application with an Administrator account:

Select Home → Global Method Settings (see Figure 8)
Select New Method…
Complete the Add New Method dialog
1. Title: A human readable name describing this method. Shown in the management user interface and possibly in the end user interface if no localization is available.
2. Name: A unique system reference to this directory. This is used by administrators to identify this authentication method. Typically values are for example sms.ad.1, sms.ad.prod, sms.ad.test, sms.customer1
3. Method Type: Select SPI Mobile Phone
  1. Method Class: This will be automatically filled in.
4. Directory: Select the previously created AD directory from the Services menu.
Press OK

Figure 8. Adding an AD SMS Method
The method configuration screen is shown, see Figure 9.
SAML Authentication Context and SAML NameID Policy related configurations are described in the Management user interface - SSO documentation. Changes to these settings are typically not required.
Tick Enabled to enable the method
Hidden will remove this method from any system generated authentication method selection menus. This is described in more detail in the Management user interface - SSO documentation. By default this is unselected.
Limit Method Visibility specifies to which IP netmask ranges this method will be shown in any system generated authentication method selection menus. Leave blank to show to all IP address. For AD password methods in a corporate environment, typically this is set to the netmask of domain users. This is described in more detail in the Management user interface - SSO documentation. By default this is unselected.
The Account Lockout Policy settings here apply to the OTP code entry part of the login process.
1. Lockout Threshold (attempts): How many times an incorrect OTP number can be entered before the account is locked.
2. Lockout Duration (minutes): How many minutes an account is locked for, if the lockout threshold is exceeded. You can specify that the account will be locked out until a System Administrator or a Site Manager explicitly unlocks it by setting the value to 0.
Set the password method to use with this SMS method in the Configuration string section. Note that this is not mandatory if the password method name has already been set in the used Directory Service (AD Directory).
```
password-name=password.ad.1 
```
Further configuration can be made using the Configuration String settings described below.
Press Update to record the settings. Some settings are updated to the Configuration String section.

Figure 9. Configuring AD SMS Printout Method

Select the SPI Mobile Phone tab to set the SMS gateway option as seen in Figure 13. This value depends on your SMS gateway. An example is shown here:

http://localhost:7080/smsgateway/sendsms?to={mobile}&content={challenge}

The URL contains the following variables:

{mobile} will be replaced with the user mobile phone number as visible in AD.

{challenge} will be replaced with a localized message containing the OTP. The message text can be configured using the SMS_TEXT key. Refer to Login screens - SSO for more information.

The gateway must return a HTTP status code of 200 upon successful sending of the SMS.


Figure 10. Configuring SMS Gateway

Configuration string settings

The following settings must be made in the Configuration String section. An example of values is shown in Listing 3 and visible in the user interface in Figure 9.

- password-name → This configuration parameter contains the name of the password method that is used by the SMS method. MANDATORY (if not set in the used Directory Service).
- policy.password.expiring → As the AD SMS authentication method uses the AD password authentication method, configuration options can also be defined for the password authentication part. If user's password is older than this he/she is given a chance to change the password. Setting value is in minutes. OPTIONAL.
- directory.account.login → Specifies the name of the user attribute to be used for the username lookup. OPTIONAL.
  Any user attribute which uniquely defines the user may be used. If more than one user has the same value in the attribute, login will fail with an error.
  For example, to allow an AD user to login using their email address as the username, set this value to mail.
  For example, to allow an AD user to login using their mobile phone number as the username, set this value to mobile.
  By default, SAMAccountName is used. Other typical values include:
  - uid
  - samAccountName
  - mobile
  - mail

Listing 3. Example configuration string settings for SMS

policy.password.expiring=36000 
password-name=password.ad.1 
directory.account.login=mail

Checking the installation of authentication methods

After the service and methods have been installed, check from the diagnostics log if the added service and authentication methods have started properly. The sso_diag.yyyy-mm-dd.log file is found in the ubilogin-sso/ubilogin/logs directory or available through the Log Viewer application. Below is a successful initialization.

Listing 4. Example lines from sso_diag.log

2022-10-01 10:29:29,010 uas tech INFO ActiveDirectory: root=dc=ad,dc=example,dc=com
2022-10-01 10:29:29,011 uas init INFO password.ad.1: ubilogin.method.provider.spi.DirectoryPasswordMethod: started

Using the authentication methods

Enable AD methods for sites

Before enabling AD Methods for an application, the methods must be enabled for the site where they will be used. Use the Ubisecure Management application with an Administrator account:

Select Site Navigator → (Site Name) → Site Methods
Select Add Method…
Select the desired methods.

Enable AD methods for the Application

To enable AD Methods for an application use the Ubisecure Management application with an Administrator or Site Manager account:

Select Site Navigator → (Site Name) → Applications
Select Application
Select the Allowed Methods tab.
Tick the desired methods
Press Update.

Testing login

Now you can use the selected Web Applications and test the authentication using credentials found in Active Directory.

If the default settings were used for login name, the user will enter sAMAccountName value in Username field, otherwise use mobile phone number or email address. The user domain is not required.


Figure 11. Login using AD username and password

Multiple AD or password method configuration

If two password methods are enabled for the same agent, then a domain drop down will appear. The user can select their domain from the list. This drop down can be avoided by using Limit Method Visibility to present the correct domain to the correct user group based on IP address range.


Figure 12. Login using multiple AD configurations

Identity Server 2023.1

AD authentication methods - SSO