Single Sign-On (SSO)¶

Connect GxPSign to your organization's identity provider (IdP) so users sign in with their existing corporate credentials.

GxPSign supports two protocols:

Before You Start¶

You need three things in place:

1. Your email domain is set on the organization. Go to Settings > Organization > Edit and fill in the Domain field (e.g. acme.com). This is what routes your users to SSO at login — without it, the SSO button never appears.
2. Admin access to your identity provider, so you can create an application and copy its client credentials.
3. Your users are invited to GxPSign first. See the warning below.

How Your Users Sign In¶

Your users don't need a special link — the normal login page routes them automatically:

1. The user enters their email address at Sign In.
2. When they tab out of the field, GxPSign matches the email's domain against your organization's Domain and, if SSO is enabled, swaps in a Sign in with your provider name button.
3. Clicking it sends them to your IdP, and your IdP returns them to GxPSign, signed in.

If you have enforced SSO, a user who tries an email + password sign-in instead is stopped with "Your organization requires Single Sign-On. Please use the SSO login," and the SSO button is shown to them.

The SSO Login URL¶

Once SSO is enabled, the SSO page also shows an SSO Login URL you can copy and share — from your intranet, a bookmark, or a welcome email:

https://gxpsign.app/sso/start/your-org-slug/

Opening it skips the email step and goes straight to your IdP. It's a convenience, not a requirement: the email-domain routing above works whether or not anyone uses this link.

Setting Up OIDC¶

Step 1 — Copy your Redirect URI¶

Go to Settings > SSO. Select OpenID Connect (OIDC) as the active protocol. In the Configure SSO Provider panel, an amber box shows Configure this Redirect URI in your Identity Provider. Copy that value. It looks like:

https://gxpsign.app/sso/oidc/callback/your-org-slug/

Your IdP will reject the login if this does not match exactly — including the trailing slash and https://.

Step 2 — Create the application in your IdP¶

Create a web application (also called a confidential client or regular web app — not a single-page app, not a native/mobile app) and paste the Redirect URI from Step 1 into it. See Provider-Specific Setup below for the exact menu path for your IdP.

Collect three values:

• The Issuer URL
• The Client ID
• The Client Secret

Step 3 — Fill in the GxPSign form¶

Back on Settings > SSO:

Click Save.

Step 4 — Test the connection¶

Click Test Connection. This fetches your issuer's discovery document and verifies GxPSign can reach your IdP.

Step 5 — Enable SSO¶

The Enable SSO button stays locked until the connection has tested successfully. Once it passes, click Enable SSO. The login page will now offer the SSO button to anyone whose email matches your organization's domain.

Sign in yourself, from a private/incognito window, before telling your users about it.

Step 6 — Enforce SSO (optional)¶

Click Enforce SSO to disable password sign-in for your organization. Users must then authenticate through your IdP.

Using the Well-Known Endpoint¶

OIDC providers publish a discovery document — a machine-readable JSON file listing every URL and capability of the provider. It always lives at the issuer URL plus /.well-known/openid-configuration:

https://<your-issuer>/.well-known/openid-configuration

This is why you can leave the four endpoint fields blank. Give GxPSign the Oidc issuer and it reads the rest from that document at login time — so your configuration also keeps working if your IdP moves an endpoint later.

Checking it yourself¶

If setup misbehaves, fetch the document directly. Anything the browser can reach, you can check:

curl -s https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration | jq

You should get JSON containing at minimum:

{
  "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
  "authorization_endpoint": "...",
  "token_endpoint": "...",
  "userinfo_endpoint": "...",
  "jwks_uri": "..."
}

Two things to check:

• You get JSON, not a 404 or an HTML login page. A 404 almost always means the issuer URL is wrong — a missing path segment, an extra trailing slash, or the wrong tenant/realm ID.
• The issuer value in the JSON matches what you typed, character for character. If your IdP reports a different issuer than the one you configured, token validation will fail at login. Copy the value from the document into the Oidc issuer field.

Filling the endpoints manually¶

Discovery is the recommended path. Fill the endpoints in by hand only if your IdP does not publish a discovery document, or it sits behind a network path GxPSign cannot reach. Copy each value from the JSON into its matching field:

Manual endpoints override discovery. If you fill them in, you own keeping them current.

Provider-Specific Setup¶

Replace the placeholders in angle brackets with your own values. In every case, the Redirect URI you paste is the one from Step 1.

Troubleshooting¶

What GxPSign Reads From Your IdP¶

With the default openid email profile scopes:

SAML 2.0¶

Use SAML only where OIDC isn't an option — it has no discovery equivalent, so every value is entered by hand.

On Settings > SSO, select SAML 2.0 as the active protocol. The info box gives you two URLs for your IdP:

Then fill in, from your IdP:

GxPSign requests the NameID format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress and reads the email, firstName, and lastName attributes. If your IdP emits different attribute names, map them:

{
  "email": "urn:oid:0.9.2342.19200300.100.1.3",
  "firstName": "urn:oid:2.5.4.42",
  "lastName": "urn:oid:2.5.4.4"
}

There is no metadata import — GxPSign cannot pull your IdP's settings from a metadata URL. Test and enable exactly as with OIDC.

Related¶

• Managing Users — invite users before pointing them at SSO
• Organization Setup — set your email domain
• Require passkey to sign — SSO step-up at signing time