Back-Channel Authentication Plugin#

Plugin Descriptor interface:

BackchannelAuthenticatorPluginDescriptor

Back-channel authenticator plugins provide back-channel authenticators via implementations of the BackchannelAuthenticationHandler interface.

Back-channel authenticators need to be linked to a front-channel (regular) authenticator, so it is typical for the same plugin JAR to provide both a front-channel authenticator and a back-channel authenticator. This link is established via the getFrontchannelPluginDescriptorReference() function present in the back-channel plugin descriptor.

Handler Interface#

The BackchannelAuthenticationHandler interface requires three methods:

  • startAuthentication(authReqId, authRequest) — Called when the client submits a CIBA request. The plugin should initiate the out-of-band authentication (e.g. push notification, SMS) and return BackchannelStartAuthenticationResult.ok() on success, or .error(...) if the request cannot be fulfilled (e.g. unknown user).
  • checkAuthenticationStatus(authReqId) — Called repeatedly by the server until the authentication concludes. Return an Optional containing a BackchannelAuthenticationResult with AuthenticationAttributes when authentication is complete, or empty to signal that the request is not yet known.
  • cancelAuthenticationRequest(authReqId) — Called when the server cancels or expires the request. The plugin should release any associated resources.

Identifying the End-User with BackchannelHint#

BackchannelHint is available since version 11.1.0 and is marked @Experimental. Its API may evolve in future releases.

The CIBA specification allows a client to identify the end-user via one of three mutually exclusive hint parameters. BackchannelAuthenticationRequest.getHint() returns a BackchannelHint, a sealed interface whose concrete type directly encodes which hint was provided:

TypeParameterMeaning
BackchannelHint.LoginHintlogin_hintRaw string identifying the user. Call .subject() to get it.
BackchannelHint.IdTokenHintid_token_hintSubject extracted from a validated ID token. Call .subject() to get it.
BackchannelHint.LoginHintTokenlogin_hint_tokenOpaque token passed through without validation. Call .token() to get the raw value. No subject is pre-extracted.

BackchannelAuthenticationRequest.getSubject() is still available for retro-compatibility reasons and returns the subject for LoginHint and IdTokenHint, or an empty string for LoginHintToken. Prefer the use of BackchannelAuthenticationRequest.getHint().

Was this helpful?