Skip to main content

Customizations

Custom scope configuration

DAPI allows to configure custom scopes, which can be used to allow defining custom proof templates. The configuration is done in the dapi database, in the scopes table. The scopes table has the following columns:

  • name: name of scope, which is derived from the scope claim in the ID token (e.g. openid or email or openid email). As for RFC of OIDC scopes are space separated and not ordered, the name of the scope in DB is ordered alphabetically and separated by - (e.g. openid email -> 'email-openid').
  • proof_template: name of the proof template to be used for this scope. The proof template must be defined in the DARS console.

This configuration can be made only requesting support for managed solutions or manually in case of self hosted solution.

Custom mappers configuration

DAPI allows to configure custom mappers, which can be used to allow defining custom jwt tokens starting from proof templates.

There are two types of mappers:

  • Naive mapper: the mapper is configured to map a proof template to a jwt token directly. This addes some limitation to proof-template definition, for example, the proof template must have a required username which will be used as a nickname and sub claim in the jwt token.
  • Configurable mapper: the mapper is configured to map a proof template to a jwt token, but the jwt token is configurable by the user. The user can define the jwt token claims and the proof template attributes to be used for each claim. The configurable mapper is more flexible than the naive mapper, but it requires more configuration.

The flow is the following:

  1. Once received a proof template, the Configurable mapper is used first if it is configured for the scope.
  2. If the configurable mapper is not configured for the scope, the naive mapper is used.

Configurable mapper

The configuration is done in the dapi database, in the mappers table. The mappers table has the following columns:

  • id: id of the mapper
  • client_id: client id of the client for which the mapper is configured
  • scope: scope for which the mapper is configured
  • mapper: the mapper configuration json.

Example of mapper:

Let's consider the next proof:

{
  "revealed_attributes": {
    "email": "example@dizme.io",
    "name": "John Doe",
    "phone_number": "+393331234567"
  },
  "self_attested_attributes": {
    "eye_color": "red"
  },
  "unrevealed_attributes": {}
}

As a result, we want to have the following jwt token:

{
  "email": "example@dizme.io",
  "email_verified": true,
  "nickname": "example@dizme.io",
  "retina": "red",
  "cell": "+393331234567",
  "sub": "example@dizme.io"
}

To achieve this result we need to configure the following mapper:

{
  "email": "revealed_attributes.email",
  "nickname": "revealed_attributes.email",
  "retina": "self_attested_attributes.eye_color",
  "cell": "revealed_attributes.phone_number"
}

Notes:

  • the sub claim is not configurable, it is always set to the nickname claim.
  • the email_verified claim is not configurable, it is always set to true when the email field is present.

Important limitation:

  • Implicit flow is not supported and a naive mapper is used instead.

This configuration can be made only by requesting support for managed solutions or manually in the case of self-hosted solutions.

Template customization

The template is customizable using a .zip file. The .zip file must contain at least the following files:

  • index-<lang>.html: the main HTML
  • 404-<lang>.html: the client_id not found
  • 500-<lang>.html: generic error

The <lang> is the language code, for example en or it. The zip file must be included into helm_chart/values/customizations/<wallet_name>/customizer.zip. In the helm chart isCustomizationEnabled: true must be set.

This configuration can be made only by requesting support for managed solutions or manually in the case of self-hosted solutions.

Template editing

The main page, index.html, displays a widget that enables users to authenticate with the OIDC SSI Gateway. It has several variables that are customizable during the client_id creation process. These variables include:

  • {{domain}}: the client's domain, usually employed for redirecting back.
  • {{provider_img}}: the client's image, commonly used for branding purposes.
  • {{client_id}}: the client's unique ID.
  • {{redirect_url}}: the client's callback URL, which is typically an RP callback URL.

Additionally, there are system-level variables used to create the widget URL, including:

  • {{proof_id}}: used to identify the proof.
  • {{agent}}: the agent endpoint used to connect to the agent.
  • {{org_id}}: identifies the organization.
  • {{proof_template}}: identifies the proof template used in the widget.
  • {{oob}}: identifies the out-of-band connection used in the widget.
  • {{service}}: identifies the DAPI service used in the widget on the agent callback.

It is important to note that editing these system-level variables is not recommended as they are crucial to the proper functioning of the OIDC SSI Gateway. Only edit the content between <!-- DO NOT TOUCH FROM HERE --> and <!-- DO NOT TOUCH UNTIL HERE --> if you have a clear understanding of what you are doing.

The 500.html page is a generic error page that displays an error code. It includes a variable, {{ message }}, which provides the support team with a numeric code that can be used to troubleshoot issues.

See an example of customization file How-to-customize

Back to top