UnboundID TOTP SASL Mechanism Handler

Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.

The UnboundID TOTP SASL Mechanism Handler may be used to perform multifactor authentication against the Directory Server using a time-based one-time password using the TOTP mechanism described in RFC 6238.

Parent Component Relations from This Component Properties dsconfig Usage

Parent Component

The UnboundID TOTP SASL Mechanism Handler component inherits from the SASL Mechanism Handler

Relations from This Component

The following components have a direct aggregation relation from UnboundID TOTP SASL Mechanism Handlers:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  None
 enabled
 identity-mapper
 shared-secret-attribute-type
 time-interval-duration
 adjacent-intervals-to-check
 require-static-password
 prevent-totp-reuse

Basic Properties

description

Description
A description for this SASL Mechanism Handler
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

enabled

Description
Indicates whether the SASL mechanism handler is enabled for use.
Default Value
None
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

identity-mapper

Description
The identity mapper that should be used to identify the user(s) targeted in the authentication and/or authorization identities contained in the bind request. This will only be used for "u:"-style identities.
Default Value
None
Allowed Values
The DN of any Identity Mapper. If this UnboundID TOTP SASL Mechanism Handler is enabled, then the associated identity mapper must also be enabled.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

shared-secret-attribute-type

Description
The name or OID of the attribute that will be used to hold the shared secret key used during TOTP processing. The key must be base32-encoded, but must not be obscured in any other way. It is strongly recommended that the specified attribute type be configured as a sensitive attribute in the server to prevent clients from being able to retrieve its value.
Default Value
ds-auth-totp-shared-secret
Allowed Values
The name or OID of an attribute type defined in the server schema.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

time-interval-duration

Description
The duration of the time interval used for TOTP processing. In order for clients to authenticate successfully, they must be configured to use the same time interval as the server.

The time interval should be large enough to allow a user to enter the generated one-time password within the interval, but small enough to minimize the length of time during which that one-time password could be re-used.

Most implementations use a default interval duration of 30 seconds, and deviating from that may limit the set of tools which may be used to generate one-time password values.

Default Value
30 seconds
Allowed Values
A duration. Lower limit is 1 seconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

adjacent-intervals-to-check

Description
The number of adjacent time intervals (both before and after the current time) that should be checked when performing authentication. It is recommended that a small number of adjacent intervals be supported to allow for clients whose clocks may be slightly skewed from that of the server, and also for cases in which the time interval changes between the time the client sent the request and the server was able to process it. However, checking too many adjacent intervals can adversely impact performance because the server will have to check up to one more than twice the configured number of adjacent intervals (one for the current interval, one for each adjacent interval before the current interval, and once for each adjacent interval after the current interval).
Default Value
2
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

require-static-password

Description
Indicates whether to require a static password (as might be held in the userPassword attribute, or whatever password attribute is defined in the password policy governing the user) in addition to the one-time password. If a static password is required, then this SASL mechanism constitutes a form of multifactor authentication, since both the static password and the one-time password will be required for successful authentication. If a static password is not required, then users will be allowed to authenticate with only a one-time password.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

prevent-totp-reuse

Description
Indicates whether to prevent clients from re-using TOTP passwords. Because a TOTP password is valid for a period of time, it is possible that a malicious individual with the ability to observe the communication between the client and the server (or is able to somehow otherwise discover both a user's static password and TOTP password) could reuse the information to authenticate as that user before the TOTP password's window of validity has expired.
If set to true, the server will check this operational attribute when processing an UNBOUNDID-TOTP bind request and will reject the bind operation if the provided TOTP password matches the most recently-used value. If the UNBOUNDID-TOTP bind is successful, then the user's entry will be updated so that the TOTP password used will not be allowed for subsequent bind attempts.
Note that setting this value to true will cause a write to the target user's entry for every successful UNBOUNDID-TOTP bind operation, and will prevent the same user from authenticating via the UNBOUNDID-TOTP mechanism multiple times within the period specified by the time-interval-duration property. As such, some environments may not wish to prevent TOTP password reuse because the negative effects may outweigh the additional security benefit.
If this configuration setting is changed, you will probably also want to make the corresponding change to the prevent-totp-reuse property in the validate TOTP password extended operation handler.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
If you change the TOTP reuse behavior in the UNBOUNDID-TOTP SASL mechanism handler, you will probably want to make the corresponding change to the prevent-totp-reuse property in the validate TOTP password extended operation handler.


dsconfig Usage

To list the configured SASL Mechanism Handlers:

dsconfig list-sasl-mechanism-handlers
     [--property {propertyName}] ...

To view the configuration for an existing SASL Mechanism Handler:

dsconfig get-sasl-mechanism-handler-prop
     --handler-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing SASL Mechanism Handler:

dsconfig set-sasl-mechanism-handler-prop
     --handler-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...