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:

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

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.

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

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
      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:

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

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

      3. 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_LOCATIONconfiguration as well.

      4. 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 
# ...
components:
  // ... 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.