2FA - Inero Software - Software Consulting

Trusted devices in Keycloak

Marta Kuprasz — Thu, 06 Mar 2025 10:47:08 +0000

User authentication in IT systems requires finding a balance between convenience and security. On one hand, users expect the login process to involve the fewest steps possible; on the other, it is essential to protect system access from unauthorized use. One way to manage security levels flexibly is through the trusted devices mechanism, which allows users to reduce the number of required login steps for recognized and secure devices.

The stricter the security policy, the more inconvenient it becomes for users—this is the eternal dilemma for system administrators. Long and complex passwords, frequent password changes, and additional authentication factors enhance security but also lead users to find ways to bypass procedures—such as writing passwords down in notebooks or saving them in browsers.

Trusted Devices – How Does It Work?

By default, Keycloak does not recognize or remember devices, meaning each session is treated independently. However, with extensions, support for trusted devices can be added, allowing users to skip certain steps during subsequent logins.

CTO of Inero Software, Waldemar Korłub, emphasizes:

"Hence the concept of trusted devices – the first time, we need to go through all the steps, but afterward, the application can, for example, skip asking for the two-factor authentication code."

Once a device is marked as “trusted,” the system can retain its status for a specified period, allowing for a simplified login process. However, the user may still be periodically asked to reauthenticate to ensure security.

Is remembering devices secure?

While the trusted devices mechanism improves user convenience, it also introduces additional risks. The biggest threat is the theft or loss of a device that has been previously marked as trusted.

As Waldemar Korłub points out:

"If the system does not require an additional authentication factor, an attacker could gain access to all stored applications. That’s why it is crucial for users to have control over their trusted devices—ideally through a panel where they can remove them at any time."

Introducing a device management panel and the option to revoke a device’s trusted status in case of loss are essential elements for ensuring security.

How can administrators control access in Keycloak?

Administrators can restrict the device remembering mechanism, for example, to specific networks or corporate devices.

Waldemar Korłub explains:

"We can limit this mechanism, for example, to computers within the local network—if users connect via the corporate VPN, we can recognize company-owned devices and enable the trusted devices option for them."

Thanks to such solutions, organizations can prevent users from assigning trusted status to personal devices that are beyond their control.

Trusted Devices in Keycloak – Key Takeaways

- Trusted Devices Help Simplify Login but Require Proper Security Measures
  The trusted devices mechanism in Keycloak allows users to skip certain authentication steps, such as entering a 2FA code. While this is a convenient solution that streamlines daily operations, it also requires the implementation of appropriate security measures. It is essential to define the validity period of a trusted device and monitor changes in login behavior to prevent misuse.

- Administrators Can Control the Trusted Device Access Policy
  Not every device should be marked as trusted, which is why administrators can restrict this feature to corporate computers or require a VPN connection. This helps prevent situations where a user assigns trusted status to a personal computer that the organization cannot control.

- Device Management Panel Enhances Security
  To give users greater control over their sessions, it is beneficial to implement a panel that allows them to review and remove trusted devices. This way, in case of device loss or suspected unauthorized access, users can quickly revoke granted permissions.

- The Ability to Remove a Device Protects Against Account Takeover
  If a device is lost or stolen and the system does not require additional authentication, an attacker could gain access to the user’s account. That’s why it is crucial to allow the removal of trusted devices at any time and enforce reauthentication. This approach provides greater flexibility while reducing the risk of unauthorized account access.

When Should You Use the Trusted Devices Feature in Keycloak?

The trusted devices feature in Keycloak enhances login convenience while maintaining a high level of security. This functionality is particularly useful in corporate environments and BYOD (Bring Your Own Device) models, where users regularly log in from the same devices.

Marking a device as trusted reduces the number of two-factor authentication (2FA) prompts, extends session duration, and allows for dynamic security policy adjustments, such as requiring reauthentication for suspicious logins. This approach helps mitigate the risk of account takeover—even if an attacker obtains a password and 2FA code—since logging in from a new device may trigger additional verification.

Implementing trusted devices in Keycloak enables organizations to strike a balance between security and user convenience.

The trusted devices mechanism in Keycloak enhances login convenience without significantly compromising cybersecurity. Proper implementation of the device remembering policy in Keycloak helps balance system security and user experience.

However, administrators should ensure that mechanisms are in place for managing the list of trusted devices and enforcing periodic verification of their status to mitigate potential security risks.

We will help you implement Keycloak

Want to implement Keycloak or add new functionalities? Schedule a meeting to explore the possibilities.

Schedule a meeting

Artykuł Trusted devices in Keycloak pochodzi z serwisu Inero Software - Software Consulting.

Behind the Scenes #2: Implementing email-based MFA in Keycloak

Marceli Formela — Thu, 13 Feb 2025 09:50:32 +0000

Keycloak natively supports many secure login solutions and comes with built-in one-time password (OTP) mechanisms, such as authentication via mobile apps like Google Authenticator or our solution AuthM8. However, if we want to use other advanced authentication methods and for example send OTP codes via email, then similar to SMS multi factor authentication (more details HERE), we need to implement this functionality ourselves. In this post, we’ll explore a custom MFA implementation that sends a one-time authentication code to the user’s email.

How does email-based MFA work?

The authentication process consists of two main stages:

- Generating and sending the MFA code

If the user already has an active cookie confirming a previous MFA verification, they should be immediately authenticated. Otherwise, Keycloak creates a new credential for the user and generates a one-time code based on configurable parameters like length or time-to-live. The code is stored in the user’s credentials and then is emailed using the email provider.

- Verifying the entered code

When a user submits the code, KC retrieves the stored credential and compares the entered value. If the code is correct and still valid (not expired), authentication is successful, and a cookie is set to remember the verification. If the code is incorrect, the user is prompted to re-enter it and if the code has expired, an error message is shown and the process must be restarted.

Email MFA: Pros and Cons

Email-based MFA offers additional security when the primary factor, such as a password, has been compromised. This is particularly helpful in cases where passwords are brute-forced or easily guessed, such as with common combinations like 123456. Similarly, this solution offers protection against credential stuffing, where attackers use leaked passwords from other breaches to attempt logging into account.

There are several other benefits to using email as a MFA:

- Email MFA does not require users to provide additional sensitive information, such as a phone number, reducing concerns about privacy.

- It does not require users to install a separate app or complete a complicated setup, which simplifies the process.

- Users are accustomed to providing their email for various purposes, such as receiving important account updates or resetting passwords. This familiarity makes it more accessible.

However, email as a delivery channel does have some drawbacks. If an attacker compromises your email (gains access to an email account through stolen credentials or by exploiting an active session.), they could potentially reset other accounts’ passwords as well. For users in vulnerable situations, such as those with access to shared devices, email-based MFA can still leave them exposed. As with any security measure, it’s essential to weigh the benefits against the potential risks and mix email MFA with other safeguards, such as strong passwords policy and secure email practices.

Implementing Email MFA

In this modified Browser Authentication Flow, we integrate our custom MFA as an additional authentication method. There are two new steps:

- MFA Email setup – this step ensures that email is set up and verified for the user before proceeding. If the user does not have a custom MFA Credential (which stores OTP codes as secrets), it will be set as well.

public class MfaEmailSetupAuthenticator implements Authenticator, CredentialValidator {
@Override
public void authenticate(AuthenticationFlowContext context) {
[…]
// Require email verification
if (!userModel.isEmailVerified()) {
userModel.addRequiredAction(UserModel.RequiredAction.VERIFY_EMAIL);
}
// Add MFA email credential if not present
if (!getCredentialProvider(context.getSession()).isConfiguredFor(realmModel, userModel, MfaEmailCredentialModel.TYPE)) {
userModel.credentialManager().createStoredCredential(new MfaEmailCredentialModel(new MfaEmailCredentialData()));
}
[…]

- MFA Email Authentication – this is the actual authentication step where a one-time code is sent via email. Marked as Alternative, meaning it can be used instead of other MFA methods like mobile app OTP.

Here, you can see how the configuration of this authenticator could look like in the Keycloak authentication flow.

- Max Cookie Age this setting determines how long the MFA session (cookie) is valid. If the cookie is still valid, the user won’t be prompted for MFA.
- Time-to-live indicates the lifetime of the MFA code.

Now let’s take a look at the code.

The method below handles the MFA process itself. If a valid cookie exists (indicating that the user has already completed MFA), the method immediately returns success, meaning the authentication flow is complete without requiring additional actions.

@Override
public void authenticate(AuthenticationFlowContext context) {
if (hasValidCookie(context)) {
context.success();
return;
}
[…]

If there is no cookie, we should try to retrieve the user’s existing MFA credential from the credential provider. If the user doesn’t have one, a new instance is created using the MfaEmailCredentialModel which just extends the built-in CredentialModel:

[…]
// get existing credential or create a new one
CredentialModel credentialModel = getCredentialProvider(session)
.getDefaultCredential(session, context.getRealm(), user);
if (credentialModel == null) {
credentialModel = user.credentialManager().createStoredCredential(new MfaEmailCredentialModel(new MfaEmailCredentialData()));
}
[…]

Then the authenticate method reads configuration properties like code length and TTL (time-to-live). The code itself can be generated using some utils method and will be stored as the secretData in the credential model.

// generate and store code
int length = Integer.parseInt(configMap.get(CONFIG_CODE_LENGTH));
int ttl = Integer.parseInt(configMap.get(CONFIG_CODE_TTL));
String code = MfaEmailCodesUtils.generateCode(length);
credentialModel.setSecretData(code);
user.credentialManager().updateStoredCredential(credentialModel);
AuthenticationSessionModel authSession = context.getAuthenticationSession();
authSession.setAuthNote("ttl", Long.toString(System.currentTimeMillis() + (ttl * 1000L)));

In the end the sendCode method is called to send the generated code to the user’s email. If the email is sent successfully, the method presents the form where the user can enter the MFA code.

// send email and show input form
try {
MfaEmailCodesUtils.sendCode(session, user, ttl, code, configMap);
context.challenge(context.form().setAttribute("realm", context.getRealm()).createForm(TPL_CODE));
} catch (Exception e) {
context.failureChallenge(AuthenticationFlowError.INTERNAL_ERROR,
context.form().setError("mfaEmailNotSent", e.getMessage())  .createErrorPage(Response.Status.INTERNAL_SERVER_ERROR));
}

The second major part of our Authenticator is the action method which handles the validation of the code entered by the user. It is invoked when the user submits the input form after receiving the email.

The method retrieves the user’s credential from the provider and then the code is validated by checking it against the stored credential using the custom isValid method.

[…]
final MfaEmailCredentialModel credentialModel = getCredentialProvider(session)
        .getDefaultCredential(session, context.getRealm(), user);
boolean isValid = getCredentialProvider(session).isValid(context.getRealm(), user,
     new UserCredentialModel(credentialModel.getId(), getCredentialProvider(context.getSession()).getType(), enteredCode));
[…]

If the code is valid, the next step is to check if it is expired. We can also set a cookie that stores the MFA session to prevent the user from being prompted for MFA again during the cookie’s validity period.

[…]
// valid
HttpResponse response = context.getSession().getContext().getHttpResponse();
response.setCookieIfAbsent(createCookie(context));
context.success();
[…]

Of course, in this post, we will not cover the entire topic, omitting implementation details such as sending the code, generating the code, validation, and creating our custom cookie.

However, we have walked through the major steps of implementing 2FA using email-based codes. On the one hand, this approach offers a simple and accessible solution. Although it has its drawbacks, using it in solutions like Keycloak helps mitigate many of these vulnerabilities. Keycloak also provides the flexibility to combine email-based MFA with other security measures, creating a more layered and resilient authentication process that can help protect against evolving cybersecurity threats.

Do you need help configuring multi-factor authentication?

Schedule a meeting to find out how we can help you.

Schedule a meeting

Artykuł Behind the Scenes #2: Implementing email-based MFA in Keycloak pochodzi z serwisu Inero Software - Software Consulting.