[keycloak-dev] Step-up Authentication for Keycloak

Thomas Darimont thomas.darimont at googlemail.com
Sat Apr 22 06:34:27 EDT 2017

Hello guys,

(longish email)

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

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

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

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
provider id, e.g. 'auth-otp-form'.

On the client / adapter side there could be a new configuration property
'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
(for OIDC one could also configure an ACR level that is provided by an
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

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

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?


More information about the keycloak-dev mailing list