OTPME-TOKEN(1)

NAME
otpme-token - manage OTPme authentication tokens

SYNOPSIS
otpme-token [--type token_type] command [options] [token]

DESCRIPTION
otpme-token manages authentication tokens in the OTPme system. Tokens are credentials assigned to users. They are identified by their path: user/token_name (e.g. alice/login).

TOKEN TYPES

hotp
    HMAC-based One-Time Password (RFC 4226).

totp
    Time-based One-Time Password (RFC 6238).

password
    Static password authentication.

ssh SSH public key authentication.

fido2
    FIDO2/WebAuthn hardware authentication.

u2f U2F hardware authentication.

yubikey_hmac
    YubiKey HMAC-SHA1 challenge-response authentication.

yubikey_hotp
    YubiKey OATH HOTP authentication.

yubikey_gpg
    YubiKey GPG applet authentication.

motp
    Mobile OTP (mOTP).

otp_push
    Push notification-based OTP.

script_otp
    OTP generation via external script.

link
    Link to another user's token.

COMMANDS

  Token Management

add [-r] token
    Add a new token. Requires --type before the command.

    For hotp and totp tokens the following extra options are available:

    --mode mode
        Token mode. Defaults to mode2. In mode2 neither the OTP secret nor the PIN are stored in the token object; the effective OTP secret is derived from the server-side secret together with the PIN. This mode is compatible with the SSO portal, but changing the PIN requires redeploying the token (a new QR code must be scanned). In mode1 the OTP secret is stored directly in the token object, so PIN changes do not require redeployment.

    --no-qrcode
        Do not display the QR code on token creation.

del token
    Delete a token.

show [token]
    Display token information.

list [regex]
    List tokens, optionally filtered by regex pattern.

enable token
    Enable a disabled token.

disable token
    Disable a token without deleting it.

rename token new_name
    Rename a token.

move [-r] token new_token_path
    Move token to another user. Use -r to replace existing token keeping its UUID.

touch token
    Re-index the object to fix potential index problems.

  Token Configuration

config [-d] token parameter [value]
    Set a configuration parameter. Use -d to delete (reset to default).

show_config token [parameter]
    Show all configuration parameters.

auto_disable [-u] token time
    Set auto-disable time (e.g. "1d" or "09:53 13.06.2023"). Use -u to disable if unused for the given time.

description token [description]
    Set token description.

info token [info]
    Set free-form info text. If info is omitted, the current info text is opened in the editor specified by the EDITOR environment variable.

dump_info token
    Dump the info text to stdout.

test token [otp|password]
    Test if given OTP/password can be verified by the token.

temp_password [--generate] [--duration time] [--remove] token [password]
    Set, generate or remove a temporary password.

  Offline Configuration

enable_offline token
    Enable offline usage (caching) of token.

disable_offline token
    Disable offline usage (caching) of token.

offline_expiry token expiry
    Set offline expiry timeout.

offline_unused_expiry token expiry
    Set offline unused expiry timeout.

  Session

enable_session_keep token
    Enable keeping of login session (e.g. on shutdown).

disable_session_keep token
    Disable keeping of login session.

  Auth Script

auth_script token script
    Change token authorization script.

enable_auth_script token
    Enable token authorization script.

disable_auth_script token
    Disable token authorization script.

  Deploy
Hardware tokens must be deployed before use. Deployment configures the physical device and registers the token in OTPme. Use --type before the command to specify the token type.

deploy --list-token-types
    List deployable token types.

  Deploy - FIDO2 and U2F

deploy [-d] [-r] token
    Register a FIDO2 or U2F hardware key. The device must be connected and will prompt for a touch.

-r  Replace existing token (keep UUID).

-d  Enable debug output.

  Deploy - YubiKey HMAC-SHA1

deploy [-d] [-r] [-n] [-s slot] [token]
    Write HMAC-SHA1 configuration to a YubiKey slot.

-s slot
    Write configuration to the given YubiKey slot.

-n  Do not reconfigure the YubiKey hardware — only register token data in OTPme.

-r  Replace existing token (keep UUID).

-d  Enable debug output.

  Deploy - YubiKey OATH HOTP

deploy [-d] [-r] [-s slot] [token]
    Write OATH HOTP configuration to a YubiKey slot.

-s slot
    Write configuration to the given YubiKey slot.

-r  Replace existing token (keep UUID).

-d  Enable debug output.

  Deploy - YubiKey GPG Applet

deploy [-d] [-r] [-n] [--backup file] [--restore file] [token]
    Initialize the GPG applet on a YubiKey and generate RSA keys. Prompts for real name, email, PIN and Admin PIN. Default backup path: /dev/shm/<username>.gpg.

--backup file
    Write GPG backup to file.

--restore file
    Restore GPG configuration from backup file.

-n  Do not initialize the GPG applet — only register token data in OTPme.

-r  Replace existing token (keep UUID).

-d  Enable debug output.

  Deploy - YubiKey PIV Applet

deploy [-d] [-r] [-n] [--key-len bits] [--backup file] [--restore file] [--restore-from-server] [--backup-key-file file] [--add-user-key] [token]
    Initialize the PIV applet on a YubiKey and generate an RSA key. Default backup path: /dev/shm/<username>_<token>.pem.

--key-len bits
    Generate RSA key with the given key length in bits.

--backup file
    Write key backup to file.

--restore file
    Restore key from backup file.

--restore-from-server
    Restore key from an existing token on the server. Requires --backup-key-file.

--backup-key-file file
    Backup key file used to decrypt the private key backup when restoring from server.

--add-user-key
    Register the token's RSA public key as the user's public key.

-n  Do not initialize the PIV applet — only register token data in OTPme.

-r  Replace existing token (keep UUID).

-d  Enable debug output.

  Dynamic Groups

add_dynamic_group token group
    Add a dynamic group to the token.

remove_dynamic_group token group
    Remove a dynamic group from the token.

list_dynamic_groups token
    List dynamic groups of the token.

  Listing

list_roles [-r] token
    List roles assigned to the token. Use -r for recursive listing.

list_hosts token
    List hosts this token is assigned to.

list_nodes token
    List nodes this token is assigned to.

list_groups token
    List groups this token is assigned to.

list_accessgroups token
    List access groups this token is assigned to.

  Policy Management

add_policy token policy
    Attach a policy to the token.

remove_policy token policy
    Remove a policy from the token.

list_policies token
    List policies attached to the token.

  ACL Management

add_acl token owner_type owner acl
    Add an access control entry.

del_acl token acl
    Remove an access control entry.

show_acls token
    Display all ACLs for the token.

enable_acl_inheritance token
    Enable ACL inheritance from parent objects.

disable_acl_inheritance token
    Disable ACL inheritance.

  Import/Export

export token
    Export token configuration to stdout.

remove_orphans token
    Remove orphaned object references.

TOKEN TYPE COMMANDS
The following commands require --type before the command.

  HOTP / TOTP / mOTP (OTP Tokens)

secret token [secret]
    Change token secret.

show_secret token
    Show token secret.

pin [--generate] token [pin]
    Change token PIN.

show_pin token
    Show token PIN.

enable_pin token
    Enable token PIN. (HOTP/TOTP only)

disable_pin token
    Disable token PIN. (HOTP/TOTP only)

gen token
    Generate token OTP.

gen_mschap token
    Generate MSCHAP challenge/response from token OTP.

gen_qrcode token
    Generate QR code for token configuration. (HOTP/TOTP only)

mode token mode
    Change token operation mode. (HOTP/TOTP only)

  HOTP Specific

counter_check_range token [range]
    Change OTP counter check range.

resync token [otp]
    Resync counter-based token.

get_token_counter token
    Get token counter value.

  mOTP Specific

validity_time token [time]
    Change OTP validity time.

timedrift_tolerance token [tolerance]
    Change OTP timedrift tolerance.

  Password Token

password [--generate] token [password]
    Change token password.

2f_token token second_factor_token
    Change second factor token.

enable_2f token
    Enable second factor token.

disable_2f token
    Disable second factor token.

enable_mschap token
    Enable MSCHAP authentication.

disable_mschap token
    Disable MSCHAP authentication.

remove_nt_hash token
    Remove NT hash used for MSCHAP authentication.

dump_pass_hash token
    Dump password hash.

set_pass_hash token file
    Set password hash from file.

upgrade_pass_hash token [hash_type] [args]
    Upgrade password hash.

  SSH Token

ssh_public_key token [ssh_public_key]
    Change token SSH public key.

card_type token [card_type]
    Set card type of SSH token (e.g. gpg).

key_type token key_type
    Set SSH key type (e.g. rsa).

password [--generate] token [password]
    Change token password.

2f_token token second_factor_token
    Change second factor token.

enable_2f / disable_2f token
    Enable/disable second factor token.

SSH tokens also support signature commands: sign, resign, verify_sign, get_sign, add_sign, del_sign.

  Link Token

add token destination_token
    Add a link token pointing to destination_token.

  YubiKey HMAC

otp_format token [format]
    Change token OTP format.

validity_time token [time]
    Change OTP validity time.

timedrift_tolerance token [tolerance]
    Change OTP timedrift tolerance.

mode token mode
    Change token operation mode.

OPTIONS

--type TYPE
    Specify the token type. Required for the add command and for all type-specific commands. Must be placed before the command.

  Display Options

-a  Show all tokens.

-z SIZE
    Limit output size.

--fields FIELD1,FIELD2
    Display only specified fields.

--role-limit N
    Limit number of roles shown.

--policy-limit N
    Limit number of policies shown.

  General Options

-r  Replace existing token and keep its UUID (for add, move, deploy).

-u  Disable if unused for the given time (auto_disable).

Global options are available for all commands. See otpme(1) for details.

CONFIG PARAMETERS
Configuration parameters can be set with the config command und displayed with show_config. For a complete description of all available parameters and their applicable object types, see otpme(7).

EXAMPLES

otpme-token --type totp add alice/totp
    Create a TOTP token for user alice

otpme-token --type fido2 deploy alice/fido2
    Deploy a FIDO2 token

otpme-token test alice/totp
    Test token authentication

otpme-token --type link add root/admin_link alice/login
    Create a link token

FILES

/var/lib/otpme/
    OTPme data directory

SEE ALSO
otpme(1), otpme(7), otpme-user(1), otpme-role(1), otpme-policy(1), otpme-accessgroup(1)

AUTHOR
the2nd <the2nd@otpme.org>

NOTE
This manual page was created with AI assistance.

COPYRIGHT
Copyright © 2014-2025 the2nd. License: GPLv3