Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mgpass.net/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

mgPass provides Single Sign-On (SSO) so users authenticate once and are automatically recognized across all connected applications. There are two SSO mechanisms depending on whether the application shares the .mgpass.net domain.
MechanismWhen to useHow it works
Same-domain SSOApps on *.mgpass.netShared session cookie on .mgpass.net
Cross-domain SSOPartner sites on other domainsFedCM (browser-native identity federation)

​
Same-Domain SSO

All mgPass properties share the .mgpass.net parent domain:
  • auth.mgpass.net — authentication server
  • admin.mgpass.net — admin console
  • mgpass.net — user account portal
When a user authenticates, the auth-worker sets a mgpass_session cookie on the .mgpass.net domain. Because all mgPass properties are subdomains, the cookie is sent with every request automatically.

​
How It Works

1

User signs in

The user authenticates on any mgPass surface (e.g. the account portal at mgpass.net). The auth-worker sets the mgpass_session cookie on .mgpass.net.
2

User visits another mgPass property

The user navigates to admin.mgpass.net. The session guard detects no local session.
3

Silent authorization

The session guard auto-redirects to auth.mgpass.net/authorize?prompt=none. Because the browser sends the shared .mgpass.net cookie, the auth-worker finds the active session.
4

Code issued silently

The auth-worker issues an authorization code and redirects back to admin.mgpass.net. No login UI is shown.
5

Token exchange

The admin app exchanges the authorization code for tokens. The user is logged in instantly.
Same-domain SSO is completely transparent to the user. The entire redirect chain happens in milliseconds and no login screen is ever displayed.
PropertyValue
Cookie namemgpass_session
Domain.mgpass.net
Lifetime30 days (sliding window)
HttpOnlyYes
SecureYes
SameSiteLax
Every time the session is used for SSO (visiting any mgPass property), the 30-day expiry resets. Active users effectively never need to re-authenticate.

​
Cross-Domain SSO

Applications on different domains (your apps, partner sites) cannot share cookies with .mgpass.net. For these, mgPass uses FedCM (Federated Credential Management) — a browser-native API where the browser itself mediates the identity check. No iframes, no third-party cookies, no custom UI.

​
How It Works

1

Request credentials

Your site calls navigator.credentials.get() with the mgPass FedCM configuration (or loads the mgPass SDK which does this automatically).
2

Browser checks session

The browser calls auth.mgpass.net/fedcm/accounts with first-party cookies. This happens in the browser’s internal network stack — no JavaScript or iframes are involved.
3

Native prompt shown

If the user has an active mgPass session, the browser displays a native account picker showing the user’s name, email, and avatar. If no session exists, nothing happens.
4

User consents

The user clicks “Continue” on the native browser prompt.
5

Token issued and delivered

The browser calls auth.mgpass.net/fedcm/assertion, which issues a signed JWT token. The browser passes the token back to your site’s JavaScript callback. Your site sends the token to your backend for verification.
FedCM works without third-party cookies and is not affected by browser privacy features like Safari ITP or Firefox ETP. The browser mediates the entire flow — your site never communicates directly with the identity provider during the credential check.
For full integration instructions, see the FedCM Integration Guide.

​
Global Logout

When a user logs out from any mgPass surface, all sessions are destroyed everywhere. This is a security guarantee — there is no way to log out of a single app while remaining logged in elsewhere.

​
What Happens

1

User triggers logout

The user clicks “Log out” on any connected application (admin console, account portal, or a partner app).
2

Redirect to auth-worker

The application redirects to auth.mgpass.net/logout with an id_token_hint parameter.
3

Session cookie cleared

The auth-worker clears the shared mgpass_session cookie on .mgpass.net.
4

All sessions revoked

All active sessions for the user are revoked in the D1 database.
5

All refresh tokens revoked

Every refresh token issued to the user is invalidated.
6

Back-channel logout

The auth-worker calls the admin and account workers via Cloudflare service bindings to destroy their local sessions immediately.
7

User redirected

The user is redirected to the post_logout_redirect_uri.

​
Implementing Logout

Redirect the user to the mgPass logout endpoint: 
GET https://auth.mgpass.net/logout?
  id_token_hint=USER_ID_TOKEN
  &post_logout_redirect_uri=https://yourapp.com
ParameterRequiredDescription
id_token_hintRecommendedThe user’s ID token. Helps mgPass identify the session without relying on cookies. Expired tokens are accepted (per OIDC spec).
post_logout_redirect_uriOptionalWhere to redirect after logout. Must be registered in your application’s post_logout_uris.
function logout(idToken) {
  const params = new URLSearchParams({
    id_token_hint: idToken,
    post_logout_redirect_uri: window.location.origin,
  });
  window.location.href =
    `https://auth.mgpass.net/logout?${params}`;
}
After global logout, the user must re-authenticate on every application. This is by design for security — a single logout action provides complete session termination across all connected properties.

​
Session Lifetime

mgPass sessions use a 30-day sliding window:
SettingValue
Default session duration30 days
Sliding windowEvery SSO use (silent auth, token refresh) extends the session by 30 days
”Remember me” checkedPersistent cookie with 30-day expiry (survives browser restart)
“Remember me” uncheckedSession cookie (cleared when browser closes)
The mgPass login form includes a “Remember me for 30 days” checkbox:
  • Checked (default): Sets a persistent cookie. The user stays logged in across browser restarts and the 30-day window resets on every use.
  • Unchecked: Sets a session cookie. Closing the browser ends the session regardless of the 30-day window.
Active users who interact with any mgPass-connected application at least once every 30 days will never need to re-authenticate.

​
Best Practices

For cross-domain SSO, use the FedCM integration (via the mgPass SDK or the direct browser API). The browser handles the session check and user prompt natively — no iframes, no third-party cookies, no custom UI needed.
Your OAuth callback handler must handle three outcomes: code (success), error=login_required (no session), and error=consent_required (first-time app). Missing any of these causes a broken experience.
Save the id_token from the token exchange response. You need it for the id_token_hint parameter during logout. Expired tokens are accepted, so you do not need to keep a fresh one.
Configure your application’s post_logout_redirect_uris in the mgPass admin console. Without this, the user sees a generic “logged out” page instead of being redirected back to your app.

​
Next Steps