This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
Sign-in appearance: a realm’s colours, layout and logo
Each trust realm can give the pages a person sees its own look: four colours, one of three layouts, a display name and an uploaded logo. A realm that sets none of it looks exactly as the service always has.
What it changes is how the pages LOOK. The form on the sign-in screen, its fields, their order and their ids are the same in every layout, so a test or a password manager that fills them keeps working. The words stay in the reader’s language (Languages and regions); the display name is the one exception, an operator’s brand, shown as typed.
Which pages take it
- The sign-in screen and every step after it: the second factors, the emailed codes and links, the wallet sign-in, the identity-provider chooser, the password change and the SPNEGO pages.
- The consent screen at
/oauth2/consent. - GNAP’s interaction pages, the federation pages and the protocol
families’ description pages (
/saml2,/saml11,/xacml,/ssf,/scim,/spiffe). - The sign-out page at
/logout. The page drawn after a sign-out that still had something for the browser to do (front-channel logout frames, SAML LogoutRequests) is the protocols’ own and keeps the service’s look. - The front door at
/. When the realm has a logo, it takes the place of the service’s own image; with none, the front door is unchanged. - The user portal at
/portal: its colours, and the logo and name in its header.
The admin console does not change. It is the service’s own tool rather than the realm’s face to the people who sign in.
The settings
Every setting is per realm and takes effect at the next page load. The Every setting table lists them with their environment variables.
| Setting | Default | What it does |
|---|---|---|
branding.layout |
centered |
One of the three layouts below. |
branding.accentColor |
#12107c |
Buttons, links, focus rings, the split panel and the banner. |
branding.pageColor |
#f4f4f7 |
The background behind the card. |
branding.cardColor |
#ffffff |
The card the form is drawn on. |
branding.textColor |
#222222 |
The text on the card. |
branding.displayName |
(empty) | A name beside the logo and at the end of the browser tab’s title (Sign in — Acme). Plain text, at most 80 characters. |
branding.logoAlt |
(empty) | The logo’s alternative text. Required while there is a logo. At most 160 characters. |
branding.logoLinkUrl |
(empty) | Where the logo leads when followed: an absolute https URL, or empty for a logo that is not a link. |
branding.logoMaxBytes |
262144 |
The largest logo an upload may carry, for every realm (1 KiB to 2 MiB). |
Colours are written #rgb or #rrggbb and kept as lower-case #rrggbb.
Anything else, a colour name included, is refused (STS-CORE-0006).
The quieter tones are derived, not set. The text on a button is black or white, whichever reads better on the accent. The muted text of notes and hints, the borders and the rules are mixed from the text colour and the card colour, and the muted text never falls below the contrast rule. A realm that keeps the default text and card colours keeps the default tones exactly.
The contrast rule
A change that leaves the text or the accent (the links) below WCAG
2.2 AA contrast, 4.5:1, against the card is refused with
STS-AUTHN-0544, and nothing is written. The rule applies at every door:
the console, the management API, POST /admin-api/config/set and a restored
configuration.
Colours set together are judged together. A dark card with light text is
two changes that are each illegal alone and legal as a pair, so send them in
one request (the console’s page and POST /admin-api/branding/save both do).
The three layouts
centered(the default): the card in the middle of the page, with the logo and the display name above it.split: a panel in the accent colour beside the card, carrying the logo and the name. On a screen narrower than 720 pixels the panel sits above the card.banner: a band in the accent colour across the top, carrying the logo and the name, with the card below it.
Pages that are not a single card draw the layouts in the way their shape
allows. The front door, the sign-out page and the user portal draw both
split and banner as the band across the top: the front door and the
sign-out page are wide pages rather than a small card, and the portal
already has a navigation column beside its pages. centered puts the logo
and name above the page on all three.
The logo
- PNG, JPEG or WebP. The image’s own bytes decide the type, whatever the
upload’s
Content-Typesays; anything else is refused (STS-AUTHN-0545). SVG is not accepted. - Each side 16 to 2048 pixels (
STS-AUTHN-0547), and no larger thanbranding.logoMaxBytes, 256 KiB by default (STS-AUTHN-0546). It is drawn at most 240 pixels wide and 64 high, so a logo around twice that size stays sharp on a high-density screen. - Alternative text is required. An upload without it is refused, and
branding.logoAltcannot be emptied while the realm has a logo (STS-AUTHN-0548). - It is served from this service, at the realm’s
/web/branding/logo(/realm/acme/web/branding/logofor the realmacme). No other origin is added to a sign-in page, so no third party learns who is signing in, and it works in a deployment with no outside network. It is served withX-Content-Type-Options: nosniff, a sandboxing content security policy and anETag. A realm with no logo answers 404 there (STS-AUTHN-0549). - It is kept in the realm: every node and process serves the same logo,
and removing the realm removes it. Uploads and removals are audited
(
branding.logo), with the image’s digest and never its bytes.
An application’s own logo, the one its registration names, is a different thing: it stays inside the card, under the realm’s.
Setting it
In the console
Sign-in appearance, under the server configuration pages of the realm’s own console, edits all of it: the colours with their derived tones and contrast results, the layout, the display name, the logo with its alternative text and link, and the upload and removal. Its Preview opens the realm’s sign-in screen in a new tab with the values not yet saved, so they can be seen before they are kept; the preview is never a real sign-in.
Over the management API
The same acts, with an access token audienced to /admin-api
(Management API), in the realm the path names:
| Request | What it does |
|---|---|
GET /admin-api/branding |
Everything the console’s page shows: the layout and the layouts there are, the colours, the derived tones, the contrast of the text, links and button text, the display name, the logo’s alternative text and link, and the stored logo’s type, sides, size and digest (never its bytes). |
POST /admin-api/branding/save |
Writes the branding.* settings the JSON body names, judged together; nothing is written when any is refused. |
POST /admin-api/branding/logo |
The request body is the image. ?alt= sets the alternative text with it. It replaces the realm’s logo. |
POST /admin-api/branding/remove-logo |
Removes the logo. The alternative text stays, so the next upload needs none. |
GET /admin-api/openapi.json describes each of them. The colour and layout
settings can also be written one at a time with
POST /admin-api/config/set, under the same contrast rule.
# A dark card with light text, as one change in the realm "acme".
curl -X POST https://sts.example.com/realm/acme/admin-api/branding/save \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"branding.cardColor":"#111111","branding.textColor":"#eeeeee",
"branding.accentColor":"#8ab4f8","branding.layout":"banner",
"branding.displayName":"Acme"}'
# The logo, with its alternative text.
curl -X POST 'https://sts.example.com/realm/acme/admin-api/branding/logo?alt=Acme' \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: image/png' \
--data-binary @acme.png
How it reaches a page
A realm whose appearance differs from the default gets a stylesheet of its
own, /web/theme.css, linked after the page’s stylesheet. It carries only
colour values, each already checked to be six hex digits, so nothing an
administrator types becomes style text. The pages keep their content
security policy (style-src 'self', no inline style). The logo, the
alternative text, the link and the display name travel as attributes of the
page and are drawn as text by the page’s script.
A realm that sets nothing gets no extra stylesheet and no extra attribute: its pages are byte for byte what they were.