FIDO2 Mediation

When you are deploying FIDO2/WebAuthn it might be necessary to implement specific business controls during authentication and registration ceremonies. FIDO2 Mediators can be used to add this extra validation, as well as insert additional data into the server responses.

Mediators take the form of a JavaScript mapping rule which runs in four places

  1. As part of the initiation of a registration attempt (a call to the attestation options endpoint).
  2. As part of an completion of a registration attempt, after all FIDO2 and WebAuthn checks have passed, but before the registration is considered validated (a call to attestation result).
  3. As part of the initiation of an authentication attempt (a call to the assertion options endpoint).
  4. As part of the completion of an authentication attempt (a call to the assertion result endpoint).

Mediation also occurs as part of an authentication service flow by using FIDO2/WebAuthn as an authentication mechanism.

The capabilities of mediation are as follows:

  1. During any mediation, FIDO2 processing can be halted with a custom message and status. To do this, populate the error field:
    error.put("status", "authenticator_denied");
error.put("message", "An administrator has disabled your authenticator type from being used");
  2. During mediation of an attestation result request, additional variables can be saved in the “attributes” parameter of the new registration. Add to the “attributes” parameter with:
    attributes.put("example_attribute", "example_value");
    Note: Only attributes of type String can be stored.

    These attributes can be accessed later in authentication mediation flows as the registration data, including these attributes, is made available as part of the mediator's context variables.

  3. During mediation of an attestation result or assertion result call, additional values can be returned to the client:
    responseData.put("did_user_verify", context.requestData.registration.userVerified);

    The response is returned to the client to let it act based on the authenticator and its registration. For example, this could be used to return the model name of the authenticator.

  4. During mediation of an attestation result or assertion result call, additional identity data can be returned which can be added to the users session:
    credentialData.put("authenticator_friendly_name", context.requestData.registration.friendlyName);

    Credential data returned indicates the users identity. Credential data is returned to the relying party in an API call to /attestation/result or /assertion/result, or when the authentication service is used to perform the assertion result, credentialData attributes are added to the user's ISAM credential. Only single-valued String attribute values should be used.

The mediator context

The context variable available in mediation contains several essential pieces of information about the request.

  1. context.requestType- Identifies which one of the following mediation is occurring:
    • attestation_options
    • attestation_result
    • assertion_options
    • assertion_result
  2. If enabled, HTTP request context (such as headers) are made available under:
    • context.requestData.headers
    • context.requestData.cookies
      Note: HTTP context is not enabled by default, enable the advanced configuration entry sps.httpRequestClaims to include headers and cookies in the context. See Advanced configuration properties.
  3. context.requestData.options- In the case of an assertion options or attestation options request, the context.requestData.options property contains the properties to be returned to the browser. In the case of an assertion result or attestation result request, the context.requestData.options property indicates the options which were provided to the client as part of this FIDO2/WebAuthn ceremony.
  4. context.requestData.registration - The registration that is used (in the case of an assertion result), or the registration about to be saved (in the case of an attestation result).

Other FIDO2 values such as the attestationStatement, authData, and clientData are also be available under context.requestData. The context object is native JavaScript, and can be accessed as an associative array.

When developing mediators the following line can be used to print the entire context variable:
IDMappingExtUtils.traceString(JSON.stringify(context));
Note: Ensure com.tivoli.am.fim.trustserver.sts.utilities.*=ALL trace is enabled.

Complete list of variables available in the mediator context

  1. stsuu- The users current identity. Read only.
  2. context- All of the context data. Read only. Native JSON.
  3. responseData- Java HashMap, writable. Available only in attestation result and assertion result requests. Responses are returned to the client.
  4. credentialData- Java HashMap, writable. Available only in attestation result and assertion result requests. Values are returned to the client in the same manner as responseData attributes, however, in the case of the authentication mechanism being used, it is the client and the credentialData attributes will be added to the user's credential directly.
  5. attributes- Java HashMap, writable. Values are stored in the registration. Only available in attestation result requests. On assertion result mediation, attribute values are available in the variable requestData.registration.attributes.
  6. error- Java HashMap, writable, Available in all options or results requests. If the message and status keys are populated they are returned to the caller as an error.

The traditional ISAM Java helpers area available in the mediator context, such as UserLookupHelper, LocalSTSClient, IDMappingExtUtils, and OAuthMappingExtUtils.