LinOTP documentation

Preface

By using LSE LinOTP you decided to use a flexible, modern authentication system.

Congratulations on your choice!

LSE LinOTP is a solution for authenticating with one time passwords. The runtime components of LSE LinOTP are available as source code, which gives you the possibility, to make your own adaption or to conduct code reviews on the software. LSE LinOTP is originally based on GNU/Linux but as it is written in Python, it might also run on other operating systems.

LSE LinOTP is lean and very gentle on resources. It is scalable from small installations up to world-spanning, redundant enterprise installations.

This manual is divided into 5 main parts.

1. The LinOTP Management Guide describes the management of users, realms and tokens.
2. The LinOTP Installation Guide explains how to install LinOTP on different operating systems.
3. The LinOTP User Guide shows the user how to use the self service portal.
4. The LinOTP Appliance Manual deals with the LinOTP Appliance. No matter if you are using the hardware appliance or the virtual appliance, here you can find how to set up and configure the appliance.
5. If you plan to adapt or extend LinOTP you can develop your own modules. How to do this is described in LinOTP Module Development Guide.

Getting Support

LSE Leading Security Experts GmbH provides Enterprise Support for LSE LinOTP.

Support via e-Mail: linotp@lsexperts.de

Telephone: +49 6151 86086 - 115

• 1. LinOTP Management Guide
  • 1. Introduction
    • 1.1. System Overview
    • 1.2. Components
    • 1.3. LinOTP core
    • 1.4. OTP Calculation
    • 1.5. UserIdResolver
    • 1.6. Authentication Modules
    • 1.7. Management Clients
    • 1.8. Features of different management clients
    • 1.9. Licenses
      • 1.9.1. LinOTP Server
      • 1.9.2. LinOTP Administration Clients (adminclients)
      • 1.9.3. LinOTP Management GUI
      • 1.9.4. LinOTP Authentication Connectors (authmodules)
      • 1.9.5. LinOTP User Connectors (useridresolver)
      • 1.9.6. LinOTP SMS Connectors
  • 2. Management Web Client
  • 3. Configure Default settings, Resolvers and Realms
    • 3.1. Default Settings
    • 3.2. Configuring UserIdResolvers
      • 3.2.1. Configuring LDAP UserIdResolver
      • 3.2.2. Configuring SQL UserIdResolver
      • 3.2.3. Configuring Passwd (Flatfile) UserIdResolver
    • 3.3. Configuring Realms
  • 4. System config
  • 5. Supported tokens
    • 5.1. Recommended Mobile Apps
      • 5.1.1. Recommended HOTP Apps
      • 5.1.2. Recommended mOTP Apps
  • 6. Managing Tokens
    • 6.1. Import tokens
      • 6.1.1. Importing tokens with the GTK client
      • 6.1.2. Importing tokens with the Web UI
    • 6.2. Viewing users in certain realms
      • 6.2.1. Viewing users in GTK client
      • 6.2.2. Viewing users in the Web UI
    • 6.3. Viewing tokens in the WebUI
    • 6.4. Assign tokens
      • 6.4.1. Multiple tokens for a user
      • 6.4.2. Assign tokens using the GTK client
      • 6.4.3. Assign tokens using the Web UI
    • 6.5. Set OTP PIN
    • 6.6. Enrolling tokens
      • 6.6.1. Enroll eToken NG-OTP
      • 6.6.2. Enroll mOTP Token
      • 6.6.3. Enroll HOTP / OATH Token
      • 6.6.4. Enroll LSE Simple Pass Token
      • 6.6.5. Enroll SMS OTP / Mobile TAN
      • 6.6.6. Enroll Remote Token
      • 6.6.7. Enroll RADIUS Token
      • 6.6.8. Enroll QR-TAN Token
      • 6.6.9. Enroll Yubikeys
      • 6.6.10. Enroll E-Mail Token
    • 6.7. Manage tokens
      • 6.7.1. Unassign
      • 6.7.2. Remove
      • 6.7.3. Disable
      • 6.7.4. Reset failcounter
      • 6.7.5. Resync token
    • 6.8. Set token realm
    • 6.9. Token info
    • 6.10. Lost token
    • 6.11. Get serial by OTP
    • 6.12. Get OTP
  • 7. Policies
    • 7.1. Selfservice policies
      • 7.1.1. OTP PIN polices
      • 7.1.2. Retrieving OTP values
    • 7.2. Admin Policies
    • 7.3. System policies
    • 7.4. License policies
    • 7.5. Enrollment Policies
      • 7.5.1. Token limits per Realm
      • 7.5.2. Token limits per user
      • 7.5.3. Random OTP PIN
      • 7.5.4. Encrypted OTP PIN
      • 7.5.5. Tokenlabels
      • 7.5.6. Auto Assignment
      • 7.5.7. Ignore Auto Assignment Pin
      • 7.5.8. Lost token
    • 7.6. Authorization Policies
      • 7.6.1. Authorization
      • 7.6.2. Token Types
      • 7.6.3. Serials
      • 7.6.4. Setting Realms
      • 7.6.5. Returning Details on validation
    • 7.7. Authentication Policies
      • 7.7.1. OTP PIN variants
      • 7.7.2. Automatic SMS sending
      • 7.7.3. SMS Text
      • 7.7.4. Authentication Passthrough
      • 7.7.5. Pass on no Token
      • 7.7.6. URL for QR-TAN token
      • 7.7.7. Challenge Response
    • 7.8. Gettoken Policies
    • 7.9. Audit Policies
    • 7.10. OCRA Policies
    • 7.11. Policy checker
    • 7.12. Importing and exporting policies
    • 7.13. Users in policies
    • 7.14. Clients in policies
    • 7.15. Best practice - policy example
      • 7.15.1. Administrators
      • 7.15.2. System
      • 7.15.3. Selfservice
  • 8. Audit Trail
    • 8.1. Logging Scopes
      • 8.1.1. Selfservice portal
      • 8.1.2. Validate
      • 8.1.3. Audit Trail
      • 8.1.4. Administrative Tasks
      • 8.1.5. System configuration
      • 8.1.6. Setting License
    • 8.2. Viewing the Audit Trail
    • 8.3. Configuration
    • 8.4. Searching the Audit Trail
      • 8.4.1. Search in SQL Audit
  • 9. Challenge Response
    • 9.1. HOTP and TOTP tokens
    • 9.2. SMS and e-mail
    • 9.3. RADIUS
  • 10. SMSProvider for SMS OTP Tokens / Mobile TANs
    • 10.1. Overview
      • 10.1.1. Triggering SMS
      • 10.1.2. Configuration
    • 10.2. SMSProvider
      • 10.2.1. HttpSMSProvider
      • 10.2.2. DeviceSMSProvider
      • 10.2.3. SmtpSMSProvider
    • 10.3. SMSProviderConfig
      • 10.3.1. HttpSMSProvider
      • 10.3.2. DeviceSMSProvider
      • 10.3.3. SmtpSMSProvider
    • 10.4. SMSProviderTimeout
  • 11. E-mail provider for e-mail token
    • 11.1. Overview
      • 11.1.1. Triggering challenge (e-mail)
      • 11.1.2. Configuration
    • 11.2. EmailProvider
      • 11.2.1. SMTPEmailProvider
    • 11.3. EmailProviderConfig
      • 11.3.1. SMTPEmailProvider
    • 11.4. EmailChallengeValidityTime
    • 11.5. EmailBlockingTimeout
  • 12. Security Module
    • 12.1. PKCS11 module and SafeNet LunaSA
    • 12.2. Password handling
  • 13. LinOTP as OpenID Provider
    • 13.1. Comfortable identity links
  • 14. Retrieving OTP values
  • 15. Self service portal
    • 15.1. Self service portal Imprint
  • 16. Tools
    • 16.1. linotp-sql-janitor
    • 16.2. linotp-tokens-used
    • 16.3. linotp-backup
    • 16.4. linotp-restore
    • 16.5. linotp-convert-token
    • 16.6. linotp-convert-xml-to-csv
    • 16.7. linotp-decrypt-otpkey
    • 16.8. LinotpLDAPProxy.pm
  • 17. Backup and Restore
    • 17.1. Disaster Recovery
  • 18. PCI DSS
  • 19. Background information and concepts
    • 19.1. Users with no token
    • 19.2. UserIdResolvers and Realms
      • 19.2.1. Authenticating with Realms and UserIdResolvers
  • 20. Usage scenarios
    • 20.1. Protection levels
  • 21. Troubleshooting
    • 21.1. LDAP/Active Directory Connection
    • 21.2. Testing the Freeradius Server
    • 21.3. RADIUS Authentication fails
    • 21.4. RADIUS server log file
    • 21.5. Access to Web API
    • 21.6. OTP Authentication
    • 21.7. LinOTP server log file
      • 21.7.1. Special logging configuration
  • 22. The linotp.ini file
    • 22.1. Auditing
      • 22.1.1. linotpAudit.type
      • 22.1.2. linotpAudit.key.private
      • 22.1.3. linotpAudit.key.public
      • 22.1.4. linotpAudit.sql.url
      • 22.1.5. linotpAudit.sql.table_prefix
      • 22.1.6. linotpAudit.sql.highwatermark
      • 22.1.7. linotpAudit.sql.lowwatermark
    • 22.2. Misc
      • 22.2.1. linotpHelp.url
      • 22.2.2. profile
      • 22.2.3. linotpGetotp.active
      • 22.2.4. linotpNoSessionCheck
      • 22.2.5. linotpSecretFile
      • 22.2.6. linotpSQL.implicit_returning
      • 22.2.7. linotpPolicy.pin_c, linotpPolicy.pin_n, linotpPolicy.pin_s
      • 22.2.8. openid_sql
      • 22.2.9. linotpOpenID.CookieExpire
      • 22.2.10. linotp.imprint_directory
      • 22.2.11. linotpTokenModules
    • 22.3. RADIUS settings
      • 22.3.1. radius.dictfile
      • 22.3.2. radius.nas_identifier
    • 22.4. Default Values
• 2. LinOTP Installation Guide
  • 1. Supported Operating Systems
    • 1.1. Supported Database systems
  • 2. Checklist
    • 2.1. Decide which distribution you want to use
    • 2.2. Decide which token database you want to use
    • 2.3. SSL certificate
    • 2.4. LinOTP Admin
    • 2.5. User databases
    • 2.6. User tokens
    • 2.7. Authentication
    • 2.8. Location in your network
  • 3. Server installation
    • 3.1. LinOTP Virtual Appliance installation
    • 3.2. Installing Debian packages
      • 3.2.1. Installing from APT repositories
    • 3.3. LinOTP Server Installation – the tar.gz, virtualenv and pip way
      • 3.3.1. Setup token database
      • 3.3.2. LinOTP and the Apache webserver
      • 3.3.3. Further changes for RedHat and CentOS 6
      • 3.3.4. Testing LinOTP Server installation
      • 3.3.5. Creating self signed SSL certificate
    • 3.4. LinOTP on Univention Corporate Server UCS
      • 3.4.1. App Center
      • 3.4.2. Join Scripts
    • 3.5. Configuration background information
      • 3.5.1. LinOTP Server configuration
  • 4. Installing Management Clients
    • 4.1. Install the Debian packages
    • 4.2. Install python packages
    • 4.3. Management Client Installation on Windows
      • 4.3.1. Installing Yubikey components
  • 5. Installing Authentication Modules
    • 5.1. Enabling PAM authentication with pam_linotp
      • 5.1.1. Configure pam_linotp
    • 5.2. Enabling RADIUS authentication with rlm_linotp2
      • 5.2.1. Configure rlm_linotp2
      • 5.2.2. Using rlm_linotp2 and SSL
      • 5.2.3. Fail-over configuration for RADIUS
    • 5.3. Enabling RADIUS authentication with Radiator
    • 5.4. Enabling RADIUS authentication with rlm_perl
      • 5.4.1. Configure radius_linotp.pm
    • 5.5. Enable SAML Identify Provider
  • 6. Customization
    • 6.1. Templates
    • 6.2. Style Sheets
    • 6.3. Changing the Logo
  • 7. Database connection
    • 7.1. Running LinOTP with DB2 on RedHat
      • 7.1.1. Overview
      • 7.1.2. Installation
      • 7.1.3. Configuration
    • 7.2. Running LinOTP with Oracle on RedHat
      • 7.2.1. Overview
      • 7.2.2. Installation
      • 7.2.3. Configuration
    • 7.3. Running LinOTP with Microsoft SQL
      • 7.3.1. Overview
      • 7.3.2. Installation
      • 7.3.3. Configuration
    • 7.4. Special parameters for database connections
      • 7.4.1. Pool recyle
      • 7.4.2. Implicit returning
  • 8. Security Modules
    • 8.1. Defining Security Modules
    • 8.2. Defining SafeNet LunaSA
      • 8.2.1. Partition Password
    • 8.3. Setting up SafeNet LunaSA
      • 8.3.1. Requirements
      • 8.3.2. Network settings
      • 8.3.3. LunaSA server certificate
      • 8.3.4. Initialization of HSM
      • 8.3.5. Setting up HSM clients and assigning clients to HSM partitions
      • 8.3.6. Troubleshooting
    • 8.4. Create AES Keys
    • 8.5. Backup and restore with LunaSA
      • 8.5.1. Backup
      • 8.5.2. Restore
    • 8.6. Setting up HA and Load balancing for LunaSA
      • 8.6.1. Register LinOTP
      • 8.6.2. Creating HA group
      • 8.6.3. Monitoring
    • 8.7. Managing Passwords with LunaSA
      • 8.7.1. Changing admin Password
      • 8.7.2. Changing HSM PED Password
      • 8.7.3. Changing Partition Passwords
      • 8.7.4. Resetting Partition Passwords
  • 9. Integration examples
    • 9.1. OTP Authentication with Apache2
      • 9.1.1. Download
      • 9.1.2. Compile
      • 9.1.3. Configuration
    • 9.2. Firewall integration
    • 9.3. Authentication with third party OTP solutions
      • 9.3.1. Configure FreeRADIUS LDAP
      • 9.3.2. Configure FreeRADIUS proxy
      • 9.3.3. Configure proxy decision
    • 9.4. Restrict access to certain devices to certain users
      • 9.4.1. Install LDAP FreeRADIUS module
      • 9.4.2. Adapt the configuration
      • 9.4.3. modules/ldap
      • 9.4.4. clients.conf
      • 9.4.5. policy.conf
      • 9.4.6. site-enabled/linotp
    • 9.5. Map certain RADIUS clients to specific LinOTP realms
      • 9.5.1. Example Data
      • 9.5.2. Configuration
      • 9.5.3. Define two client networks
      • 9.5.4. Define the mapping policy
      • 9.5.5. Add the shortname to the request
      • 9.5.6. Activate policy during authentication
    • 9.6. Authenticating RADIUS clients that pass the ntdomain
    • 9.7. LinOTP and MIT Kerberos
      • 9.7.1. Setting up OTP with Kerberos
      • 9.7.2. Setting up FAST
    • 9.8. Deny access for disabled users in Active Directory
    • 9.9. Use LDAPs in UserIdResolvers
    • 9.10. Configure a redundant MySQL database with master-master-replication
      • 9.10.1. Introduction
      • 9.10.2. Replication user
      • 9.10.3. Configure replication
      • 9.10.4. Setup slaves
      • 9.10.5. Synching the machines
  • 10. Updates
    • 10.1. Updating from LinOTP 2.6.1.1 to LinOTP 2.7
      • 10.1.1. Updating a deb install
      • 10.1.2. Updating a pip install
      • 10.1.3. Changelog
    • 10.2. Updating from LinOTP 2.6.1 to LinOTP 2.6.1.1
      • 10.2.1. Updating a deb install
      • 10.2.2. Updating a pip install
      • 10.2.3. Changelog
    • 10.3. Updating from LinOTP 2.6.0.3 to LinOTP 2.6.1
      • 10.3.1. Updating a deb install
      • 10.3.2. Updating a pip install
      • 10.3.3. Changelog
    • 10.4. Updating from LinOTP 2.6 to LinOTP 2.6.0.3
      • 10.4.1. Updating a deb install
      • 10.4.2. Updating a pip install
      • 10.4.3. Changelog
    • 10.5. Updating from LinOTP 2.6 to LinOTP 2.6.0.1
      • 10.5.1. Updating a deb install
      • 10.5.2. Updating a pip install
      • 10.5.3. Changelog
    • 10.6. Updating from LinOTP 2.5.2 to LinOTP 2.6
      • 10.6.1. Updating a deb install
      • 10.6.2. Updating a pip install
      • 10.6.3. Changelog
    • 10.7. Updating from LinOTP 2.5.1 to LinOTP 2.5.2
      • 10.7.1. Updating a deb install
      • 10.7.2. Updating a pip install
      • 10.7.3. Changelog
    • 10.8. Updating from LinOTP 2.5.0 to LinOTP 2.5.1
      • 10.8.1. Updating a deb install
      • 10.8.2. Updating a pip install
      • 10.8.3. Changelog
    • 10.9. Updating from LinOTP 2.4.4 to LinOTP 2.5.0
      • 10.9.1. Updating a deb install
      • 10.9.2. Updating a pip install
      • 10.9.3. Changelog
  • 11. Migrating from LinOTP 1.3 or LinOTP 1.0
  • 12. Security advisories
    • 12.1. Locked Users
    • 12.2. UserIdResolver
  • 13. Troubleshooting
    • 13.1. Connecting to userstores
    • 13.2. Distribution not Found: LinOTP2
    • 13.3. SQLAlchemy error
    • 13.4. Access denied for user root@localhost
• 3. LinOTP User Guide
  • 1. Introduction
  • 2. Workflows
    • 2.1. Using mOTP token
      • 2.1.1. Initializing the mOTP token
      • 2.1.2. Registering the mOTP Token
      • 2.1.3. Authenticating using mOTP Token
    • 2.2. Using eToken Pass
      • 2.2.1. Disable lost token
      • 2.2.2. Change OTP PIN
      • 2.2.3. Resynchronize token
      • 2.2.4. Assign new token
    • 2.3. Enrolling OATH Token or Google Authenticator
• 4. LinOTP Appliance Manual
  • 4.1. Getting started
  • 4.2. Configuring network settings
  • 4.3. Managing LinOTP token administrators
  • 4.4. LinOTP debug logging
  • 4.5. Configuring the RADIUS access to the LinOTP appliance
    • 4.5.1. Detailed settings
      • 4.5.1.1. Realm mapping
      • 4.5.1.2. Windows domain stripping
  • 4.6. Working with configuration sets
  • 4.7. Root user and appadmin user
  • 4.8. Change the server SSL certificate
    • 4.8.1. New self-signed certificate
    • 4.8.2. Create Certificate Request – Externally signed Certificate
  • 4.9. Advanced settings
  • 4.10. Redundant setup
    • 4.10.1. Setup redundancy
    • 4.10.2. Known Errors
    • 4.10.3. Reverting Redundancy
  • 4.11. The support file
  • 4.12. Updates
  • 4.13. Backup and restore
  • 4.14. Network integration
  • 4.15. Emergency recovery
• 5. LinOTP Module Development Guide
  • 5.1. Authentication interfaces
    • 5.1.1. Validate Controller
      • 5.1.1.1. Authentication workflow
    • 5.1.2. OCRA Controller
    • 5.1.3. Example for authentication integration
      • 5.1.3.1. C integration
      • 5.1.3.2. PHP integration
  • 5.2. Administrative Interfaces
    • 5.2.1. Admin Interface
      • 5.2.1.1. Orphanced tokens
    • 5.2.2. Admin Controller
    • 5.2.3. System Controller
    • 5.2.4. License Controller
    • 5.2.5. Session protection
      • 5.2.5.1. Disabling session protection
  • 5.3. Tokens
    • 5.3.1. The GUI file
      • 5.3.1.1. The scope config
      • 5.3.1.2. The scope enroll
      • 5.3.1.3. The scope selfservice
    • 5.3.2. The token file
      • 5.3.2.1. Challenge Response
      • 5.3.2.2. Base TokenClass
  • 5.4. UserIdResolver Modules
  • 5.5. Licenses
    • 5.5.1. AGPLv3

Indices and tables

• Index
• Search Page