Skip to main content

​
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 domainsOne Tap SDK with hidden iframe

​
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 provides the One Tap SDK — a lightweight JavaScript SDK that checks for an active mgPass session using a hidden iframe.

​
How It Works

1

Embed the SDK

The partner site includes the One Tap SDK script tag. The SDK creates a hidden iframe pointing to auth.mgpass.net/onetap/check.
2

Iframe checks session

The iframe is on the auth.mgpass.net origin, so it CAN read the mgpass_session cookie. If a valid session exists, the iframe posts the user’s basic profile info (name, email, avatar) back to the parent page via postMessage.
3

Banner displayed

The SDK renders a floating “Continue as [Name]” banner in the bottom-right corner of the page. If no session exists, the SDK is completely invisible.
4

User clicks the banner

Clicking the banner starts an OAuth authorization flow with prompt=none. Because the session exists, the auth-worker issues an authorization code instantly.
5

Redirect and token exchange

The user is redirected to the partner’s redirect_uri with an authorization code. The partner exchanges the code for tokens and the user is logged in.
The One Tap SDK never exposes tokens, session IDs, or any sensitive data to the partner site. Only basic profile information (name, email, avatar) is shared via postMessage to render the banner.
For full integration instructions, see the One Tap SDK 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

Instead of manually implementing prompt=none redirects for cross-domain SSO, use the One Tap SDK. It handles the iframe session check, user prompt, and OAuth redirect automatically with a single script tag.
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

  • One Tap SDK — integrate cross-domain SSO with a single script tag
  • Token Refresh — keep users authenticated with automatic token renewal
  • OAuth Flows — full details on the authorization code flow
  • Applications — register your app to use SSO