Use a Custom Approval Template#

ESS’ Solid OIDC Broker Service displays an approval page when, during the login flow, an application requests access to user information (such as the user’s WebID). The default approval page displays, if provided during client registration or in Solid-OIDC Client ID Document, the application’s name, logo, policy, and terms of service.

For example, the following image shows the default approval page for the My Example App; the My Example App does not specify a logo or terms of service or policy.

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 default template uses the following value expressions for the client metadata and the requested scopes:

{client.clientName}
{client.clientId}
{client.logoUri}
{client.policyUri}
{client.tosUri}
{scopes}

Instead of the default template, you can use your own template. To use your own template, add the new template (and associated files such as *.css file) to the Solid OIDC Broker Service container and update the INRUPT_OPENID_APPROVAL_TEMPLATE_LOCATION property.

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.

Go to your ESS installation directory:
```
cd ${HOME}/ess
```

Create a directory with your template files and configuration.

Create a new directory custom-approval/ under the directory and switch to the new directory:
```
mkdir custom-approval/ && cd custom-approval/
```
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.

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

### custom-approval/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

## Add the files to the configMapGenerator

configMapGenerator:
  - name: ess-openid-custom-approval-files-configmap
    namespace: ess
    files:
      - ./approval.html
      - ./styles.css
      - ./logo.svg

patches:
  ## 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
      metadata:
        name: not-important
      spec:
        template:
          spec:
            volumes:
              - name: ess-openid-custom-approval-volume
                configMap:
                  name: ess-openid-custom-approval-files-configmap
            containers:
              - name: ess-openid
                volumeMounts:
                  - mountPath: /deployments/custom/approval/
                    name: ess-openid-custom-approval-volume
  ## For ess-openid:
  ## - Update the INRUPT_OPENID_APPROVAL_TEMPLATE_LOCATION to 
  ##   the mounted volume path + template html page
  - target:
      kind: Deployment
      name: ess-openid
    patch: |
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: INRUPT_OPENID_APPROVAL_TEMPLATE_LOCATION
          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.

Go back to your ESS installation directory:
```
cd ${HOME}/ess
```

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 
# ...

components:
  // ... Preceding contents of components omitted for brevity
  - custom-approval/

Continue with the rest of the Applying Your Customizations procedure.

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