WebTerminal is broken on IRIS 2024.2

I'm posting this for the benefit of WebTerminal users who have upgraded to the recently-released IRIS 2024.2 -- (Build 247U) Tue Jul 16 2024 09:52:30 EDT -- or are considering doing so.

That version of 2024.2 contains a change (DP-432503) which requires that the user under which the Web Gateway initially connects to IRIS (usually CSPSystem) must have READ permission on the database hosting the dispatch class of the REST web application.

For cases where that is not true an error is raised, but this returns an HTTP 404 status to the caller instead of the expected HTTP 401.

Apparently the problem will be fixed in 2024.3, reference DP-432898 / ALI048 : REST Login endpoints to return 401 HTTP error instead of 404, but as a Continuous Delivery (CD) release 2024.2 won't get a maintenance release correction.

Workaround is to arrange for CSPSystem to have READ permission on the database of the namespace you installed WebTerminal in.

Here's how I did it:

1. Create a new security resource %DB_WEBTERMINAL and set the WEBTERMINAL database to use this instead of %DB_%DEFAULT.
2. Create a role %DB_WEBTERMINAL that gives the role-holder RW access to the %DB_WEBTERMINAL resource.
3. Create another role (I called mine DBread_WEBTERMINAL) that gives the role-holder only R access to that resource.
4. Give the CSPSystem user the DBread_WEBTERMINAL role. This works around the 2024.2 bug.
5. Edit the /terminalsocket web application and add %DB_WEBTERMINAL to the Application Roles tab. This step is necessary because WebTerminal initially runs its websocket process as UnknownUser and needs to update state information in its database even before it switches to run as the authenticated user.

An easier but less secure technique would be:

1. Create a new security resource %DB_WEBTERMINAL with RW public privileges, then set the WEBTERMINAL database to use this instead of %DB_%DEFAULT.

More details at https://github.com/intersystems-community/webterminal/issues/155