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
- At your identity provider, register a web application that uses the authorisation code flow.
- Register the redirect address below with it. The console shows it as Register this redirect address with your identity provider.
- In Nullgap, choose the OpenID Connect protocol and enter the three values in the table below.
- Fill in the settings both protocols share and save.
- Choose Test connection.
- Verify each domain, then switch Single sign-on is on.
The redirect address:
$NULLGAP_URL/api/auth/sso/callback
| Console field | API field | What to enter |
|---|---|---|
| Issuer | issuer | The https:// address of your identity provider. Its discovery document is read from there |
| Client ID | clientId | The client ID the provider gave the application |
| Client secret | clientSecret | The 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
- At your identity provider, add Nullgap as a SAML 2.0 application.
- Give the provider the values under what to enter at the identity provider. Many providers can read all of them from the metadata URL.
- In Nullgap, choose the SAML 2.0 protocol and give the provider's details, by pasting its metadata or by hand.
- Fill in the settings both protocols share and save.
- Choose Test connection.
- Verify each domain, then switch Single sign-on is on.
- 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 label | API field (under saml.sp) | Value | Your provider may call it |
|---|---|---|---|
| Metadata URL | metadataUrl | $NULLGAP_URL/api/auth/saml/metadata/ followed by your organisation's id | Service provider metadata |
| Entity ID (audience) | entityId | The same address as the metadata URL | Audience, identifier, SP entity ID |
| Assertion Consumer Service URL | acsUrl | $NULLGAP_URL/api/auth/saml/acs | Reply URL, ACS URL, single sign-on URL |
Also set, at the provider:
| Setting | Value |
|---|---|
| Name ID | The person's e-mail address, in the e-mail address format |
| Signature | Sign the assertion or the whole response |
| Assertion encryption | Off |
#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 field | API field | What to enter |
|---|---|---|
| Identity provider entity ID | samlIdpEntityId | The provider's entity ID. It is the Issuer of every sign-in it sends |
| Sign-in URL | samlIdpSsoUrl | The provider's single sign-on address for the HTTP-Redirect binding. Must be https |
| Signing certificate | samlCertificates | The 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 supported | What 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 assertions | Turn assertion encryption off at the provider. The connection is already TLS |
| SHA-1 signatures | Use RSA or ECDSA with SHA-256 or SHA-512 |
| Inclusive canonicalisation | Use exclusive canonicalisation, which is the usual default |
| Single logout | Signing out of Nullgap does not sign you out of the provider, and the other way round |
| Fetching provider metadata from a URL | Paste 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 field | API field | Meaning |
|---|---|---|
| Allowed email domains | allowedDomains | Only 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 members | defaultRole | member 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 on | enabled | Switch off to pause SSO without losing the set-up. Needs the protocol's details and at least one allowed domain |
| Require single sign-on | requireSso | See below |
| Accept emails the provider has not marked as verified | trustUnverifiedEmail | OIDC 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.
| Protocol | What it checks | A pass says |
|---|---|---|
| OIDC | Fetches the provider's discovery document from the issuer | "The identity provider answered and its configuration is valid." |
| SAML | That 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_firstotherwise); - your own account must have a second factor (
enrol_firstotherwise).
#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 may | It may not |
|---|---|
| Open the organisation whose identity provider issued it | Open any other organisation, even one the account is a member of |
| Do everything the member's role allows there | Change 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 policy | Create 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 happens | Likely cause | What to do |
|---|---|---|
Sign-in page with error=sso_domain | The address is not on an allowed domain | Add the domain, or have the person use an address on a listed one |
Sign-in page with error=sso_domain_unverified | The domain is listed but not verified, or its verification lapsed | Verify the domain |
Sign-in page with error=sso_email | OIDC: the provider did not mark the address as verified. SAML: the assertion carries no e-mail address | OIDC: 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=sso | Anything 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 secret | Start 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 link | The organisation address is wrong, or single sign-on is off | Check the org value and the Single sign-on is on switch |
502 sso_unavailable on the sign-in link | OIDC: the provider's discovery document could not be fetched | Check 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 missing | Fill in all three |
400 when saving: "List at least one email domain that may sign in" | Turning SSO on with no allowed domain | Add a domain |
400 verify_domain_first | Requiring SSO before any domain is verified | Verify a domain first |
400 enrol_first | Requiring SSO from an account with no second factor | Set up a second factor on your own account |
403 step_up_required | The change needs a fresh second-factor check | Confirm 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