Improve SSO documentation with detailed UAA setup (#4833)

Document how to properly setup UAA client in production environment, with
proper listing in login home page.

website/docs/advanced/sso.md

@@ -76,6 +76,68 @@ Further configuration of SSO is provided through the `SSO_OPTIONS` environment v
 
 Setting this variable to `nosplash` will skip the need for users to press the Login button - users will jump straight to the configured SSO endpoint when accessing Stratos instead of first seeing the Stratos login page.
 
+### Using a dedicated UAA Client for Stratos
+
+In production environments, it's wise to setup a dedicated UAA client for
+Stratos SSO, instead of re-using the `cf` client, that already represents by
+the `cf` CLI.
+
+In this case, you can duplicate the `cf` client definition and create a
+`stratos-console` client, for example. In typical UAA deployment manifest with
+BOSH, you would typically add the following configuration properties to the
+`uaa` job, in the `uaa` instance group.
+
+```yaml
+uaa:
+  clients:
+    stratos-console:
+      authorized-grant-types: authorization_code
+      redirect-uri: https://console.((system_domain))/pp/v1/auth/sso_login_callback
+      autoapprove: true # Bypass users approval
+      # The following properties are copied from those of the default 'cf' client:
+      access-token-validity: 600
+      authorities: uaa.none
+      override: true
+      refresh-token-validity: 2592000
+      scope: network.admin,network.write,cloud_controller.read,cloud_controller.write,openid,password.write,cloud_controller.admin,scim.read,scim.write,doppler.firehose,uaa.user,routing.router_groups.read,routing.router_groups.write,cloud_controller.admin_read_only,cloud_controller.global_auditor,perm.admin,clients.read
+      secret: ""
+```
+
+### Listing the Stratos console as a registered application in UAA users home page
+
+With the above UAA client set though, the Stratos Console would still not be
+displayed as a registered SSO application in UAA users home page. (This home
+page is typically hosted at `https://login.{SYSTEM_DOMAIN}/home`.)
+
+In order to properly list the Stratos Console there, the `show-on-homepage`
+property has to be set to `true` and the `app-launch-url` property has to be
+perperly provided, with some non-`null` URL.
+
+The example below shows the whole setup, with a simplified PNG image as the
+`app-icon` though, to keep is concise.
+
+```
+uaa:
+  clients:
+    stratos-console:
+      name: Stratos Console
+      show-on-homepage: true
+      app-launch-url: https://console.((system_domain))
+      app-icon: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAD1BMVEWZttQvMDEoKisqKywAAAApvvoVAAAAGElEQVQYlWNgYUQBLAxMDCiAeXgLoHsfAD03AHOyfqy1AAAAAElFTkSuQmCC
+```
+
+If you need an `app-icon` that properly displays the Stratos logo though, here
+is one you could use. This is the Stratos logo, reduced to 68x68 because
+that's the size the UAA users home page will display it. This is still 4.91 KB
+of PNG data though, as it is Base64-encoded.
+
+```
+uaa:
+  clients:
+    stratos-console:
+      app-icon: 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
+```
+
 ## Troubleshooting
 
 1. User has selected the incorrect application authorities when logging in to Stratos via SSO for the first time.