KEYCLOAK-242 and Trusted Device Detection

[Thomas Darimont]

Dear Keycloak developers,

For a project, I need to support marking a device/browser as "trusted" to streamline authentication, for example, skip 2FA.

The issue [0] contains a few notes about possible implementations and requirements.

I gave this a spin and built a prototype for this. The .gif [1] shows how this might work.

# What is a "trusted device", and how is it marked and detected?

In this case, a "trusted device" is a user agent, e.g. a browser, or an application, that can store and send cookies. Perhaps the term "Trusted Browser" might be more appropriate here.

A device can be marked as "trusted" by storing a signed "KEYCLOAK_DEVICE" cookie which the device needs to send during authentication. This cookie stores a random deviceId and some metadata as a signed JWT (HS256) created during device registration. To make Keycloak aware of trusted devices for a given user, I also store the deviceId in a new table like "trusted_devices" with information about realm_id, user_id, device_id, device_name, and createdAt timestamp. (I choose a new table since I didn't want to abuse user attributes for this. Another option could have been using the credentials table for this.)

An additional browser-fingerprinting mechanism could be applied to improve the trusted device detection. Still, I didn't consider that option as I'm not sure how robust this would be concerning browser updates.

Other services like DuoSecurity [3] also support trusted devices and implement this in a similar way (signed cookie with metadata). Instead of skipping 2FA entirely on trusted devices, they use a risk-based approach for authentication where they (might) ask less often for a 2FA frequently on trusted devices. Perhaps Keycloak will support a mechanism like that in the future too :)

# How to register a trusted device?

I use a user-initiated RequiredAction in my prototype to register a device as trusted, but this could also happen during 2FA/OTP registration. There could be a checkbox "Trust this device/device", which would avoid prompting for OTP on the OTP registration page. Another option could be to add a "Trusted Devices" section on the Security page of the Account Console to trigger this user-initiated action.

As shown in the [1] .gif, the user can register this browser as trusted or not. With a checkbox, the user can tell whether all other trusted devices (for this user) should be removed (from the Keycloak database).

Submitting this form will send a KEYCLOAK_DEVICE cookie in the response.

The KEYCLOAK_DEVICE cookie is httpOnly, secure, and only sent to the realm issuer URL (could be narrowed to auth-related URLs.). Additionally, the maxAge of the cookie can be configured to, e.g., 120 days.

# How to handle trusted devices in Authentication flows?

I use a new conditional Authenticator (Trusted Device Condition) to checks if the KEYCLOAK_DEVICE cookie is valid and matches a previously registered trusted device for the user. If we detect a trusted device, then the condition matches. The authenticator logic can be inverted, which lets the condition match if the current device is not a trusted device.

The "negated" trusted device condition can then be used in a browser

authentication flow as a conditional sub-flow to the OPT-Forms to skip OTP validation on trusted devices. An example of such an auth-flow is shown in [2].

The code is here [4].

I think something along those lines might be interesting to have in Keycloak core. What do you think?

Cheers,

Thomas

[0] https://issues.redhat.com/browse/KEYCLOAK-242

[1] https://github.com/thomasdarimont/keycloak-extension-playground/blob/master/auth-trust-device/poc-trusted-device-auth-v2.gif

[2] https://github.com/thomasdarimont/keycloak-extension-playground/blob/master/auth-trust-device/poc-trusted-device-browser-auth-flow.png

[3] https://help.duo.com/s/article/1012?language=en_US

[4] https://github.com/thomasdarimont/keycloak-extension-playground/tree/master/auth-trust-device

[Pedro Igor Craveiro e Silva]

I like the functionality and it touches an area that we do very little: device activity and how many things we can do with it, from a security perspective.

Your proposal should allow:

* Track user devices (based on the browser)

* Allow users to manage device activity (not only for active sessions but have a history too)

* Allow introducing different authentication strategies based on device activity (including geo)

* Allow different fingerprints strategies for identifying devices

To name a few.

A long time ago, when working with Stan in the new account console, we ended up with this set of changes https://github.com/keycloak/keycloak/pull/6217.

Looks like both implementations have certain things in common. For instance, storing device info.

That proposal was rejected due to being too complex as we were basically interested in showing devices for active sessions without any other capability built around it, like trusting a device to seamlessly authenticate users as you are proposing.

That said, I like the idea. And perhaps you can look at that PR to check some of the feedback I got at that time.

--
You received this message because you are subscribed to the Google Groups "Keycloak Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to keycloak-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/b658c579-ed06-47e3-96e2-2b9b22662993n%40googlegroups.com.