diff --git a/how-to/integrate-server-authentication/README.md b/how-to/integrate-server-authentication/README.md
index 0823f9d544..37a0cf90ff 100644
--- a/how-to/integrate-server-authentication/README.md
+++ b/how-to/integrate-server-authentication/README.md
@@ -6,7 +6,91 @@
Your OpenFin application will often need to authenticate using a server login page before use, this examples demonstrates such an integration.
-This application you are about to install is a simple example of plugging in your own content or app. The basic server intercepts a request to the provider window and checks to see if you are authenticated. If you are not it redirects to a login screen. If you are then it will load the provider window. The settings in the manifest make the provider window visible (so it acts as a splash screen or the location where the login form will be displayed). When you have an authenticated session and the splash screen is visible then the provider will hide itself after a period of time and launch the main application window. This example assumes you have already [set up your development environment](https://developers.openfin.co/of-docs/docs/set-up-your-dev-environment)
+This application you are about to install is a simple example of plugging in your own content or app. The basic server intercepts a request to the provider window and checks to see if you are authenticated. If you are not it redirects to a login screen. If you are then it will load the provider window.
+
+This example assumes you have already [set up your development environment](https://developers.openfin.co/of-docs/docs/set-up-your-dev-environment)
+
+There are two use cases covered:
+
+## Server side authentication with the platform provider window visible
+
+The settings in the [manifest.fin.json](./public/manifest.fin.json) make the provider window visible (so it acts as a splash screen or the location where the login form will be displayed). When you have an authenticated session and the splash screen is visible then the provider will hide itself after a period of time and launch the main application window.
+
+```json
+"platform": {
+ ...
+ "autoShow": true,
+ "providerUrl": "http://localhost:8080/platform/provider.html",
+ },
+```
+
+## Server side authentication with the platform provider window invisible
+
+The settings in the [second.manifest.fin.json](./public/second.manifest.fin.json) make the provider window invisible. When the server redirects to a login screen then a preload script which is loaded into the provider window checks to see if the window should be visible (if it is the login screen) or if an error window should be shown (if it isn't the login screen and it isn't the provider window....i.e. it has become stuck as part of a redirect).
+
+```json
+"platform": {
+ ...
+ "autoShow": false,
+ "providerUrl": "http://localhost:8080/platform/provider.html",
+ "preloadScripts": [
+ {
+ "url": "http://localhost:8080/preload/auth-preload-check.js"
+ }
+ ]
+ },
+```
+
+The preload script needs to be in an area that does not require authentication (as you haven't been authenticated yet if you are on the login screen).
+
+The [preload script](./public/preload/auth-preload-check.js) is an example and should not be treated as production code:
+
+```javascript
+document.addEventListener('DOMContentLoaded', async () => {
+ console.log('auth-preload-check.js loaded. Performing logic checks.');
+ // preload scripts can be loaded into an iframe so only check the top level window
+ if (window === window.top && window.fin !== undefined) {
+ // TODO: ADD YOUR OWN LOGIC HERE
+ console.log('auth-preload-check.js logic starting.');
+ // Create a new URL object from the current window location
+ const url = new URL(window.location.href);
+
+ // TODO: ADD YOUR OWN PATH LOGIC HERE
+ // determine behavior based on the current URL (we have example paths)
+ if (url.pathname === '/app/login') {
+ console.log('Detected we are on the login page.');
+ // If we are on the login page ensure the page is visible
+ await fin.me.show();
+ } else {
+ // ensure the page is hidden as we may have shown it if it was the login page and we are now on a redirect page or the provider.
+ console.log('We are on a page that should not be visible. Ensuring the window is hidden.');
+ await fin.me.hide();
+ }
+
+ // TODO: WHEN STUCK OR UNHAPPY PATH DETERMINE WHAT TO DO NEXT
+ // We provide an example of launching a new window to show a friendly error message
+ if (url.pathname === '/app/stuck') {
+ console.log(
+ 'Detected we are authenticated but a redirect has encountered an error and is stuck so the main provider.html page will not be loaded. Showing a friendly error message.'
+ );
+ window.open('/app/friendly-error', '_blank');
+ }
+ }
+});
+```
+
+## Login Accounts
+
+There are two login accounts that simulate a successful scenario and a stuck scenario. The stuck scenario is a redirect page the platform doesn't control so when it happens the manifest.fin.json file will be stuck on that page. The second.manifest.fin.json file uses a preload script that detects it is on a stuck page and launches a user error page.
+
+- Success account: `test@example.com / pass1234`
+- Stuck account: `stuck@example.com / pass1234`
+
+## Things to note
+
+You may have different paths depending on environment. You might decide to have environment based preload scripts that are assigned to the environment specific manifest file.
+
+Consider the unhappy path. What would be helpful to your users and your support team if a user could not login to your platform. In our example we show a pop up window but your business/product owner should be involved in the conversation.
## Running the Sample
@@ -44,14 +128,26 @@ npm run start
npm run client
```
+or to run the hidden provider window using a preload script:
+
+```shell
+npm run secondclient
+```
+
5. If you modify and want to build the code you can run the build command.
```shell
npm run build
```
+## Scenario 1 - manifest.fin.json - Visible Provider Window
+
![Server Authentication](openfin-integrate-server-authentication.gif)
+## Scenario 2 - second.manifest.fin.json - Invisible Provider Window
+
+![Server Authentication Hidden Provider](openfin-integrate-server-authentication-hidden.gif)
+
---
### Read more about [working with Workspace](https://developers.openfin.co/of-docs/docs/overview-of-workspace)
diff --git a/how-to/integrate-server-authentication/openfin-integrate-server-authentication-hidden.gif b/how-to/integrate-server-authentication/openfin-integrate-server-authentication-hidden.gif
new file mode 100644
index 0000000000..6afa90f8b7
Binary files /dev/null and b/how-to/integrate-server-authentication/openfin-integrate-server-authentication-hidden.gif differ
diff --git a/how-to/integrate-server-authentication/openfin-integrate-server-authentication.gif b/how-to/integrate-server-authentication/openfin-integrate-server-authentication.gif
index d4003c78e5..520795274a 100644
Binary files a/how-to/integrate-server-authentication/openfin-integrate-server-authentication.gif and b/how-to/integrate-server-authentication/openfin-integrate-server-authentication.gif differ
diff --git a/how-to/integrate-server-authentication/package.json b/how-to/integrate-server-authentication/package.json
index 65ea4bd81f..b345139d25 100644
--- a/how-to/integrate-server-authentication/package.json
+++ b/how-to/integrate-server-authentication/package.json
@@ -7,6 +7,7 @@
"dos": "node ./scripts/dos.mjs && node ./scripts/kill.mjs",
"kill": "node ./scripts/kill.mjs",
"client": "node ./scripts/launch.mjs",
+ "secondclient": "node ./scripts/launch.mjs http://localhost:8080/second.manifest.fin.json",
"build-client": "webpack build --config ./client/webpack.config.js --mode=development",
"build-server": "tsc --project ./server",
"build": "npm run build-server && npm run build-client",
diff --git a/how-to/integrate-server-authentication/public/app/friendly-error.html b/how-to/integrate-server-authentication/public/app/friendly-error.html
new file mode 100644
index 0000000000..8920e817fb
--- /dev/null
+++ b/how-to/integrate-server-authentication/public/app/friendly-error.html
@@ -0,0 +1,52 @@
+
+
+
+
+
+ Friendly Error Page
+
+
+
+
+
+
+
+
+
+
Friendly Error Page
+
We are on the unhappy path.
+
+
+
+
+
+
+
+ The provider has not been loaded due to an error so the platform cannot perform the necessary
+ bootstrapping steps to launch the platform.
+
+
If you logout and exit you will be presented with the login screen again.
+
If you just exit you will be presented with this screen again.