FIDO2 Mediation

When we 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 options request, modified options can be returned to client. Update attestation options with:
    attestation_options.put("mediated_attribute", {"test":true});

  3. 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("exampleAttribute", "exampleValue");
    Only String attributes can be stored with the registration.

    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.

  4. During mediation of an assertion option request, modified options can be returned to client. Update assertion options with:
    assertion_options.put(“example_attribute”, “example_value”);

  5. 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 that returns the model name of the authenticator.

  6. 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);
credentialData.put("credentialList", ["list", "of", "credentials"]);

    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 Verify Access credential. Only String and Lists of strings 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

      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 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));
Ensure com.tivoli.am.fim.trustserver.sts.utilities.*=ALL trace is enabled.

Complete list of variables available in the mediator context

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


Parent topic: FIDO and WebAuthn Support