PKI 10.4 Access Banner Design - dogtagpki/pki GitHub Wiki

Overview

This page describes the enhancements to support access banner functionality added in PKI 10.4.

This enhancement provides a configurable access banner (e.g. warning, terms of service) that will appear at the beginning of a private user session in PKI Web UI, PKI Console, and PKI CLI. The user will be required to acknowledge the content of the banner in order to continue using the application.

Considerations

  • Banner should be part of server configuration accessible by the admin.

  • Banner should be displayed before or at the beginning of the SSL connection in CLI, Web UI, and Console.

  • A user can start from any page within the web UI. Banner should be displayed regardless of the starting page.

  • If the session is reestablished after expiration, the banner should be displayed again.

  • Banner can be ignored on CLI for automation.

Configuration

Each PKI server instance can be configured to provide access banner for its clients. By default the banner is not installed.

To install banner on a PKI server instance, store the content of the banner in banner.txt in the instance’s configuration folder (i.e. /var/lib/pki/<instance>/conf), for example:

WARNING!
Access to this service is restricted to those individuals with
specific permissions. Any attempts to gain access, authorized
or not, and all operations that follow, are audited and could
be used against you in the court of law.

To uninstall banner simply remove the banner.txt.

Note: banner configuration can be changed at any time without requiring server restart. However, the client (e.g. web browser) may cache the content of an old banner, so there is no guarantee that the client will immediately see the changes.

This is documented in Access Banner.

REST Services

PKI server will provide REST services to provide the content of the banner to the client and to keep track whether the banner has been displayed in the current session.

  • Server info service:

    • Operation: GET /pki/rest/info

    • Input: none

    • Output: version number, banner

  • Login service:

    • Operation: POST /pki/rest/login

    • Input: none

    • Output: none

These services will be deployed under the /pki web application. The web deployment file for this web application is located at /usr/share/pki/server/webapps/pki/WEB-INF/web.xml. The web deployment contains various settings including session timeout.

PKI UI

PKI UI consists of the following pages:

The root page will simply redirect to the welcome page.

The welcome page will provide a button/link to go to the main page.

The main page will provide links to PKI subsystem UIs installed in the instance. The main page can only be accessed with SSL connection. The PKI subsystem UIs will continue to accept secure and unsecured connection like before.

Regardless of which page in PKI UI the user started from, when the user first starts the SSL connection the browser will ask the user to optionally provide a client certificate for authentication. After that access banner will be displayed in a dialog box. If the user clicks Cancel the UI will redirect to the welcome page. If the user clicks OK the UI will stay on the same page. If the user revisits the page after clicking OK, the banner will not reappear until the session is closed or has expired.

PKI Console

If banner is disabled, the PKI Console will work exactly the same as before.

If banner is enabled, when PKI Console is started it will call the REST service to retrieve the banner, then display the banner on the terminal. It will ask the user whether to continue with the application. If the user answers No the application will exit immediately. If the user answers Yes the application will continue as before (e.g. asking the user for the username and password).

$ pkiconsole https://pki.example.com:8443/ca
WARNING!
Access to this service is restricted to those individuals with
specific permissions. Any attempts to gain access, authorized
or not, and all operations that follow, are audited and could
be used against you in the court of law.

Do you want to proceed (y/N)? y

This is documented in PKI Console.

PKI CLI

When a user invokes PKI CLI, the CLI will retrieve the banner from the server and display the banner will before executing the program:

$ pki -n caadmin ca-user-find
WARNING!
Access to this service is restricted to those individuals with
specific permissions. Any attempts to gain access, authorized
or not, and all operations that follow, are audited and could
be used against you in the court of law.

Do you want to proceed (y/N)? Y
-----------------
3 entries matched
-----------------
  User ID: CA-pki.example.com-8443
  Full name: CA-pki.example.com-8443

  User ID: caadmin
  Full name: caadmin

  User ID: pkidbuser
  Full name: pkidbuser
----------------------------
Number of entries returned 3
----------------------------

To bypass banner (e.g. for automation) the CLI will support --ignore-banner option.

This is documented in PKI CLI Options.

Tip
 To find a page in the Wiki, enter the keywords in search field, press Enter, then click Wikis.
⚠️ **GitHub.com Fallback** ⚠️