Interaction hook
Many issuance workflows require the issuer to perform custom interactions with the user. This could include gathering more information, introducing additional authentication steps (e.g. 2FA, MFA or biometric checks) or communicating the terms of service.
To facilitate this you can configure MATTR VII to invoke an interaction hook which will redirect the user to a custom component. This redirect happens after the user is authenticated but before the credential is issued. The redirect can include any user claims retrieved from the Authentication provider, and these can be consumed and used by the interaction hook component.
The interaction hook component must be publicly available, and thus requires access controls to protect it from unauthorised access. MATTR VII interaction hook integration supports a JWT HS256-based authorisation scheme to enable this.
When MATTR VII redirects the end user to your interaction hook component, it will include a JWT
object as a session_token query parameter. Your interaction hook component should verify this JWT
object using the interaction hook secret to make sure that the request is legitimate. This
secret can be obtained when you
configure an interaction hook. If the verification
fails, the request should be rejected.
This token is passed in the URL, and is subject to the max URL character limits. Limits differ amongst browsers but 2000 characters should meet most browsers requirements. This means that you shouldn’t transfer big files (for example images) to and/or from the Interaction hook component.
Once the end user completes the interaction hook journey, they need to be redirected back to MATTR
VII to complete the issuance workflow. The redirect URL can be found in the session token JWT
payload, and the issuer must generate and sign a new JWT token using the same secret, and include
it as a query parameter with the redirect.
Any claims returned by the interaction hook component can be included in the issued credential. However, they are not persisted on your tenant unless the interaction hook is explicitly configured to do.
Upon the successful completion of the interaction hook, your custom component will redirect the user back to their digital wallet to complete the credential issuance flow.
If your interaction hook component determines that the user should not be allowed to continue with the issuance journey (for example, they’ve failed a biometrics test), you can return an error in your signed JWT which will signal to the issuance journey that it should fail.
Best practices
- Interaction hook components can be either a web or native application. We recommend using web applications as they are more compatible with most scenarios.
- You can combine several custom interactions as part of the issuance workflow by building them into a single Interaction hook component.