Skip to main content

SSO — SAML identity providers

If your organization runs an enterprise identity provider — Okta, ADFS, OneLogin, Shibboleth, an internal IdP — you can wire it into GreekManage so members sign in without a separate password. This page walks the SAML 2.0 setup end-to-end: what to give your IdP, what to paste back into GreekManage, and how to test the connection before you turn it on.

Before you start​

Have these from your IdP admin (or your own IdP admin console):

  • The IdP entity ID — usually a URL like https://idp.example.com/saml/metadata
  • The SSO URL (also called the SingleSignOnService URL) — where GreekManage redirects users to sign in
  • Optionally an SLO URL (SingleLogoutService URL) — where GreekManage sends sign-out requests
  • The IdP's X.509 signing certificate — the PEM-encoded public certificate that signs SAML assertions. You'll paste this into GreekManage so it can verify responses.

You'll also need to know how your IdP releases identity claims — specifically which attributes carry the user's email, given name, and surname.

Create the identity provider​

  1. Open Org → Settings → Identity Providers.
  2. Click Add Provider.
  3. Fill out:
    • Name — a human label for this connection (e.g., "University SSO", "Acme Okta"). Members never see this directly; it's for your admin team.
    • Type — choose SAML.
    • Slug — a short URL-safe identifier (auto-generated from the name). The slug appears in your IdP-facing endpoint URLs and must be globally unique across GreekManage. Once you've pointed your IdP at these URLs, changing the slug breaks the connection — pick something stable on day one.
    • Allowed Domain (optional) — restrict sign-in to a specific email domain (e.g., example.edu). If a user authenticates successfully at the IdP but their email is on a different domain, GreekManage refuses the sign-in with a 403. Leave blank to accept any domain your IdP releases.
  4. Click Create. The provider is created in the inactive state — members can't use it yet. You'll flip it on after you finish wiring and testing.

Add Identity Provider dialog with Type set to SAML and slug + allowed-domain fields. Add Identity Provider dialog with Type set to SAML and slug + allowed-domain fields.

Give your IdP the endpoint URLs​

Now give your IdP team four pieces of data. All four URLs include the slug you just picked. Replace [your-app-domain] with the public hostname your members use (e.g., app.greekmanage.com) and [slug] with the slug.

What your IdP needsURL pattern
Service Provider metadata (XML)https://[your-app-domain]/api/auth/sso/saml/[slug]/metadata/
Assertion Consumer Service (ACS)https://[your-app-domain]/api/auth/sso/saml/[slug]/acs/
Single Logout Service (SLS)https://[your-app-domain]/api/auth/sso/saml/[slug]/sls/
Initiate (login) URLhttps://[your-app-domain]/api/auth/sso/saml/[slug]/login/

Most IdPs accept the metadata URL and read everything else from it automatically. If your IdP doesn't support metadata import, paste the ACS URL by hand.

Binding choices:

  • ACS (IdP → GreekManage): HTTP-POST. The IdP posts the signed SAML response to the ACS URL.
  • SSO (GreekManage → IdP): HTTP-Redirect. GreekManage sends the user to your SSO URL with a redirect.
  • SLS: HTTP-Redirect.

The NameID format GreekManage requests is emailAddress — the user's primary identifier is their email. Your IdP should release the user's primary email as the NameID value (or in an attribute statement you map below).

Paste the IdP details into GreekManage​

Back in Identity Providers, find the SAML provider you just created and click the pencil icon to open its config form. Fill in:

  • IdP Entity ID — the IdP's entity ID URL.
  • SSO URL — the IdP's SingleSignOnService URL.
  • SLO URL — optional. Leave blank if your IdP doesn't support Single Logout.
  • X.509 Certificate — paste the full PEM, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. The certificate is stored encrypted at rest. If you ever re-paste a new certificate (e.g., rotating after expiry), it replaces the old one.
  • SP Entity ID — leave blank to auto-generate from your metadata URL. Set this only if your IdP requires a specific entity ID different from the metadata URL.

Click Save SAML Configuration.

SAML config form with all fields filled in SAML config form with all fields filled in

Attribute mapping (optional)​

By default, GreekManage reads three SAML attributes using the standard OID-based claim URIs:

User fieldDefault SAML attribute
Emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
First namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

If your IdP releases different attribute names (e.g., mail, givenName, sn), override them in the attribute mapping config. If your IdP doesn't release an email attribute at all, GreekManage falls back to the NameID — which works as long as the NameID itself is an email address.

Test the connection​

After saving, click the test tube icon next to the provider in the list. GreekManage validates that:

  • The SAML configuration record exists and has all required fields
  • A valid SP metadata document can be generated from your settings

This is a static config check — it does not initiate a live SAML flow against your IdP. To verify the live flow, flip the provider to active (the toggle next to its name), open a private/incognito browser window, and sign in by selecting your IdP on the GreekManage sign-in page. On success the user lands on the dashboard.

Turn the provider on​

Once the live flow works, leave the Active toggle on. The provider now appears as a sign-in option for members whose email domain matches your allowed domain (or for everyone, if you didn't set an allowed domain). When a member signs in via your IdP for the first time, GreekManage looks up an existing user by email and links the SSO subject to that account. GreekManage does not auto-create accounts from SAML sign-ins — the user must already exist in your organization. New members are added through the normal member onboarding or PNM intake flows.

Common failure modes​

"SAML response error: invalid_response" or signature mismatch The certificate in GreekManage doesn't match the one your IdP is signing with. Either you pasted a different cert, the cert was rotated on the IdP side, or the cert is expired. Re-export the current signing cert from your IdP and re-paste it.

"SAML authentication failed" The IdP returned a response, but it failed validation — usually a clock skew between servers, an unexpected audience restriction, or a NameID format mismatch. Check your IdP logs for the assertion it sent and verify the audience is set to your SP entity ID.

"Email domain must be example.edu" The user authenticated, but their email is on a different domain than the Allowed Domain you set on the provider. Either widen the allowed domain or leave it blank.

"No email in user info response" / blank email on the new SSO user Your IdP isn't releasing an email attribute and the NameID isn't an email either. Configure the IdP to release the user's primary email in the standard email claim, or override the email attribute in GreekManage's attribute mapping to whatever your IdP releases.

Member sees "No account found" after IdP sign-in The IdP authenticated them, but no GreekManage user exists with that email. Confirm the user is a member of a chapter in your org. If their primary email at the IdP differs from their GreekManage email, add the IdP's email as an additional verified email on their profile — multi-email auth will match it.

Disabling the provider​

Toggle Active off and the SAML option disappears from the sign-in page. Existing users who previously signed in via this IdP fall back to their other sign-in methods (password, passkey, OAuth). Deleting the provider entirely is also fine — it doesn't delete user accounts, only the IdP wiring.

Last verified against v0.62.1 (2026-05-10).