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:

`{client.clientName}`	The name of the application.
`{client.clientId}`	The client identifier for the application.
`{client.logoUri}`	The client logo.
`{client.policyUri}`	The client privacy policy.
`{client.tosUri}`	The client Terms of Service.
`{scopes}`	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:

Add the new template file (and associated files such as a *.css file) to the Solid OIDC Broker Service container.
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.