Skip to main content

Authentication and tokens

Your application owns authentication. A SecureAuth Connect embedded component never runs an OAuth flow, never reads your page's storage, and never persists a token. It calls one function you supply, and uses what that function returns.

init({
deploymentUrl: "https://acp.example.com",
tenantId: "your-tenant",
serverId: "your-workspace",
tokenProvider: () => yourAuth.getFreshToken(),
variant: "account-center",
});

tokenProvider returns a string or a promise of one. Mount the element only once the person has a session: returning an empty string is an error, not a way to say "nobody is signed in".

The refresh contract​

The token you return is cached for the life of the page. When a request comes back 401, the element calls tokenProvider again, once, and retries with the result.

That second call has to return a renewed token. Handing back the one that just failed leaves the element unable to recover, and the person sees an error they cannot act on.

An expired session is page-wide, not per element: there is one tokenProvider per page, so every mounted element learns about it at the same moment.

Recent sign-in for sensitive changes​

Setting a password, a TOTP authenticator, or a passkey needs a sign-in from the last few minutes, not just a valid token. When the sign-in is older, the element asks the person to sign in again. It cannot do that itself, because your page owns the sign-in, so when they agree it raises sa-error with type: "reauthentication_required". The view stays as it was.

Handle it by sending the person through your sign-in again with a fresh authentication, for example prompt=login on the authorization request. Then make sure tokenProvider returns the new token, and they can retry the change.

document.addEventListener("sa-error", event => {
if (event.detail.type === "reauthentication_required") {
signInAgain({ prompt: "login" });
}
});

Unlike unauthorized, this does not mean the session ended, so do not sign the person out.

Where your token comes from​

The Embed tab writes the right shape into the snippet for you, based on how the client is registered. These are the three it writes.

A library in the browser​

For a single-page or mobile application using an OIDC library that can renew silently.

tokenProvider: async () => (await userManager.signinSilent()).access_token,

This is oidc-client-ts's own call. Another library works as well, as long as it exposes something equivalent: swapping the variable name is not enough if the interface differs.

An endpoint on your server​

For a server-rendered application, where the browser holds a session cookie and your server exchanges it for a token.

tokenProvider: async () => {
const res = await fetch("/api/access-token", { credentials: "include" });
if (!res.ok) throw new Error("not signed in");
return (await res.json()).access_token;
},

Your own code​

When you already keep the token after the authorization code exchange and refresh it yourself.

tokenProvider: () => yourAuth.getFreshToken(),

The method name carries the requirement. A getToken() that hands back a cached value turns the retry into a loop.

Scopes​

The elements read and write the signed-in person's own data through the self-service APIs, so the access token has to carry the scopes those APIs require, and the client it was issued to has to be allowed to request them.

The Embed tab derives the list from the elements the application places, and grants what is missing in one click. It includes the scopes of sections the variant hides: an element that cannot read its variant in time shows every section, so it still needs them. The reason it is derived rather than fixed is that over-granting is the usual failure mode: a list copied out of documentation gives an application access to data it never shows.

ScopeNeeded for
openid, profile, emailThe token itself, and the identity header on every pane.
view_ss_profileAny pane at all. Each one reads the signed-in person before it decides what to show.
manage_ss_profileEditing personal details, preferred language, and sign-in methods.
view_sessionsThe identity header's last sign-in row, and the sessions list.
manage_sessionsRevoking a session.
list_clients_with_accessThe privacy and applications panes.
revoke_client_accessWithdrawing an application's access on the privacy pane.
warning

Scopes are the real boundary. Hiding a section removes the UI and stops its requests, but the API stays reachable with that token. If data must not be readable, do not grant the scope.

What the element does not touch​

  • It does not read or write localStorage, sessionStorage, or cookies on your page.
  • It does not redirect, open a popup, or mount an iframe to renew anything.
  • It does not know your client ID or client secret. It only ever sees the token you hand it.

See also​