Nullgap.dev Docs

Administration

Single sign-on

Let your people sign in to Nullgap through your identity provider, with OpenID Connect or SAML 2.0.

Single sign-on (SSO) sends your people to your own identity provider to sign in. Nullgap supports OpenID Connect (OIDC) and SAML 2.0. An organisation has one identity provider at a time.

#Before you start

  • You must be an owner. Admins can see the set-up but not change it.
  • Saving or removing the set-up asks for a fresh second-factor check if your account has a second factor. See the step-up check. An API key cannot change single sign-on.
  • You need access to your domain's DNS. An e-mail domain works for sign-in only after you have verified it.
  • You need to be able to register an application at your identity provider.

In the console the set-up is under Settings, Access, Single sign-on.

#How sign-in works afterwards

Your people start at the sign-in link the console shows:

$NULLGAP_URL/api/auth/sso/start?org=acme

Nullgap sends the browser to your identity provider, checks what comes back, and signs the person in. Someone who signs in for the first time with an address on a verified domain becomes a member automatically, with the role you chose for new members.

Both protocols are started by Nullgap. Put the sign-in link behind the application tile at your identity provider, not the provider's own "launch" link.

#Set up OIDC

  1. At your identity provider, register a web application that uses the authorisation code flow.
  2. Register the redirect address below with it. The console shows it as Register this redirect address with your identity provider.
  3. In Nullgap, choose the OpenID Connect protocol and enter the three values in the table below.
  4. Fill in the settings both protocols share and save.
  5. Choose Test connection.
  6. Verify each domain, then switch Single sign-on is on.

The redirect address:

$NULLGAP_URL/api/auth/sso/callback
Console fieldAPI fieldWhat to enter
IssuerissuerThe https:// address of your identity provider. Its discovery document is read from there
Client IDclientIdThe client ID the provider gave the application
Client secretclientSecretThe client secret. It is stored encrypted and never shown again; the API only reports hasClientSecret

Nullgap asks the provider for an ID token and reads the person's address from its email claim. The token must carry email_verified as true, unless you switch on Accept emails the provider has not marked as verified (trustUnverifiedEmail). The display name comes from name, or preferred_username if there is no name.

#Set up SAML

  1. At your identity provider, add Nullgap as a SAML 2.0 application.
  2. Give the provider the values under what to enter at the identity provider. Many providers can read all of them from the metadata URL.
  3. In Nullgap, choose the SAML 2.0 protocol and give the provider's details, by pasting its metadata or by hand.
  4. Fill in the settings both protocols share and save.
  5. Choose Test connection.
  6. Verify each domain, then switch Single sign-on is on.
  7. Sign in once through the sign-in link to confirm the whole round trip.

#What to enter at the identity provider

The console shows these under How your identity provider connects.

Console labelAPI field (under saml.sp)ValueYour provider may call it
Metadata URLmetadataUrl$NULLGAP_URL/api/auth/saml/metadata/ followed by your organisation's idService provider metadata
Entity ID (audience)entityIdThe same address as the metadata URLAudience, identifier, SP entity ID
Assertion Consumer Service URLacsUrl$NULLGAP_URL/api/auth/saml/acsReply URL, ACS URL, single sign-on URL

Also set, at the provider:

SettingValue
Name IDThe person's e-mail address, in the e-mail address format
SignatureSign the assertion or the whole response
Assertion encryptionOff

#The identity provider's details

Give them in one of two ways.

Paste metadata XML (samlMetadataXml): paste the provider's metadata document. Nullgap reads the entity ID, the sign-in URL and the signing certificates from it. Nullgap never fetches metadata from an address; you paste the document.

Enter by hand:

Console fieldAPI fieldWhat to enter
Identity provider entity IDsamlIdpEntityIdThe provider's entity ID. It is the Issuer of every sign-in it sends
Sign-in URLsamlIdpSsoUrlThe provider's single sign-on address for the HTTP-Redirect binding. Must be https
Signing certificatesamlCertificatesThe provider's signing certificate, in PEM form or as its bare base64 body. Up to three, each up to 8000 characters. An entry that is not an X.509 certificate is refused

If you send both in one request, the values entered by hand override what the metadata says.

Nullgap reads the person's address from an attribute named email, mail, emailaddress or user.email (the common URI forms of the e-mail claim are also recognised), and falls back to the NameID when that is an address. The display name comes from a displayName or name attribute, or from first and last name.

#Rotating the provider's certificate

Save both the old and the new certificate (up to three are kept). Either may sign. Remove the old one after your provider has switched. The console warns when a stored certificate is close to expiry or has expired.

#SAML limits

Not supportedWhat to do instead
Sign-in started at the identity provider (IdP-initiated)Every assertion must answer a request Nullgap made. Point the application tile at the sign-in link
Encrypted assertionsTurn assertion encryption off at the provider. The connection is already TLS
SHA-1 signaturesUse RSA or ECDSA with SHA-256 or SHA-512
Inclusive canonicalisationUse exclusive canonicalisation, which is the usual default
Single logoutSigning out of Nullgap does not sign you out of the provider, and the other way round
Fetching provider metadata from a URLPaste the XML

Other facts that help when a provider's settings are strict:

  • The sign-in request goes out with the HTTP-Redirect binding; the response comes back with HTTP-POST.
  • The response must be addressed to the entity ID and ACS URL above, and must arrive within 10 minutes of the request.
  • Clocks may differ by up to three minutes.
  • A response must contain exactly one assertion.

#Settings both protocols share

Console fieldAPI fieldMeaning
Allowed email domainsallowedDomainsOnly people whose address is on one of these domains can sign in through SSO. Up to 50. Each must be verified before it works. Public suffixes such as co.uk and single names are refused
Role for new membersdefaultRolemember or admin. Given to someone who joins by signing in for the first time, or who is added through SCIM. Nobody becomes an owner this way
Single sign-on is onenabledSwitch off to pause SSO without losing the set-up. Needs the protocol's details and at least one allowed domain
Require single sign-onrequireSsoSee below
Accept emails the provider has not marked as verifiedtrustUnverifiedEmailOIDC only. See the warning above

The protocol itself is the protocol field: oidc or saml. Switching protocol keeps both sets of details, so you can prepare one while the other is live.

#The test button

Test connection (POST /api/orgs/:org/sso/test) checks the saved set-up without signing anyone in.

ProtocolWhat it checksA pass says
OIDCFetches the provider's discovery document from the issuer"The identity provider answered and its configuration is valid."
SAMLThat the entity ID, sign-in URL and a certificate are stored, and that at least one certificate has not expired"The SAML settings are complete. Sign in through the identity provider once to confirm the whole round trip."

For SAML the test cannot prove that the provider accepts Nullgap's request or signs with the stored certificate. Only a real sign-in does.

#Requiring single sign-on

With requireSso on, a member can open the organisation only from a session that was started through your identity provider. Any other session gets 403 sso_required.

To switch it on:

  • single sign-on must be on;
  • at least one allowed domain must be verified (verify_domain_first otherwise);
  • your own account must have a second factor (enrol_first otherwise).

#The owner break-glass path

An owner whose account has a second factor (an authenticator app or a passkey) can still open the organisation after signing in another way, for example with a passkey or an e-mail link. This is deliberate: if your identity provider is down or misconfigured, an owner can get in and fix the set-up.

Keep at least two owners with a second factor, and check that each can sign in without the identity provider before you rely on it.

Admins and members have no such path.

#What a single sign-on session may do

A session started through your identity provider is trusted inside your organisation only, because the provider is yours and vouches only for your people.

It mayIt may not
Open the organisation whose identity provider issued itOpen any other organisation, even one the account is a member of
Do everything the member's role allows thereChange the account itself: add or remove a passkey or an authenticator, rename the profile, link a code-host login, end other sessions
Meet the organisation's "require multi-factor sign-in" setting without a second factor in Nullgap, because your provider enforces its own policyCreate an organisation or accept an invitation
Pass a step-up check, if the account has a second factor

The refused actions answer 403 sso_session. To do them, sign in with an e-mail link or a passkey.

#When sessions end

Sessions that rested on the set-up end when the set-up changes:

  • switching single sign-on off, or removing it, ends every session it issued;
  • changing the protocol, the issuer or the SAML entity ID ends every session it issued;
  • removing a domain from the list ends the sessions of people on that domain;
  • a domain whose verification lapses ends the sessions of people on that domain.

#Removing single sign-on

Remove deletes the set-up, gives up your verified domains, and ends the sessions it issued. Members go back to the other sign-in methods. Someone who only ever signed in through the identity provider needs another method to get back in. SCIM provisioning stops accepting users, because it depends on the allowed domains.

#Read the set-up through the API

An API key with the admin scope can read the set-up. Changing it is console-only.

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/sso"

The answer is null when nothing is set up. Otherwise it is the configuration, abridged here:

{
  "enabled": true,
  "protocol": "saml",
  "allowedDomains": ["acme.example"],
  "domainVerification": "dns",
  "defaultRole": "member",
  "requireSso": false,
  "loginUrl": "https://nullgap.acme.example/api/auth/sso/start?org=acme",
  "redirectUri": "https://nullgap.acme.example/api/auth/sso/callback",
  "saml": {
    "idpEntityId": "https://idp.acme.example/saml",
    "idpSsoUrl": "https://idp.acme.example/sso/saml",
    "certificates": [
      { "fingerprint": "3A:5C:...", "subject": "CN=idp.acme.example", "notAfter": "2027-06-01T00:00:00.000Z" }
    ],
    "sp": {
      "entityId": "https://nullgap.acme.example/api/auth/saml/metadata/org_7d3k",
      "acsUrl": "https://nullgap.acme.example/api/auth/saml/acs",
      "metadataUrl": "https://nullgap.acme.example/api/auth/saml/metadata/org_7d3k"
    }
  }
}

The full field list is in the single sign-on reference.

#Common errors

A failed sign-in sends the browser back to the sign-in page with a short reason. The cause is not shown to the person signing in. Each refused attempt is written to your audit log as auth.sso_failed.

What happensLikely causeWhat to do
Sign-in page with error=sso_domainThe address is not on an allowed domainAdd the domain, or have the person use an address on a listed one
Sign-in page with error=sso_domain_unverifiedThe domain is listed but not verified, or its verification lapsedVerify the domain
Sign-in page with error=sso_emailOIDC: the provider did not mark the address as verified. SAML: the assertion carries no e-mail addressOIDC: fix the claim at the provider, or see trustUnverifiedEmail. SAML: send the address as NameID or as an email attribute
Sign-in page with error=ssoAnything else: an expired or reused sign-in attempt, a sign-in started at the provider, a wrong audience or ACS URL, a signature made with a certificate that is not stored, an encrypted assertion, a wrong client secretStart again from the sign-in link. If it repeats, compare the provider's settings with the tables above and re-run the test
404 sso_not_available on the sign-in linkThe organisation address is wrong, or single sign-on is offCheck the org value and the Single sign-on is on switch
502 sso_unavailable on the sign-in linkOIDC: the provider's discovery document could not be fetchedCheck the issuer and that the provider is reachable from the internet
400 when saving: "issuer, clientId and clientSecret are needed..."Turning OIDC on with details missingFill in all three
400 when saving: "List at least one email domain that may sign in"Turning SSO on with no allowed domainAdd a domain
400 verify_domain_firstRequiring SSO before any domain is verifiedVerify a domain first
400 enrol_firstRequiring SSO from an account with no second factorSet up a second factor on your own account
403 step_up_requiredThe change needs a fresh second-factor checkConfirm with your authenticator code or passkey and save again

A sign-in attempt must finish in the browser that started it, within 10 minutes. Opening the sign-in link in one browser and finishing in another fails with error=sso.

Nullgap documentation