[keycloak-dev] W3C Web Authentication - Two-Factor, implementing JIRAs

Thu Mar 14 09:02:24 EDT 2019

This is OK for me. I propose starting with initial proposals for the fundamentals in this email, and once there's an agreement on those, separating the discussion between the two JIRAs to refine the concepts for each one. Once the work to be done is clearer, it can be supplemented with screen mockups and/or prototypes.

1) Scope of the modifications

- For JIRA KEYCLOAK-9693<https://issues.jboss.org/browse/KEYCLOAK-9693>, I believe that the description in the JIRA is not general enough to cover the description in web-authn-two-factor.md<https://github.com/keycloak/keycloak-community/blob/master/design/web-authn-two-factor.md>. Modifications to the authentication flows should support single factor, as well as 2nd factor and allow both authentication factor levels to select the alternative types of authenticator to be used. This allows a single factor authentication to use for example a FIDO2 dongle for passwordless authentication, or even let the user choose between the dongle and a password during the login.  Modifications for this JIRA include: changes to the authentication logic, changes to the authentication part of the admin console, changes to the authentication screens that the user sees during login, changes to the REST API, and possibly some changes to the database.

- For JIRA KEYCLOAK-9694<https://issues.jboss.org/browse/KEYCLOAK-9694>, changes are to the "users > credentials" part of the administration console and to the REST API.

2) Design proposal for KEYCLOAK-9693<https://issues.jboss.org/browse/KEYCLOAK-9693>

a) Authentication logic

The current authentication flow system should be kept, but perhaps simplified. For a start I think that actual authenticators categories - that is elements that provide identity (e.g. password, cookie, kerberos, otp, fido, ...) - should be separate from other executions like "reset password".

Thus, instead of directly adding "cookie" or "password" as alternatives in the authentication flow, the user can add the execution "authentication factor", and under authentication factor he can add only the valid authenticator categories. Each of the authenticator categories under the authentication factor are considered valid alternatives, and are evaluated in order. The authentication stops being automatically evaluated at the first authenticator that requires user input (alternative: all non-user input authenticators are evaluated before the first user-input authenticator).

Adding a 2nd "authentication factor" execution sets the 2nd factor, and it must then have authenticators assigned. To have an authenticator category be valid for both authentication factors it must be set under both 1st and 2nd authentication factor. For example, kerberos could be set for both 1st and 2nd factor, which would mean that the user skips both factors if he's registered with kerberos, but it could also be just set for the first factor, in which case he'd still have to input the 2nd factor. To handle optional 2nd factors there could either be a "optional authentication factor type" or have an "optional" flag in the options of the "authentication factor".

Potentially, this system could also allow a company that's really security conscientious/paranoiac to set N factors.

Authentication factors are treated as a bloc in the evaluation of alternatives. That is, if in a flow there's "Identity provider redirector", "authentication factor 1", "authentication factor 2", entering the authentication factor 1 flow will automatically cause "authentication factor 2" to be executed after.

To make things perhaps a little more clear, the current default "Browser" authentication would become for example:

Auth type

------------------------------------------------------------

Identity Provider Redirector

Authentication factor (1)

  |- Cookie

  |- Kerberos

  |- Username Password Form

Authentication factor (2) [OPTIONAL]

  |- Cookie

  |- Kerberos

  |- OTP Form

And if we wanted to have an mandatory 2nd factor, with either OTP or a FIDO2 configured:

Auth type

------------------------------------------------------------

Identity Provider Redirector

Authentication factor (1)

  |- Cookie

  |- Kerberos

  |- Username Password Form

Authentication factor (2)

  |- Cookie

  |- Kerberos

  |- OTP Form

  |- FIDO-2

Potentially we could also introduce another type of authentication execution, we could call it "Authenticated on", to simplify the authenticators that bypass the authentication factors. We could then have:

Auth type

------------------------------------------------------------

Identity Provider Redirector

Authenticated on

  |- Cookie

  |- Kerberos

Authentication factor (1)

  |- Username Password Form

Authentication factor (2)

  |- OTP Form

  |- FIDO-2

b) Authentication section in the admin console

The schema described in a) would be implemented in the Authentication > flows. Bindings and Required Actions don't need any change I think. For policies I believe the password policy for the realm should remain, but the OTP policy should disappear, as a user could have several alternative OTP devices with different settings. As such, the information about the OTP settings should probably move to information associated with the credential.

c) Authentication screens for the user

When the user logs in, unless he has something like a cookie he will see by default the first configuration interface configured in the current Authentication factor. If there are many different factors configured, he can access a list of any valid authenticator to use. If the user fails with the selected authenticator, he may choose another configured authenticator to validate the step.

d) REST API

There's no major change here, aside from updating the scheme to support the separation between authenticator categories and executions, and adding instructions to edit which authenticator categories are assigned to an authentication factor.

e) database modifications

Authenticator categories could be separated from executions either by having a new dedicated table, or by introducing a field in the authentication_execution table

3) Design proposal for KEYCLOAK-9694<https://issues.jboss.org/browse/KEYCLOAK-9694>

a) Changes to the users > Credential menu

Instead of manage Password we have "manage credentials", with a list of credentials for a user. The credentials grouped by type, and should indicate by which authentication factor they are valid for (1st factor, 2nd factor, unconfigured). The administrator should be able to edit / remove a credential.

- For editing the administrator should be able to visualise the data of the credential (except the secret and the salt) and edit metadata about a device. Data would be any data in the fields of the credential that describe immutable data about the credential, and metadata would be for example label that a user can see and edit to name his device and a label that only the administrator could see and edit. The administrator (and user) should be able to set a "preferred credential" for each authentication factor level, which will override the factor shown by default during the login.

- For deleting, I think that this should be linked to the authentication factors and authenticator categories of the realm, for example:

   + For a realm with a single factor configured of types password and FIDO2, the credentials can be removed until ONE remains, and that last one cannot be removed.

   + For a realm with a two factors configured, the first with password and FIDO2, and the second with OTP and FIDO UAF (I know, this is not a very good example from a security point of view), then it must be impossible to remove the last credential for the first factor, and to remove the last credential for the second factor.

A note for passwords: Unlike other credentials I don't think that there should be more than one password that can be configured. Also, among its edition option it should be possible to reset (temporarily or not) as is currently the case.

If the administrator and user can remove credentials, I do not know if the possibility to disable credentials is still useful. I don't see any problems with the feature either though, so if it’s still deemed useful it would keep its current behaviour.

b) Modifications to the REST API

Currently there's no way to get credentials with the REST API. This should change with these modifications to reflect the new options for the administrator. The API should function in the same manner as the admin console: Credentials can be exposed (except for secret and hash values), the metadata edited and the credentials deleted with the same restrictions as described in section 3a

c) Database modifications

I do not believe that this modification entails any database modifications. The current system with credential and credential attributes should be sufficient for the handling of multiple authenticators.

That's it. Comments, questions and criticism are all welcome.

________________________________
From: Stian Thorgersen <sthorger at redhat.com>
Sent: 08 March 2019 13:17
To: Doswald Alistair
Cc: keycloak-dev
Subject: Re: [keycloak-dev] W3C Web Authentication - Two-Factor, implementing JIRAs

No one is working on the admin part at the moment, so contributions here would be very welcome. It's not a straightforward task though and would need a fair bit of design/prototyping/discussions to get this right.

On Fri, 8 Mar 2019 at 11:14, Doswald Alistair <alistair.doswald at elca.ch<mailto:alistair.doswald at elca.ch>> wrote:
Hello,

I've been following the thread about the implementation of WebAuthn in Keycloak, and saw that there are some related JIRAs in the following design document https://github.com/keycloak/keycloak-community/blob/master/design/web-authn-two-factor.md.

Is anyone  already working on JIRAs https://issues.jboss.org/browse/KEYCLOAK-9693 and https://issues.jboss.org/browse/KEYCLOAK-9694 for managing multiple 2nd factor authenticators? If not, with my colleagues we could implement them relatively quickly as we have use cases for these functionalities.

Best regards,

Alistair Doswald
_______________________________________________
keycloak-dev mailing list
keycloak-dev at lists.jboss.org<mailto:keycloak-dev at lists.jboss.org>
https://lists.jboss.org/mailman/listinfo/keycloak-dev