Description

 
I work for MITRE and one of my projects has the requirement for applications to request particular authentication flows when authenticating users and subsequently make authorization decisions based on the flow completed. To accomplish this, we developed a reference implementation to map Authentication Context Class Reference (ACR) values in OIDC authorization requests to authentication flows. We are interested in pushing this code back up to the community for general use.
 
Keycloak currently provides the ability to use the ACR claim to perform step-up authentication, allowing applications to request stronger authentication in particular situations. However, this is hierarchical and limited to performing additional authentication steps within the same flow. In some cases, an organization may require users to perform entirely different flows based on the resources they are accessing.
 

Implementation

 
The implementation has 3 primary pieces:
 

• New configuration to map ACR values to authentication flows
• Update the authentication flow resolver to check if a particular flow was requested by the client
• Create an ACR to auth flow protocol mapper
   
  Mapping ACR Values to Flows
   
  The configuration of this mapping is straight forward. A new section was added to the Advanced Settings section of the Advanced client configuration tab. Administrators can configure mappings from ACR values to authentication flows.
   
  When a request to the OAuth authorization endpoint is received, Keycloak will check if any of the specified ACR values are configured in this mapping, if one is found, it will set the flow ID in a session note indicating that the flow was requested.
   
  Update the Authentication Flow Resolver
   
  The authentication flow resolver will be updated to check the session note indicating a flow was requested. If it was, it will attempt to load that flow and will return the requested flow to the authentication processor. If a flow was not requested by the client, Keycloak will resolve the flow as it currently does, first checking if the client has a flow override, and then defaulting to the realm flow.
   
  Upon completing a flow, Keycloak will set a user session note specifying the flow that was completed.
   
  ACR Protocol Mapper
   
  A new ACR to auth flow protocol mapper will be needed to populate the ACR claim. This mapper will check the user session note for a completed flow ID. It will then search through the ACR to auth flow map configured for the client and determine the first ACR value that matches this flow ID. It will then set the ACR claim in the token to this value.
   

Interaction with the existing ACR step-up mechanism

 
Keycloak already implements a mapping from ACR values to level of authentication (LoA) to perform step-up authentication. This alternative mapping seamlessly integrates with the existing implementation.
 
If no ACR to auth flow mapping is configured on the client, the existing ACR to LoA mapping will work exactly the same. If an ACR to auth flow mapping is configured, Keycloak will first check if the requested ACR values are configured in the auth flow mapping. If there is a match, Keycloak will set the associated flow ID as requested and will route the user to that flow during authentication (and no requested LoA will be set in the session notes).  If there is not a match, it will fall back to the existing behavior for LoA.