Use a Custom Approval Template#

During the login flow, ESS’ Solid OIDC Broker Service displays an approval page so that an application can receive the access/ID tokens.

For example, the following image shows the default approval page for the My Example App:

Default Approval Page for the :guilabel:`My Example App`.

Qute Template#

ESS’ Solid OIDC Broker Service uses the Qute Templating Engine to generate the approval page from a template. The template can use the following expressions for the client metadata and the requested scopes:


The name of the application.


The client identifier for the application.


The client logo.


The client privacy policy.


The client Terms of Service.


The request scopes.

Default Template#

Starting in version 2.2, the default approval template:

  • Clarifies the description of the requested scopes; i.e., the requested permissions;

  • No longer displays the Inrupt logo on the top left;

  • No longer displays an About section (which included links to the client’s privacy policy and terms of service, if set).

Using a Custom Template#

Instead of the default template, you can use your own template. To use your own template:

  1. Add the new template file (and associated files such as a *.css file) to the Solid OIDC Broker Service container.


Example Customization#

The following configuration adds the new template (and associated files) to the Solid OIDC Broker Service container and updates the INRUPT_OPENID_APPROVAL_TEMPLATE_LOCATION property to the path of the file in the container.

  1. Go to your ESS installation directory:

    cd ${HOME}/ess
  2. Create a directory with your template files and configuration.

    1. Create a new directory custom-approval/ under the directory and switch to the new directory:

      mkdir custom-approval/ && cd custom-approval/
    2. In the directory, add your new template and any other files used in the template, such as stylesheet and/or images. In the example, assume the new template is named approval.html and uses styles.css and logo.svg. Add the three files to the custom-approval/ directory.

    3. In the directory, create a kustomization.yaml with the following content:

      ### custom-approval/kustomization.yaml
      kind: Component
      ## Add the files to the configMapGenerator
        - name: ess-openid-custom-approval-files-configmap
          namespace: ess
            - ./approval.html
            - ./styles.css
            - ./logo.svg
        ## For ess-openid:
        ## - create a Docker volume using the configMap 
        ## - mount the volume, specifying a path in the container 
        - target:
            kind: Deployment
            name: ess-openid
          patch: |-
            apiVersion: apps/v1
            kind: Deployment
              name: not-important
                    - name: ess-openid-custom-approval-volume
                        name: ess-openid-custom-approval-files-configmap
                    - name: ess-openid
                        - mountPath: /deployments/custom/approval/
                          name: ess-openid-custom-approval-volume
        ## For ess-openid:
        ##   the mounted volume path + template html page
        - target:
            kind: Deployment
            name: ess-openid
          patch: |
            - op: add
              path: /spec/template/spec/containers/0/env/-
                value: /deployments/custom/approval/approval.html

      The customization specified in the file:

      • Adds the template and associated files to a configMapGenerator named ess-openid-custom-approval-files-configMap.

      • Creates a volume ess-openid-custom-approval-volume using the ess-openid-custom-approval-files-configMap configMap.

      • Mounts the volume at the specified mount path. The mount path is the directory inside the container where you want to access the volume. This example uses /deployments/custom/approval/ as the mount path. If you choose to use a different path, ensure you also update the INRUPT_OPENID_APPROVAL_TEMPLATE_LOCATION configuration as well.

      • Sets the INRUPT_OPENID_APPROVAL_TEMPLATE_LOCATION to the template file in the mounted path. In this example, /deployments/custom/approval/approval.html.

  3. Go back to your ESS installation directory:

    cd ${HOME}/ess
  4. Modify the kustomization.yaml (i.e., step 3 of the Applying Your Customizations procedure).

    Specifically, add the highlighted content (the custom-approval/ component) to the kustomization.yaml file

    # kustomization.yaml in your ESS installation directory
    # ...  Preceding content omitted for brevity 
    # ...
      // ... Preceding contents of components omitted for brevity
      - custom-approval/
  5. Continue with the rest of the Applying Your Customizations procedure.

For additional configuration properties for the ESS Broker, see Solid OIDC Broker Service.