Skip to main content

​
Overview

The mgPass One Tap SDK enables cross-domain SSO for partner sites. If your users have an active mgPass session, the SDK displays a floating “Continue as [Name]” banner that lets them sign in with a single click — no password, no redirect chain, no friction. If no mgPass session exists, the SDK is completely invisible. It adds no UI, no prompts, and no overhead.

One script tag

Add a single <script> tag and call mgpass.onetap() with your client ID.

Zero friction

Users click once to authenticate. No login form, no password entry.

Privacy-first

No tokens or session IDs are exposed. Only basic profile info is shared.

Invisible when inactive

If the user has no mgPass session, nothing is shown. Your page is unaffected.

​
Quick Start

Add the SDK to any page where you want to offer One Tap sign-in: 
<script src="https://auth.mgpass.net/sdk/onetap.js"></script>
<script>
  mgpass.onetap({
    client_id: 'your_client_id',
    redirect_uri: 'https://yoursite.com/callback',
    scope: 'openid profile email'
  });
</script>
That is the complete integration. The SDK handles everything else: session detection, banner rendering, and the OAuth redirect.

​
Configuration Options

OptionTypeRequiredDefaultDescription
client_idstringYes—Your OAuth client ID from the mgPass admin console
redirect_uristringYes—Where to redirect after authentication. Must be registered in your app’s allowed redirect URIs.
scopestringNoopenid profile emailOAuth scopes to request
<script src="https://auth.mgpass.net/sdk/onetap.js"></script>
<script>
  mgpass.onetap({
    client_id: 'your_client_id',
    redirect_uri: 'https://yoursite.com/callback'
  });
</script>

​
How It Works

1

SDK loads

The onetap.js script loads and registers the mgpass.onetap() function on the global mgpass object.
2

Hidden iframe created

The SDK creates a hidden iframe pointing to auth.mgpass.net/onetap/check. Because the iframe is on the auth.mgpass.net origin, it can read the mgpass_session cookie (same-origin policy).
3

Session check

Inside the iframe, JavaScript checks for the mgpass_session cookie and validates the session. A 5-second timeout is enforced — if the iframe does not respond, it is cleaned up silently.
4

Result posted to parent

The iframe posts the result to the parent page via postMessage:
  • Session found: { authenticated: true, user: { name, email, avatar } }
  • No session: { authenticated: false }
5

Banner shown (if session exists)

If an active session was found, the SDK renders a floating banner in the bottom-right corner displaying the user’s name, email, and avatar with a “Continue as [Name]” call to action.
6

User clicks the banner

Clicking the banner redirects to auth.mgpass.net/authorize with prompt=none and the configured client_id, redirect_uri, and scope. Because the session exists, the auth-worker issues an authorization code instantly.
7

Token exchange

The user lands on your redirect_uri with an authorization code. Your server exchanges the code for access and ID tokens via the /api/token endpoint.
The One Tap banner appears in the bottom-right corner of the page with a slide-in animation.

​
What the banner shows

  • User’s avatar (or initials fallback)
  • User’s display name
  • User’s email address
  • “Continue as [Name]” button
  • Close button (X) in the top-right corner
  • “Secured by mgPass” branding at the bottom

​
Dismiss behavior

  • Clicking the X button dismisses the banner for the current browser session (tracked in sessionStorage).
  • Navigating to a new page on your site where the SDK is loaded will not re-show the banner if the user dismissed it.
  • Closing and reopening the browser clears sessionStorage, so the banner will appear again on the next visit.

​
When nothing is shown

The SDK is completely invisible when:
  • No active mgPass session exists
  • The user previously dismissed the banner (current browser session)
  • The iframe times out after 5 seconds (network issues)

​
Security

The hidden iframe uses allow-same-origin allow-scripts sandbox attributes. It cannot navigate the parent page, submit forms, or access parent DOM.
The SDK verifies that every postMessage event originates from auth.mgpass.net. Messages from any other origin are ignored.
The iframe only sends basic profile information (name, email, avatar) to the parent page. Tokens, session IDs, and cookies are never exposed to the partner site.
User data is passed via postMessage, not URL parameters. Nothing is exposed in browser history, server logs, or referrer headers.
The iframe has a 5-second timeout. If no response is received (e.g. the user has third-party cookies blocked), the iframe is removed from the DOM silently.

​
Advanced Usage

​
Programmatic Dismiss

You can hide the banner programmatically (e.g. when the user starts interacting with your own login form): 
mgpass.dismissOnetap();
This has the same effect as clicking the X button — the banner is hidden and will not reappear for the current browser session.

​
Handling the Callback

After the user clicks the banner and completes the OAuth flow, they arrive at your redirect_uri with an authorization code: 
https://yoursite.com/callback?code=AUTH_CODE&state=RANDOM_STATE
Exchange the code for tokens on your server: 
app.get('/callback', async (req, res) => {
  const { code } = req.query;

  const tokenResponse = await fetch('https://auth.mgpass.net/api/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: 'https://yoursite.com/callback',
      client_id: 'your_client_id',
      client_secret: 'your_client_secret',
    }),
  });

  const tokens = await tokenResponse.json();
  // tokens.access_token, tokens.id_token, tokens.refresh_token

  // Create a local session for the user
  req.session.user = tokens;
  res.redirect('/');
});

​
Styling

The banner uses inline styles with fixed positioning. It does not interfere with your page layout or existing CSS.
PropertyValue
PositionFixed, bottom-right corner
Z-index999999
Width360px
AnimationSlide-in from bottom
ShadowSubtle drop shadow
The banner is self-contained and does not inject any global CSS. Your stylesheets will not affect it, and it will not affect yours.

​
Browser Support

The One Tap SDK works in all modern browsers that support:
  • postMessage API
  • sessionStorage
  • <iframe> with sandbox attributes
This includes Chrome, Firefox, Safari, and Edge (all current versions).
Browsers with aggressive third-party cookie blocking (e.g. Safari ITP, Firefox ETP) may prevent the iframe from reading the mgpass_session cookie. In these cases, the SDK silently falls back to showing nothing. Users can still sign in using the standard OAuth flow.

​
Next Steps

  • SSO Guide — understand same-domain and cross-domain SSO architecture
  • OAuth Flows — full details on the authorization code flow
  • Token Refresh — keep users authenticated with automatic token renewal