Browser-based custom screen auth token API authentication

Per the Tessitura Custom Screens (v15.0+) documentation, browser-based custom screens can be requested with an <<auth>> token passed as a URL parameter. This token represents the Tessitura Client's currently logged-in user's application session, and can be used to authenticate API requests with the user's security context.

This style of session token authentication is far preferable to the alternative, where the web application providing the browser-based custom screen must authenticate to the API as itself, be granted access to a maximum resource scope, and implement resource security on behalf of the API services based on the current user's usergroup. To do this securely, the web application must also request the user to log into itself, inside of a custom tab inside a Tessitura client app session that the user has already authenticated to. This complicates security implementation and the double-login requirement makes for bad UX.

To make use of this method of authentication, the custom web application can be largely if not entirely stateless. The only tradeoff is that API resource permissions must be granted to the Tessitura User Groups that the users operate under. In the case of custom tabs/screens, it would be advisable to bundle appropriate API permissions with access to the custom screen security object itself.

The authentication flow looks something like this:

1. TR_CUSTOM_TAB is configured with an entry for https://your.app/?token=<<auth>>, and usergroups are granted permission to this custom tab and to any API Resources that will need to be accessed (logging in as an Admin group circumvents this requirement and can be useful for testing).
2. User opens the custom tab. Custom web app receives a GET request from the embedded browser containing the auth token in the URL.
3. Web app must parse URL parameters obtaining the token value, decoding any URL %-encoding which is likely to occur in the auth token parameter. Most libraries and frameworks will do this automatically.
4. Web app can now make a request to the Tessitura API. Instead of using traditional basic auth (Username:Usergroup:Location:Password), the request can simply provide a token authorization header as follows: Authorization: Token <token>.

Depending on the specific needs of the web app, it is likely advisable for the token to be returned back to the frontend as a session cookie, since the URL parameter provided by Tessitura is only guaranteed when the custom screen is loaded for the first time (or reloaded). Any navigations the user does from within the custom screen (e.g. by clicking an <a> tag) will navigate to whatever href has been provided by the web app. An app developer may opt to provide the auth token in all such hrefs instead of using the session cookie approach, but this is up to personal taste.