Developer guide (advanced)

The SSO handles signing in, but “who is signed in” is decided by your site's own session. The Client Secret lives only on your backend.

Sign-in in 7 steps

1. The user opens your siteBrowser

   Your site sees they are not signed in yet.

2. Send the user to the SSOYour backend

   Your backend (/auth/login) redirects the browser to the SSO with a random check value (state).

3. Find out who they areSSOMicrosoft

   The SSO checks whether they are already signed in; only if not, Microsoft asks for their work account and password.

4. Send the user back to your siteSSO

   The SSO redirects the browser to /auth/callback with a one-time “ticket” (code) and the same check value.

5. Exchange the ticket for the user's dataYour backend

   Your backend checks the check value, then trades “ticket + Client Secret” with the SSO for name, email, department and more. The browser never sees this step, so the secret stays safe.

6. Remember that they are signed inYour backend

   Your backend keeps the user in its own session. Every later request just checks the session — no need to ask the SSO again.

7. The page shows the name and photoBrowser

   advantech-sso.js calls your /auth/me to get the current user and displays it.

What the user actually sees: open the site → (the first time) the Microsoft sign-in screen → back on the site. Everything else happens automatically in milliseconds.

On the SSO (done by an SSO administrator or service owner)

On your server

# .env (never commit this file)
SSO_CLIENT_ID=svc_xxxxxxxx
SSO_CLIENT_SECRET=xxxxxxxx
APP_URL=https://myapp.advantech.world
SESSION_SECRET=<64 random characters: openssl rand -hex 32>

Reference these by URL or download them to your own site. The URLs are stable and will not be renamed.

Front end (HTML / CSS / JS)

In production consider hosting the JS / CSS yourself so SSO maintenance never affects your pages; referencing them directly always gives the latest version.

Backend samples

The backend needs no SSO-specific package — only each language's standard HTTP and session features (Flask, Express, PHP curl, ASP.NET Core, Spring Boot, Go standard library).

SSO APIs

Add prompt to /authorize to decide whether the user sees any screen this time and whether the password is asked again. The starters' /auth/login?silent=1 is prompt=none.

• Other values (e.g. consent) are ignored, as if not set.
• After a user signs out, the SSO uses select_account automatically for their next sign-in so they don't silently get the same account back.
• login_required / access_denied come back to your callback as errors only with prompt=none; otherwise the user deals with it on the SSO's or Microsoft's screen.

# No screen — only try whether automatic sign-in works
https://ae-sso.advantech.com/authorize?client_id=svc_xxxxxxxx&redirect_uri=…&response_type=code&state=RANDOM&prompt=none

# Force the password again
https://ae-sso.advantech.com/authorize?client_id=svc_xxxxxxxx&redirect_uri=…&response_type=code&state=RANDOM&prompt=login

# Add prompt in the starter's /auth/login
q["prompt"] = "login"                      # Python  (/auth/login)
q.set("prompt", "login");                  // Node.js
$q['prompt'] = 'login';                    // PHP

Parameters of the logout URL (/logout)

The SSO and the front-end kit handle most of the work; the rest must live in your backend, because only your server can hold the Client Secret and decide who may do what.

• SSO provides Nothing to do.
• Front-end kit provides Just reference the files.
• You build (starter has it) Must exist in your backend; the starters already contain it — use it or adapt it.
• You must build No starter can decide this for you; build it for your business rules.

• The production Redirect URI is registered and matches APP_URL.
• The site uses https; the session cookie is HttpOnly + Secure + SameSite=Lax.
• The Client Secret and session key are only in environment variables / a secret store, not in Git.
• Sessions are stored in Redis or a database (survive restarts and several servers).
• Every page and API that needs sign-in checks the session on the backend; authorization rules run on the backend.
• The service's data permissions allow only needed fields; an allowlist is set if needed.
• Everything in “Something went wrong?” was tested: signed out, no access, sign-out, reload, two tabs signing in at once.
• Sites with a CSP include the SSO address; you decided whether production references or hosts the JS / CSS.