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

Tue Apr 16 04:51:54 EDT 2019

I’ve made a PR for the design document on keycloak-community. Compared to the initial mail, I’ve made some changes to the multi-factor part to take into account our discussions and some comments from my colleagues. I’ve also added a section for the design of step-up authentication.

From: Stian Thorgersen <sthorger at redhat.com>
Sent: mercredi 20 mars 2019 13:01
To: Doswald Alistair <alistair.doswald at elca.ch>
Cc: keycloak-dev <keycloak-dev at lists.jboss.org>
Subject: Re: [keycloak-dev] W3C Web Authentication - Two-Factor, implementing JIRAs

On Mon, 18 Mar 2019 at 10:51, Doswald Alistair <alistair.doswald at elca.ch<mailto:alistair.doswald at elca.ch>> wrote:
* I can move the design proposal to https://github.com/keycloak/keycloak-community/tree/master/design. For this I simply format in Markdown and do a pull request?

Yes

* I’d also be in favour of a face to face meeting. I’m in the CET timezone (currently GMT+1 and GMT+2 from the 31st of march). This week I’d be available Tuesday, Thursday and Friday, and I also have availabilities next week (except Monday). I’m not sure of the logistics however… We use skype for business internally, but maybe you have a preferred platform? Also, would you mind if one of my colleagues who could work on the JIRAs joins the meeting call?

I've had issues with Skype in the past. We can use BlueJeans if that works for you? Tuesday at 12?

* Since I’m answering anyway, I’ll answer a few of your comments (the rest can be discussed later as I think that they are more technical):

- I believe that you’re correct to say that we should consider the step-up (and one of my colleagues actually had the same comment upon reading my proposal). I may have some ideas on how this would work with the proposed 2 factor, but I’d like to read up on what was already discussed/proposed first. Has there been more discussed than what’s at https://issues.jboss.org/browse/KEYCLOAK-847, http://lists.jboss.org/pipermail/keycloak-user/2016-November/008311.html, http://lists.jboss.org/pipermail/keycloak-dev/2016-May/007150.html and http://lists.jboss.org/pipermail/keycloak-dev/2017-April/009245.html?

Had a long discussion with some folks from the team a while back around step-up, but of course we didn't write it down ;)

In summary the plans where to add markers into the flows that would be used to set the authentication levels, then allow the authentication processor to skip as well as fast forward as needed.

- For the users setting their own default authenticator I agree (and intended to describe that in the text, though upon re-reading that part of the description is fragmented), as long as the admin has enabled the authentication category in a flow. However, it is true that between the default flow and custom/per-client flows it may be difficult to determine how the user sees/selects his preferred authenticator for an authentication step (not to mention what would happen when an admin changes the configuration). This should definitely be further detailed. I’m not sure yet if some extra data structures are necessary though, maybe some custom functions to get the required information is sufficient.

We need a group that means "one of these" ;)

- I think that having a built in flow that follows the proposed logic isn’t too difficult. There’d be the “Authenticated on”,
“Authentication factor 1” and “Authentication factor 2” executions with some default authenticator categories. The admin would be able to set enabled and disabled for the built-in authenticator categories, but be able to add and remove in custom flows. That way a newbie admin wouldn’t be able to do too much damage, while a more experienced one would be able to customize as he wants. Some extra documentation within the admin console may help with this.

From: Stian Thorgersen <sthorger at redhat.com<mailto:sthorger at redhat.com>>
Sent: vendredi 15 mars 2019 09:25
To: Doswald Alistair <alistair.doswald at elca.ch<mailto:alistair.doswald at elca.ch>>
Cc: keycloak-dev <keycloak-dev at lists.jboss.org<mailto:keycloak-dev at lists.jboss.org>>
Subject: Re: [keycloak-dev] W3C Web Authentication - Two-Factor, implementing JIRAs

* Would be worth moving this to a design proposal on https://github.com/keycloak/keycloak-community/tree/master/design. Would be easier to work collectively on a design proposal there than to have an endless thread on a ML ;). I'd also be open to join you on a call to have a discussion "face to face"

* I was thinking to limit to two factor for now, but you're probably right here with regards to consider the bigger picture now as it may be difficult to get it right otherwise

* Need to consider how this fits into step-up authentication

* Admins should be able to select level of authentication required, but users should be able to choose from available options

* Users should be able to select from available mechanisms when configuring. Users should be able to set their own default. This means the account console/rest needs metadata to discover available mechanisms. I wonder if there's a need for something outside of flows and authenticators to capture metadata about supported credential types which is used by account and admin consoles to manage credentials.

* I was aiming a simpler setup where admin doesn't need to create custom flow unless they want to add custom authenticators. That means authenticators should be enabled/disabled in the flow rather than added/removed

Some more comments inline below

On Thu, 14 Mar 2019 at 14:02, Doswald Alistair <alistair.doswald at elca.ch<mailto:alistair.doswald at elca.ch>> wrote:

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.

In the first round we are focusing on two factor. Follow-up later is passwordless flows for web-authn. Passwordless is more tricky as it requires identity first login flow, ability for users to somehow define how they authenticate, rather than just what the second factor is, ability for admins to define authentication optoins rather than just two factor options.

As I mentioned above though it is probably all to linked to consider only one at the design phase. So perhaps we need to work together on a design proposal that will include everything including step-up authentication.

- 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

I like this in general. Devil is in the detail here though and need to think about this some more, especially how it fits into step-up-authentication.

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.

+1 I also think this is limited to the flow itself. Bear in mind I want to have a built-in flow that can be configured rather than requiring creating new flows. For example if we have OTP and WebAuthn authenticators an admin should be able to just enabled WebAuthn, not have to create a new flow to add it. Obviously a new custom flow would be required if the flow or custom authenticators are added. Moving OTP policy from realm to authenticator is already planned work, it was only added to the realm in the first place as it was done before we had configurable authenticators.

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.

When it comes to default that is the users choice. So as a user if I have chosen webauthn as my default that should be shown first to me, even if the realm has the OTP as the first/default. It's also not when the user fails with the selected authenticator, but rather allow the user to choose a different authenticator.

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

Realm config is responsible for most of the mess in the tables today. It's just plain daft to save this as separate tables/columns as it's always fetched as one blog and never queried. So I wonder if we could take a first start at this by simply storing the whole authentication flow including authenticator config as a single JSON blob in the DB.

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.

Credentials needs to have some metadata associated with them. Does it support a user to have mutiple (passwords is a single, webauthn is multiple). Can the admin update the value (passwords admin can update, webauthn only users can and that's through application initiated actions which account console will use). The thinking with regards to adding/updating credentials is that users do it through actions (required or application initiated), while admins do it directly in the console (in which case we need to have a dynamic way to specify the values, something like how component model works).

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

We just need to be very careful here that secrets are never returned on a REST endpoint, but otherwise yes we need an endpoint that can list a users credentials.

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<mailto: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