22.3. One-Time Passwords

Important

The IdM solution for OTP authentication is only supported for clients running Red Hat Enterprise Linux 7.1 or later.

One-time password (OTP) is a password valid for only one authentication session and becomes invalid after use. Unlike a traditional static password, OTP generated by an authentication token keeps changing. OTPs are used as part of two-factor authentication:

The user authenticates with a traditional password.
The user provides an OTP code generated by a recognized OTP token.

Two-factor authentication is considered safer than authentication using a traditional password alone. Even if a potential intruder intercepts the OTP during login, the intercepted OTP will already be invalid by that point because it can only be used for successful authentication once.

Warning

The following security and other limitations currently relate to the OTP support in IdM:

The most important security limitation is the potential vulnerability to replay attacks across the system. Replication is asynchronous, and an OTP code can therefore be reused during the replication period. A user might be able to log on to two servers at the same time. However, this vulnerability is usually difficult to exploit due to comprehensive encryption.
It is not possible to obtain a ticket-granting ticket (TGT) using a client that does not support OTP authentication. This might affect certain use cases, such as authentication using the mod_auth_kerb module or the Generic Security Services API (GSSAPI).
It is not possible to use password + OTP in the IdM solution if the FIPS mode is enabled.

22.3.1. How OTP Authentication Works in IdM

22.3.1.1. OTP Tokens Supported in IdM

Software and Hardware Tokens

IdM supports both software and hardware tokens.

User-managed and Administrator-managed Tokens

Users can manage their own tokens, or the administrator can manage their tokens for them:

User-managed tokens: Users have full control over user-managed tokens in Identity Management: they are allowed to create, edit, or delete their tokens.
Administrator-managed tokens: The administrator adds administrator-managed tokens to the users' accounts. Users themselves have read-only access for such tokens: they do not have the permission to manage or modify the tokens and they are not required to configure them in any way.

Note that users cannot delete or deactivate a token if it is their only active token at the moment. As an administrator, you cannot delete or deactivate your last active token, but you can delete or deactivate the last active token of another user.

Supported OTP Algorithms

Identity Management supports the following two standard OTP mechanisms:

The HMAC-Based One-Time Password (HOTP) algorithm is based on a counter. HMAC stands for Hashed Message Authentication Code.
The Time-Based One-Time Password (TOTP) algorithm is an extension of HOTP to support time-based moving factor.

22.3.1.2. Available OTP Authentication Methods

When enabling OTP authentication, you can choose from the following authentication methods:

Two-factor authentication (password + OTP): With this method, the user is always required to enter both a standard password and an OTP code.
Password: With this method, the user still has the option to authenticate using a standard password only.
RADIUS proxy server authentication: For information on configuring a RADIUS server for OTP validation, see Section 22.3.7, “Migrating from a Proprietary OTP Solution”.

Global and User-specific Authentication Methods

You can configure these authentication methods either globally or for individual users:

By default, user-specific authentication method settings take precedence over global settings. If no authentication method is set for a user, the globally-defined methods apply.
You can disable per-user authentication method settings for any user. This ensures IdM ignores the per-user settings and always applies the global settings for the user.

Combining Multiple Authentication Methods

If you set multiple methods at once, either one of them will be sufficient for successful authentication. For example:

If you configure both two-factor and password authentication, the user must provide the password (first factor), but providing the OTP (second factor) is optional when using the command line:
```
First Factor:
Second Factor (optional):
```
In the web UI, the user must still provide both factors.

Note

Individual hosts or services might be configured to require a certain authentication method, for example OTP. If you attempt to authenticate to such hosts or services using the first factor only, you will be denied access. See Section 22.4, “Restricting Access to Services and Hosts Based on How Users Authenticate”.

However, a minor exception exists when RADIUS and another authentication method are configured:

Kerberos will always use RADIUS, but LDAP will not. LDAP only recognizes the password and two-factor authentication methods.
If you use an external two-factor authentication provider, use Kerberos from your applications. If you want to let users authenticate with a password only, use LDAP. It is recommended that the applications leverage Apache modules and SSSD, which allows to configure either Kerberos or LDAP.

22.3.1.3. GNOME Keyring Service Support

IdM integrates OTP authentication with the GNOME Keyring service. Note that GNOME Keyring integration requires the user to enter the first and second factors separately:

First factor: static_password
Second factor: one-time_password

22.3.1.4. Offline Authentication with OTP

IdM supports offline OTP authentication. However, to be able to log in offline, the user must first authenticate when the system is online by entering the static password and OTP separately:

First factor: static_password
Second factor: one-time_password

If both passwords are entered separately like this when logging in online, the user will subsequently be able to authenticate even if the central authentication server is unavailable. Note that IdM only prompts for the first-factor traditional static password when the user authenticates offline.

IdM also supports entering both the static password and OTP together in one string in the First factor prompt. However, note that this is not compatible with offline OTP authentication. If the user enters both factors in a single prompt, IdM will always have to contact the central authentication server when authenticating, which requires the system to be online.

Important

If you use OTP authentication on devices that also operate offline, such as laptops, Red Hat recommends to enter the static password and OTP separately to make sure offline authentication will be available. Otherwise, IdM will not allow you to log in after the system goes offline.

If you want to benefit from OTP offline authentication, apart from entering the static and OTP passwords separately, also make sure to meet the following conditions:

The cache_credentials option in the /etc/sssd/sssd.conf file is set to True, which enables caching the first factor password.
The first-factor static password meets the password length requirement defined in the cache_credentials_minimal_first_factor_length option set in /etc/sssd/sssd.conf. The default minimal length is 8 characters. For more information about the option, see the sssd.conf(5) man page.

Note that even if the krb5_store_password_if_offline option is set to true in /etc/sssd/sssd.conf, SSSD does not attempt to refresh the Kerberos ticket-granting ticket (TGT) when the system goes online again because the OTP might already be invalid at that point. To obtain a TGT in this situation, the user must authenticate again using both factors.

22.3.2. Required Settings for Configuring a RADIUS Proxy on an IdM Server Running in FIPS Mode

In Federal Information Processing Standard (FIPS) mode, OpenSSL disables the use of the MD5 digest algorithm by default. Consequently, as the RADIUS protocol requires MD5 to encrypt a secret between the RADIUS client and the RADIUS server, the unavailability of MD5 in FIPS mode results in the IdM RADIUS proxy server to fail.

If the RADIUS server is running on the same host as the IdM master, you can work around the problem and enable MD5 within the secure perimeter, by performing the following steps:

Create the /etc/systemd/system/radiusd.service.d/ipa-otp.conf file with the following content:
```
[Service] 
Environment=OPENSSL_FIPS_NON_APPROVED_MD5_ALLOW=1
```
Reload the systemd configuration:
```
# systemctl daemon-reload
```
Start the radiusd service:
```
# systemctl start radiusd
```

22.3.3. Enabling Two Factor Authentication

For details on the available authentication methods related to OTP, see Section 22.3.1.2, “Available OTP Authentication Methods”.

To enable two factor authentication using:

the web UI, see the section called “Web UI: Enabling Two Factor Authentication”.
the command line, see the section called “Command Line: Enabling Two Factor Authentication”.

Web UI: Enabling Two Factor Authentication

To set authentication methods globally for all users:

Select IPA Server → Configuration.
In the User Options area, select the required Default user authentication types.
Figure 22.4. User Authentication Methods

To ensure the global settings are not overridden with per-user settings, select Disable per-user override. If you do not select Disable per-user override, authentication methods configured per user take precedence over the global settings.

To set authentication methods individually on a per-user basis:

Select Identity → Users, and click the name of the user to edit.
In the Account Settings area, select the required User authentication types.
Figure 22.5. User Authentication Methods

Command Line: Enabling Two Factor Authentication

To set authentication methods globally for all users:

Run the ipa config-mod --user-auth-type command. For example, to set the global authentication method to two-factor authentication:
```
$ ipa config-mod --user-auth-type=otp
```
For a list of values accepted by --user-auth-type, run the ipa config-mod --help command.
To disable per-user overrides, thus ensuring the global settings are not overridden with per-user settings, add the --user-auth-type=disabled option as well. For example, to set the global authentication method to two-factor authentication and disable per-user overrides:
```
$ ipa config-mod --user-auth-type=otp --user-auth-type=disabled
```
If you do not set --user-auth-type=disabled, authentication methods configured per user take precedence over the global settings.

To set authentication methods individually for a specified user:

Run the ipa user-mod --user-auth-type command. For example, to set that user will be required to use two-factor authentication:
```
$ ipa user-mod user --user-auth-type=otp
```

To set multiple authentication methods, add --user-auth-type multiple times. For example, to configure both password and two-factor authentication globally for all users:

$ ipa config-mod --user-auth-type=otp --user-auth-type=password

22.3.4. Adding a User-Managed Software Token

Log in with your standard password.
Make sure the FreeOTP Authenticator application is installed on your mobile device. To download FreeOTP Authenticator, see the FreeOTP source page.
Create the software token in the IdM web UI or from the command line.
- To create the token in the web UI, click Add under the OTP tokens tab. If you are logged-in as the administrator, the OTP Tokens tab is accessible through the Authentication tab.
  Figure 22.6. Adding an OTP Token for a User
- To create the token from the command line, run the ipa otptoken-add command.
```
$ ipa otptoken-add
------------------
Added OTP token ""
------------------
  Unique ID: 7060091b-4e40-47fd-8354-cb32fecd548a
  Type: TOTP
...
```
  For more information about ipa otptoken-add, run the command with the --help option added.
A QR code is displayed in the web UI or on the command line. Scan the QR code with FreeOTP Authenticator to provision the token to the mobile device.

22.3.5. Adding a User-Managed YubiKey Hardware Token

A programmable hardware token, such as a YubiKey token, can only be added from the command line. To add a YubiKey hardware token as the user owning the token:

Log in with your standard password.
Insert your YubiKey token.
Run the ipa otptoken-add-yubikey command.
- If the YubiKey has an empty slot available, the command will select the empty slot automatically.
- If no empty slot is available, you must select a slot manually using the --slot option.For example:
```
$ ipa otptoken-add-yubikey --slot=2
```
  Note that this overwrites the selected slot.

22.3.6. Adding a Token for a User as the Administrator

To add a software token as the administrator:

Make sure you are logged-in as the administrator.
Make sure the FreeOTP Authenticator application is installed on the mobile device. To download FreeOTP Authenticator, see the FreeOTP source page.
Create the software token in the IdM web UI or from the command line.
- To create the token in the web UI, select Authentication → OTP Tokens and click Add at the top of the list of OTP tokens. In the Add OTP Token form, select the owner of the token.
  Figure 22.7. Adding an Administrator-Managed Software Token
- To create the token from the command line, run the ipa otptoken-add command with the --owner option. For example:
```
$ ipa otptoken-add --owner=user
------------------
Added OTP token ""
------------------
  Unique ID: 5303baa8-08f9-464e-a74d-3b38de1c041d
  Type: TOTP
...
```
A QR code is displayed in the web UI or on the command line. Scan the QR code with FreeOTP Authenticator to provision the token to the mobile device.

To add a programmable hardware token, such as a YubiKey token, as the administrator:

Make sure you are logged-in as the administrator.
Insert the YubiKey token.
Run the ipa otptoken-add-yubikey command with the --owner option. For example:
```
$ ipa otptoken-add-yubikey --owner=user
```

22.3.7. Migrating from a Proprietary OTP Solution

To enable the migration of a large deployment from a proprietary OTP solution to the IdM-native OTP solution, IdM offers a way to offload OTP validation to a third-party RADIUS server for a subset of users. The administrator creates a set of RADIUS proxies where each proxy can contain multiple individual RADIUS servers. The administrator then assigns one of these proxy sets to a user. As long as the user has a RADIUS proxy set assigned, IdM bypasses all other authentication mechanisms.

Note

IdM does not provide any token management or synchronization support for tokens in the third-party system.

To configure a RADIUS server for OTP validation and to add a user to the proxy server:

Make sure that the radius user authentication method is enabled. See Section 22.3.3, “Enabling Two Factor Authentication” for details.
Run the ipa radiusproxy-add proxy_name --secret secret command to add a RADIUS proxy. The command prompts you for inserting the required information.
The configuration of the RADIUS proxy requires the use of a common secret between the client and the server to wrap credentials. Specify this secret in the --secret parameter.
Run the ipa user-mod radiususer --radius=proxy_name command to assign a user to the added proxy.
If required, configure the user name to be sent to RADIUS by running the ipa user-mod radiususer --radius-username=radius_user command.

As a result, the user OTP authentication will start to be processed through the RADIUS proxy server.

Note

To run a RADIUS server on an IdM master with FIPS mode enabled, additionally, perform the steps described in Section 22.3.2, “Required Settings for Configuring a RADIUS Proxy on an IdM Server Running in FIPS Mode”.

When the user is ready to be migrated to the IdM native OTP system, you can simply remove the RADIUS proxy assignment for the user.

22.3.7.1. Changing the Timeout Value of a KDC When Running a RADIUS Server in a Slow Network

In certain situations, such as running a RADIUS proxy in a slow network, the IdM KDC closes the connection before the RADIUS server responds because the connection timed out while waiting for the user to enter the token.

To change the timeout settings of the KDC:

Change the value of the timeout parameter in the [otp] section in the /var/kerberos/krb5kdc/kdc.conf file. For example, to set the timeout to 120 seconds:
```
[otp]
DEFAULT = {
  timeout = 120
  ...
}
```
Restart the krb5kdc service:
```
# systemctl restart krb5kdc
```

22.3.8. Promoting the Current Credentials to Two-Factor Authentication

If both password and two-factor authentication are configured, but you only authenticated using the password, you might be denied access to certain services or hosts (see Section 22.4, “Restricting Access to Services and Hosts Based on How Users Authenticate”). In this situation, promote your credentials from one-factor to two-factor authentication by authenticating again:

Lock your screen. The default keyboard shortcut to lock the screen is Super key+L.
Unlock your screen. When asked for credentials, use both password and OTP.

22.3.9. Resynchronizing an OTP Token

See Section B.4.3, “OTP Token Out of Sync”.

22.3.10. Replacing a Lost OTP Token

The following procedure describes how a user who lost its OTP token can replace the token:

As an administrator, enable password and OTP authentication for the user:

[admin@server]# ipa user-mod --user-auth-type=password --user-auth-type=otp user_name

The user can now add a new token. For example, to add a new token that has New Token set in the description:
```
[user@server]# ipa otptoken-add --desc="New Token"
```
For further details, enter the command the ipa otptoken-add --help parameter added.

The user can now delete the old token:

Optionally, list the tokens associated with the account:

[user@server]# ipa otptoken-find
--------------------
2 OTP tokens matched
--------------------
  Unique ID: 4ce8ec29-0bf7-4100-ab6d-5d26697f0d8f
  Type: TOTP
  Description: New Token
  Owner: user

  Unique ID: e1e9e1ef-172c-4fa9-b637-6b017ce79315
  Type: TOTP
  Description: Old Token
  Owner: user
----------------------------
Number of entries returned 2
----------------------------

Delete the old token. For example, to delete the token with the e1e9e1ef-172c-4fa9-b637-6b017ce79315 ID:

[user@server]# # ipa otptoken-del e1e9e1ef-172c-4fa9-b637-6b017ce79315
--------------------------------------------------------
Deleted OTP token "e1e9e1ef-172c-4fa9-b637-6b017ce79315"
--------------------------------------------------------

As an administrator, enable only OTP authentication for the user:
```
[admin@server]# ipa user-mod --user-auth-type=otp user_name
```