OpenID Connect

Three further settings under valsightOpenIdConnectProperties control what the login page offers and which scopes each login option requests: buttonText (see Login button label), additionalScopes (see Additional scopes), and the alternativeLogin group (see Alternative login flow).

Login button label

Available since 7.2.5 and 7.3.0.

This key sets a default, it does not override: whatever an administrator has saved under Login Page Settings wins whenever it is set. See Login Page Customization for that setting.

Use buttonText to ship a label together with the configuration file, so a newly installed instance already shows the right wording before anyone opens the settings page. If neither is set, the button reads OpenID Connect.

Additional scopes

Available since 7.2.5 and 7.3.0.

Write the value either as a YAML list or as a single string with the scopes separated by commas, whitespace, or both. The scopes are added to scope; nothing is removed.

The typical use is an identity provider that accepts an organization scope. Sending it pins the login to one organization, so the user reaches their own identity provider directly instead of first having to enter an email address for domain discovery.

That same scope excludes everyone who is not a member of that organization. Those users need the alternative login flow.

Alternative login flow

Available since 7.2.5 and 7.3.0.

A second login option that requests a different set of scopes from the same OpenID Connect client. It exists for the users an organization scope in additionalScopes would otherwise lock out, for example staff who authenticate against a different organization’s identity provider.

The flow is requested with a query parameter on the authorization URL:

<server_url>/<contextPath>/oauth2/authorization/openIdConnect?loginFlow=alternative

That parameter only selects between scope sets already configured on the server. An absent, unknown, or unconfigured value falls back to the primary scopes, so no caller can request scopes of their own.

On the login page the option is rendered as a link below the OpenID Connect button rather than as a second button, because it is a variant of the same provider and not a login method of its own.

When the enabled key is needed

Configuring either additionalScopes or buttonText under alternativeLogin already enables the flow, so most instances need no enabled key at all. Set it explicitly in two cases:

• enabled: true for a flow that has neither scopes nor a label of its own, which is otherwise indistinguishable from an unconfigured one.
• enabled: false to switch a configured flow off without deleting its keys.

An empty scope list is a valid configuration

Leaving alternativeLogin → additionalScopes empty is a meaningful configuration rather than a pointless one. The flow then sends only the scopes listed under scope, and so no organization scope at all, which is what makes the identity provider fall back to its own account chooser.

For that reason the alternative flow never falls back to the primary additionalScopes. Once the flow is enabled, requesting it always replaces the primary scopes, even when it defines none.

Listing the link for some clients only

Name a request header in requiredHeader and the link is listed only for clients whose request carries it; leave the key unset and the link is listed for everyone. Use it where a login page carries one customer’s branding and the alternative option is meant for a different group of users — staff, say — who can be told apart by something the infrastructure in front of Valsight already knows.

Which clients get the header is decided in that infrastructure and not in Valsight. The application never interprets the value, only whether the header is there with a non-blank value, so the header can mean whatever the deployment needs it to mean.

Two requirements on whichever component injects it:

• It has to set the header on every request, so that a copy sent by the client is always overwritten. If a client could supply the header itself, the setting would gate on nothing.
• It has to be a component the request cannot bypass. Valsight reads the configured header alone, with no fallback to X-Forwarded-For or X-Real-IP, because a client writes those freely. See Reverse Proxy.

Hiding the link decides what the login page offers; it is not an access rule. The flow’s URL keeps working without the header, and opening the login page with ?alternativeLogin=1 lists the link for any client:

<server_url>/<contextPath>/app/index.html#/login?alternativeLogin=1

Give that URL to the users the flow is for who reach the login page without the header. Where nothing injects the header, no client ever carries it and the link is only reached this way — so leave requiredHeader unset until the header is actually in place.

While requiredHeader is set, the login page’s data response carries a Vary header naming it, so a cache between Valsight and the browser cannot serve one client’s login page to another.

Example configuration

spring:
    security:
        oauth2:
            client:
                registration:
                    openIdConnect:
                        scope: openid, email, profile
                        valsightOpenIdConnectProperties:
                            buttonText: Log in with Acme ID
                            additionalScopes: urn:zitadel:iam:org:id:123456789456132
                            alternativeLogin:
                                # deliberately empty: send no organization scope at all
                                additionalScopes:
                                buttonText: Log in with a different organization
                                requiredHeader: x-internal-client

With this configuration the login page shows one Log in with Acme ID button that pins the login to the Acme organization. Clients whose request carries x-internal-client additionally get a Log in with a different organization link below it, which sends no organization scope. Drop the requiredHeader line to offer that link to everyone.