gigamcp/ docs

Single Sign-On (SAML / OIDC)

Gigamcp uses WorkOS SSO as the identity broker. Your IT team configures the integration once in a hosted Admin Portal; gigamcp only stores the resulting connection id.

Supported IdPs

  • Okta (SAML 2.0, OIDC)
  • Microsoft Entra ID / Azure AD (SAML 2.0, OIDC)
  • Google Workspace (SAML 2.0)
  • OneLogin, JumpCloud, Ping, Auth0, Duo, Rippling (SAML 2.0)
  • Generic SAML 2.0 / OIDC for everyone else

Step-by-step

  1. Sign in to gigamcp as a workspace owner or admin.
  2. Open Enterprise → Single Sign-On.
  3. Press Configure SAML / OIDC. We open the WorkOS Admin Portal in a new tab using a one-time link (valid for 7 days).
  4. The Admin Portal walks your IT team through the IdP-specific steps:
    • Okta — assign the "WorkOS" app, copy the metadata URL.
    • Azure AD — register the enterprise app, paste the SAML response signing certificate.
    • Google Workspace — create a SAML app, paste the IdP metadata XML.
  5. When the Admin Portal reports Connected, return to gigamcp. The connection id (conn_…) is now visible in WorkOS; paste it into the SSO connection id field on this page and press Save.
  6. Optionally tick Require SSO for every member. With this toggle on, password and Google OAuth logins are rejected for any user whose email matches one of your verified domains.

Testing

From an incognito window, go to https://app.gigamcp.io/login, enter an IdP-managed email, and press Continue with SSO. You should be redirected to your IdP, sign in, and land back on /app.

Routing rules

  • Users whose email domain matches a domain you've verified in WorkOS are routed to your IdP.
  • Service Provider-initiated flows hit /api/auth/sso/initiate?email=… on the gigamcp API; we look up the connection by domain and 302 to WorkOS.
  • Identity Provider-initiated flows post to the WorkOS ACS URL; the WorkOS callback issues a session cookie just like any other login.

Troubleshooting

  • Redirect loop after IdP sign-in — the most common cause is missing NameID or emailattribute in the SAML response. Check the WorkOS Admin Portal > Connection > Logs.
  • "Connection not found" — confirm the value pasted into SSO connection id exactly matches the WorkOS connection (it must start with conn_).
  • Old SSO sessions don't pick up new permissions — gigamcp re-checks group memberships on every request, but role changes require a re-login. Either wait 60 minutes for the cookie to expire or sign out and back in.

Disabling SSO

Press Disconnect on the SSO page. This clears the connection id; users can immediately sign in via password / Google OAuth again. The WorkOS connection itself remains until your IT team revokes it from the Admin Portal.