4. System config — LinOTP 2.7 documentation

Introduction to LinOTP 2.7 System Configuration

Ever wondered why your mfa settings feel like a mess? It's usually because the global config is off. Before you start enrolling devices, you gotta nail down the foundation.

• System Defaults: Sets the baseline for failcounts and sync windows across all tokens.
• NTP is Mandatory: You gotta keep your server time synced via ntp. If the server clock drifts even a little, your time-based tokens (TOTP) will stop working and users will get locked out for no reason.
• Web vs Native: You get the same control whether using the web api or the old-school native client.
• Security Consistency: Global rules stop weak spots in retail or healthcare setups.

According to the LinOTP 2.7 documentation, these settings define the overall behavior before you even touch a specific user.

Next, let's look at how the system actually handles login attempts.

Core Authentication Logic and FailCounter Management

Ever had a user get locked out because they mashed the keyboard too many times? It's a headache for everyone, but LinOTP's failcounter logic is what keeps your security tight without making the helpdesk explode.

• Max FailCount: This is your "three strikes" rule. Once a token hits this limit, it's dead in the water until an admin resets it. In high-stakes finance setups, you might keep this low, while a retail shop might be more forgiving.
• Success Reset: If this is on, one good login wipes the slate clean. It’s great for users who just had a clumsy morning, but keep an eye on it if you're worried about slow-motion brute force.
• False PIN Penalty: If someone guesses the wrong PIN, linotp can increase the failcount for all tokens assigned to that user. This is a massive win for thwarting attackers trying to guess their way into a healthcare portal or private api.
• Pass on no token: This is a setting you'll find in the policy section. If you turn this on, anyone without a token assigned just bypasses mfa entirely. As you can guess, "Pass on no token" is a huge security hole because an attacker just needs a password for any unprovisioned account.

You also gotta decide where the PIN goes. Most people Prepend it (PIN + 123456), but you can append it if your legacy apps requires that. The Default OTP Length is super important here—if you set it to 6 but the token sends 8, the system won't know where the PIN ends and the code starts.

According to the LinOTP 2.7 Documentation, using the X-Forwarded-For header is also huge for identifying the real client ip when you're behind a load balancer, which keeps your audit logs actually useful.

Next, we'll dive into why token sync windows matter more than you think.

Advanced Token Synchronization and TOTP Parameters

Ever struggled with a user whose token just refuses to work because they haven't used it in months? It's usually a sync issue.

For time-based tokens, everything depends on the clock. As mentioned earlier, keep your server time synced via ntp or things get messy fast. If your linotp server and the user's phone aren't on the same page, login fails.

• TOTP timestep: Stick to 30 or 60 seconds. Most apps like Google Authenticator use 30 by default.
• TOTP timewindow: This is your "buffer." Setting it to 60 or 120 allows a few minutes of drift so users don't get locked out by a slightly slow phone clock.

If a token gets too far out of alignment, linotp can fix it automatically via the "Auto-resync" workflow.

The system waits for two consecutive codes to prove the user actually has the device. When a user is out of sync, they just enter their current otp, wait for the next one, and enter that too. In the admin UI, you'll see the token counter or clock offset jump to match the new values. It's a lifesaver for hardware tokens sitting in a drawer for a year.

Next, we'll check out how this integrates with your web apps and user directories.

SAML Integration and SSO Testing Tools

Ever tried to get your saml attributes to play nice with an identity provider? It’s a total pain when the surname or email just won't show up on the other side.

If you’re using simpleSAMLphp, you gotta tell linotp to actually send the data. (LinOTP integration for SimpleSAMLphp | by Greg Harvey - Medium) By default, it might just say "yep, user is good," but that doesn't help your app know who the person actually is.

• Enable samlcheck: You have to check the "Return SAML Attributes" box in the system config. This opens up the /validate/samlcheck api for business.
• Attribute Exchange: Once it's on, linotp sends back the username, given name, surname, and mobile phone. This is huge for retail apps that need a phone number for step-up auth.

Manual validation is basically asking for a lockout. Use third-party browser extensions or standalone apps like "SSOTools" (which are generic saml tracers and debuggers) to check your saml and oauth flows before you go live. These tools let you see the actual xml response so you can catch messy metadata or expired certificates that linotp needs to trust the connection.

Now that the connection is set up, we need to make sure the users are actually being found in the right place.

User Handling and Realm Management

Ever had a user complain they can't log in because they typed [email protected] but your system only knows bob? That's a classic realm mismatch.

• splitAtSign logic: If you turn this on, linotp chops the username at the "@". It's a lifesaver for multi-tenant setups where user1@site-a and user1@site-b need separate tokens.
• Migration safety: Use "Pass on user not found" only when moving users from old systems. It lets them in without mfa if they aren't in the database yet—super risky but handy for 48-hour rollouts.
• Token audits: As mentioned earlier, "Pass on no token" is a huge security hole. It basically ignores mfa for anyone who hasn't been assigned a device yet.

Watch out if your ldap actually uses @ in the directory names, because linotp might get confused and split it in the wrong spot.

Next, we’re gonna look at the actual token types you can plug into this mess.

Conclusion and Security Recommendations

Setting up linotp 2.7 doesn't have to be a nightmare if you get the basics right from the start. If you leave the defaults alone, you're gonna have a bad time when users start complaining about sync issues or when an auditor sees your bypass settings.

Here is a quick checklist to keep things tight:

• Check your NTP: Seriously, if your server clock is off, your totp tokens are useless.
• Tighten FailCounts: Don't let people guess forever. Set a reasonable limit and use the False PIN penalty.
• Audit your Policies: Make sure "Pass on no token" is turned off once you're done with your initial rollout.
• Verify SAML: Use those sso debuggers to make sure your attributes like email and phone are actually passing through.
• Realm Splitting: Use splitAtSign if you're dealing with multiple domains so the ldap lookups don't fail.

Keep your mfa secure and your users won't hate you (hopefully).