[keycloak-dev] Step-up Authentication for Keycloak

[Thomas Darimont]

Hello guys,

(longish email)

I have an idea how step up authentication could work with Keycloak that I'd
like to share.

Summary:
Clients require certain authentication steps by using scopes linked to
authenticators.
An authenticator would only be executed if it's scope is present.
An application can detect the current authentication level by inspecting
the
OIDC token or SAML assertions and request additional authentication if
necessary.

All that with (IMHO) a few little additions to Keycloak.

Idea:
The main idea is to have a new option 'Scope Param Required' for
authenticators as
there is for Roles. If 'Scope Param Required' is "On" then the
authenticator is
only executed if the scope parameter in the login URL contains the
authenticator
provider id, e.g. 'auth-otp-form'.

On the client / adapter side there could be a new configuration property
like
'additional-scopes' to specify a required authentication scope.
Optionally there could be an additional property 'required-claims:
auth-otp-form=true' to
indicate that a user can only access the app if the given claim is present.

Authenticators could also by default emit a 'User session note' with the
provider id to
indicate that they were executed, e.g. "auth-otp-form: true".
This could then be mapped via a protocol mapper into a OIDC token / SAML
response.
(for OIDC one could also configure an ACR level that is provided by an
authenticator,
but this wouldn't help for SAML)

With this clients could detect the executed authenticators based on the
claims in the
OIDC token (or ACR value) or SAML assertions and trigger reauthentication
if necessary, e.g. by sending a
redirect to the '/auth' URL with parameters 'prompt=login' and
'scope=openid+auth-otp-form'.

Example Scenario (OIDC):
In realm 'acme' we have two clients 'A' and 'B'.
To access 'A' username/password authentication is enough, but for 'B' one
needs to provide an
additional factor, e.g. an OTP token or code via SMS.

The auth-otp-form authenticator is configured with 'Scope Param Required=On'
B's adapter config contains 'additional-scopes: auth-otp-form'

First the user accesses 'A' and authenticates with username-password. Then
the user tries
to access 'B'. 'B' detects that the current OIDC (access/ID) token doesn't
contain the
required claim 'auth-otp-form'. Thus it sends a redirect as mentioned
above, e.g.:
http://localhost:8081/auth/realms/acme/protocol/openid-connect/auth?client_id=B&redirect_uri=http%3A%2F%2Flocalhost%3A8081%2Fauth%2Frealms%2Facme%2FB%2Flogin-redirect&state=0%2F1fa9fb6b-8ac9-4f4d-ac98-beb0c3548271&response_type=code&scope=openid+auth-otp-form&prompt=login

Keycloak would now detect that it needs to execute the OTPForm authentiator
based on the scope
parameter auth-otp-form which will prompt the user for OTP input.

Note that the user still would need to provide his username/password. If
one would be able to skip
that (since the user is already authenticated via username/password) one
could think of an additional
parameter like 'auth_mode=step_up' to signal Keycloak that it should only
verify credentials that have not yet checked.

In this case it would skip the username / password authenticator and jump
to the OTP form.

What do you think?

Cheers,
Thomas