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:

  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:

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

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.

On this page