Configure an Interaction hook

You can configure an Interaction hook via our Self service portal as well.

Overview

Many credential issuance journeys require the issuer to perform custom interactions with the user. This could be gathering more information, performing additional authentication steps (E.g, 2FA, MFA or biometric checks) or communicating the terms of service.

 To facilitate this requirement, you can configure MATTR VII to invoke an interaction hook which will redirect the user to a custom component during the credential issuance journey. This redirect happens after the user is authenticated with your configured identity provider but before the credential is issued to the user. 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.

Your interaction hook component can be either a web or native application.  We recommend using a web interface because it's more compatible with most scenarios.

You can only configure one interaction hook on your MATTR VII tenant. If you require several custom interactions as part of the credential issuance workflow, they should all be linked into a single interaction hook component.

Request

Make the following request to configure an interaction hook:

1PUT https://YOUR_TENANT_URL/v1/openid/configuration

1{
2    "interactionHook": {
3        "url": "https://example-university.com/callback",
4        "claims": [],
5        "sessionTimeoutInSec": 1200,
6        "disabled": false
7    }
8}

• url: The interaction hook URL that the user will be redirected to after completing the authentication process:

  • Must be a valid URL.

  • Must use the HTTPS protocol.

  • Must not be an IP address.

  • Must not include query parameters.

• claims: An array of user attributes that will be returned in the authentication response. These claims are included in the session token that is sent to the interaction hook.

• sessionTimeoutInSec: Interaction hook session duration (in seconds). Once a session expires, the user is shown an error when they are redirected. If not specified, the default environment session duration is applied.

• disabled: Indicates whether the interactions hook is disabled. When false, the interactions hook is enabled. This means that users will be redirected to your interaction hook component (http://example-university.com/callback) after they've authenticated themselves against your IdP.

Response

1{
2    "interactionHook": {
3        "url": "https://example-university.com/callback",
4        "claims": [],
5        "sessionTimeoutInSec": 1200,
6        "disabled": false,
7        "secret": "dGtUrijBOT6UUJ8JO4kAFyGfhahDlVVeIk/sPbWTa7c="
8    }
9}

• secret: Must be used by your interaction hook component to sign a new JWT with any additional claims that you may include. Refer to Authorise an interaction hook for more information.

What's next?

Now that you have your interaction hooks configured, you can configure a claims source as part of your OpenId4VCI issuance workflow.

If your use case does not require a claims source, you can proceed to create a credential configuration.