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.
The UnboundID TOTP SASL Mechanism Handler component inherits from the SASL Mechanism Handler
The following components have a direct aggregation relation from UnboundID TOTP SASL Mechanism Handlers:
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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. |
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}] ...