Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve SSO documentation with detailed UAA setup #4833

Merged
merged 1 commit into from
Dec 9, 2020
Merged

Improve SSO documentation with detailed UAA setup #4833

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions website/docs/advanced/sso.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down