Currently Keycloak "main" has basic support for step-up authentication and also opened PR #10088 for bugfixing. This discussion about other possible enhancements and ideas for improve/update current functionality.

Keycloak.js support

It can be nice to consider adding some support for claims or acr_values to the keycloak.js adapter for make it easier for users to request authentication levels from their JS applications. Question is how to make API to be easy to use and extensible for the future. I see 3 options - from "easiest" to most flexible.

Option 1

The easiest to support requesting with acr option sent to login method. This will consider them always as essential claim. Hence no built-in support for request non-essential (voluntary) claim:

Example:

var loginOptions = {
    acr: "1 2"
}
keycloak.login(loginOptions);

Adapter will translate this into claims parameter with essential=true sent in the OIDC request.

Option 2

Possibility to specify if "essential" or not. The acr option itself would be object instead of String:

var options = {
    acr: { 
        values:"1 2",
        essential: false
    }
}
keycloak.login(loginOptions);

Option 3

Introduce something like claimsBuilder to the keycloak.js. This can help in the future if we want to have more proper support for claims parameter by Keycloak server (Currently claims parameter is used only for acr claim):

var claimsParam = keycloak.claimsBuilder()
            .acr("1 2", true)
            .build();
var loginOptions = { claims: claimsParam };
keycloak.login(loginOptions);

Currently I used the option 3 for my prototype as it would allow easiest extensibility in case we want to have more proper support for claims parameter in the future. That is my preference.

Support in other Keycloak OIDC adapters

It is not considered due the fact they will be likely deprecated soon.

SAML support

SAML specification has some possibility to request ACR levels by <RequestedAuthnContext> parameter in the SAML authentication request. More described in the design https://github.com/keycloak/keycloak-community/blob/main/design/multi-factor-admin-and-step-up.md#saml .

Should we add support for SAML or not? If yes, should we also target SAML adapters? Is it sufficient to at least specify "Default level" for SAML client (see below) and not consider <RequestedAuthnContext> parameter support?

Protocol mapper and client scope for "acr" claim

Currently adding acr claim to the token is hardcoded. It will be better to add dedicated protocol mapper implementation for adding acr claim to the token. And add dedicated client scope for that. This will be default client scope in the realm added to all new clients. Similar to current roles and web origins client scopes.

Backwards compatibility

Before adding step-up authentication, Keycloak had very limited support for acr claim (Hardcoded to return value 0 in case of SSO re-authentication and value 1 for normal (non SSO) authentication. In theory, some client adapters (not Keycloak, but some 3rd party) rely on the current ACR claim from tokens to be present. But not really sure about that.

Options for backwards compatibility are:

• Possibility is to stick to same behaviour we had before adding step-up authentication (Hardcoded acr claim to 1 in case of proper authentication and 0 in case of SSO authentication) . Protocol mapper will just override this (if used). This is my preferred option. We can improve once we have "Client Types" support.

• Don't handle it for existing realms and clients and only document it. Which means the acr claim won't be returned for them by default. This is probably OK, but someone can have issues in case that he relies on acr claim for some reason and has millions of clients.

• Update existing realms and clients during migration. Will be expensive to do and hence I consider it as no go.

Support for OIDC well-known endpoint

OIDC Discovery specification introduced acr_values_supported for OIDC server to return supported acr values. Keycloak currently does not return anything in it.

We can remove configuration option ACR to LoA mapping from client level and instead add it to the realm level or "client policy executor" level. Have this mapping at client policy or realm level is probably sufficient granularity. As I am not sure if various clients in the realm ever need different values for acr claim.

Compromise might be to introduce "Client Policy Executor" and add mapping ACR to LoA to this executor. This will allow it to be reused by multiple clients.

Then acr_values_supported in Well-Known endpoint can directly return values specified by this mapping.

In case that Acr to Loa mapping is not filled for the realm, the Well-Known endpoint can just browse through the authentication flow bind to the realm browser and figure if there are any LoA conditions and return the number values specified by these conditions. This can be cached to not require parsing authentication flows during each call of well-known endpoint.

In case of client policy executor granularity (my preference), the well-known endpoint can browse through executors and return all values supported by any executor.

Option for client to specify default level

Currently there is no option at client level to request "default level" for the particular client.

For the client, we can likely remove Acr to LoA mapping option (see above) and add option for Default ACR values to specify the values requested by target client. There is OIDC dynamic client registration parameter default_acr_values for that, which we can easily add to support then. See OIDC Client registration specification for more details.

Note that specification considers this as voluntary claim (not essential) and hence Keycloak server is not strictly forced to return any of the specified values. When client is created, we can validate if default_acr_values corresponds to some of acr_values_supported for the realm.

What ACR to send from SSO authentication?

Currently Keycloak returns ID Token with ACR of level 0 in case that authentication was done with SSO. Example:

• Client sends authentication request with acr_values=1. User authenticates with username/password. ID token is returned to client with acr: 1
• Client sends another request with acr_values=1. User is not required to actively authenticate in Keycloak due the SSO. ID token is returned to client with acr: 0

I think that it is more appropriate to return the last ACR achieved even from SSO authentication.

Note that OIDC specification has this snippet:

The value "0" indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 [ISO29115] level 1. 
Authentication using a long-lived browser cookie, for instance, is one example where the use of "level 0" is appropriate.

But question is what is really "Authentication using a long-lived browser cookie"? My understanding is that this is the case when user did not had SSO and in spite of that, the "active authentication" of the user was done with long-lived cookie. However in case of SSO authentication, the user was before authenticated actively with the password and now the SSO is just "SSO re-authentication". So not sure if "SSO re-authentication" is what specification really meant?

I see possibilities like:

• Always return last saved level from user session in case of SSO re-authentication
• Introduce switch to ACR protocol mapper. This will allow to specify whether SSO re-authentication should return 0 or the last saved level from user session. When the latter would be default value.

Option for users to skip authenticator

Consider that client sends something like acr_values=2 1. It means client prefers level 2, but level 1 is also OK. In this case, after authentication with password (level 1), Keycloak can display authenticator for 2nd level as well (WebAuthn, OTP, Recovery code). But user will see link like "Skip this authenticator" . It can be similar link to "Try another way" . Keycloak will return to client with ID token with acr=1 or acr=2 based on if user skipped 2nd factor or not.

Client can do it's own checks and allow some functionality based on the achieved level. For example photoalbum client can allow read photos for level 1, but adding/deleting photos only to level 2.

Client policy

As specified above, we can use client policy for more fine-grained granularity like:

• Default "essential" levels
• Default "non-essential" levels
• ACR to LoA mapping (Currently specified at client level, but we can possibly remove from the client)
• What is the level to be used during each authentication and what level can be "re-used" from SSO? This will allow us to remove option "Store LoA in user session" from the authenticator condition. Level can be always stored in the user session after successful authentication. Client policy executor will just specify if level can be re-used or not.