Skip to content

Upgrading to v11

v11 checks an SSO domain with Internet Identity instead of with the organization’s server, and reports the answer as client state.

A client built with ssoDomain now checks its own domain as soon as it is built, and getSsoStatus() reports the answer. Read it like getStatus(), and re-read it when subscribe() fires:

// v10
if (await isValidSsoDomain(input.value, AbortSignal.timeout(5_000))) {
await new AuthClient({ ssoDomain: input.value }).signIn();
}
// v11
const client = new AuthClient({ ssoDomain: input.value });
client.subscribe(() => render(client.getSsoStatus()));
render(client.getSsoStatus());
function render(sso) {
switch (sso.state) {
case 'checking':
return showSpinner();
case 'available':
return enableContinue(sso.name); // the organization's label, when it publishes one
case 'invalid':
return showNotADomain(sso.reason); // every problem with the value: the user has to change it
case 'unavailable':
return showUnavailable(sso.retryAfter, sso.reason); // a "Try again" countdown while retryAfter is set
}
}
continueButton.addEventListener('click', () => {
client.signIn().then(showApp, showSignInError); // no await before signIn(), or the popup is blocked
});

The answer comes from Internet Identity, which checks the whole configuration the sign-in uses, not only that the organization serves a file. Organizations no longer need to serve /.well-known/ii-openid-configuration with CORS headers for this check.

To check again, for a “Try again” button, call refreshSsoStatus(). When the user types a different domain, dispose of the previous client and build a new one.

A malformed ssoDomain no longer throws (breaking)

Section titled “A malformed ssoDomain no longer throws (breaking)”

new AuthClient({ ssoDomain }) used to throw when the value was not a domain. It now builds the client and reports { state: 'invalid', reason }, where reason names every problem with the value, so a client can be built from whatever the user typed. signIn() and requestAttributes() still open Internet Identity for such a client, which explains the error on its own screen. Setting both openIdProvider and ssoDomain still throws.

An ssoDomain must be a DNS name (breaking)

Section titled “An ssoDomain must be a DNS name (breaking)”

An ssoDomain is checked against the same rules Internet Identity applies, and one that breaks them now reports invalid instead of being accepted:

  • A port, such as acme.com:8443, is accepted only on a loopback host (localhost, 127.0.0.1, or a name under .localhost), for a local mock provider.
  • Every label is 1 to 63 letters, digits, or hyphens, with no hyphen at either end and no -- in its third and fourth places (punycode xn-- aside), so foo..com, -foo.com, foo_bar.com, and ab--cd.com are invalid.
  • A name has at least two labels and at most 253 characters.

A listener is now also called when a client built with ssoDomain gets an answer from Internet Identity. A listener that only reads getStatus() sees the same status as before.

The check calls app_sso_domain_check and app_sso_domain_status on the Internet Identity canister, through the same identityProvider and agentOptions the client mints with. A local Internet Identity that does not have these methods leaves the status at checking.