Skip to content

Setup flow

Single sign-on, LDAP and SCIM

How your team signs in to a self-hosted OneCamp: Google and GitHub, single sign-on with OIDC or SAML, an LDAP or Active Directory directory, and SCIM provisioning. Google and GitHub sign-in come with every licence, the free one included. OIDC, SAML, LDAP and SCIM come with a paid licence.

Every change below is made in your server's .env (in the install directory), then applied with:

make restart-api

That recreates only the API container, in seconds.

Who may join

Whatever the way in, someone becomes a member only when one of these is true:

  • they were invited (Admin → Invitations), and the invitation is still live: it hasn't been used and hasn't passed its expiry (a week by default);
  • their address is on the Sign-up allow-list (Admin → General);
  • they're already a member;
  • they sign in through single sign-on or the directory, which decide for themselves (see below).

The allow-list takes exact addresses (ana@acme.com) and whole Google Workspace domains (@acme.com). A domain entry admits only people signing in with Google, and only when Google says the account belongs to that Workspace domain. GitHub never admits by a domain entry, because anyone can add an address to a GitHub account. Public mail domains such as gmail.com or outlook.com can't be added.

Addresses are compared without regard to letter case. An address with characters outside plain ASCII is refused, so a look-alike can't reach someone else's account.

New members land in the workspace's default channels (#general until you choose others in Admin → General → Default channels), with the message box ready.

Google and GitHub

Add these redirect addresses to your OAuth app, with your API host in place of onecamp-backend.example.com:

https://onecamp-backend.example.com/oauth_callback/google
https://onecamp-backend.example.com/oauth_callback/github
  1. In Google Cloud Console (an OAuth client of type Web application) or GitHub (Settings → Developer settings → OAuth Apps), add the redirect address.
  2. In OneCamp, open Admin → Integrations → Sign-in providers, paste the client ID and secret, and save. No restart is needed.

OneCamp takes only addresses the provider has verified. From GitHub it takes any verified address on the account that the workspace knows (invited, allowed or a member), not only the primary one.

Single sign-on with OIDC

Works with Okta, Microsoft Entra ID, Google Workspace, Keycloak and any OpenID Connect provider. Create a web application in your provider with this redirect URI:

https://onecamp-backend.example.com/oauth_callback/oidc

Then set in .env and run make restart-api:

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://your-provider.example.com
OIDC_CLIENT_ID=...
OIDC_CLIENT_SECRET=...

Anyone your provider lets through gets an account on first sign-in, so limit who may use the app in your provider. Providers that send email_verified as text (Amazon Cognito among them) work.

Single sign-on with SAML

  1. Make SAML's certificate and key, once:

    make saml-cert

    It writes them to ./saml, which the shipped compose file mounts for the API, and keeps an existing pair (your identity provider holds a copy of the certificate). It works even when Docker created ./saml as root.

  2. In your identity provider, create a SAML app. OneCamp's metadata is at https://onecamp-backend.example.com/saml/metadata, and its sign-in reply address (ACS) is https://onecamp-backend.example.com/saml/acs.

  3. Set in .env, then make restart-api:

    SAML_ENABLED=true
SAML_IDP_METADATA_URL=https://your-idp.example.com/metadata

The certificate is published in OneCamp's metadata so your provider can encrypt what it sends; OneCamp's requests aren't signed.

LDAP and Active Directory

LDAP_ENABLED=true
LDAP_HOST=ldap.example.com
LDAP_PORT=636
LDAP_USE_TLS=true
LDAP_BIND_DN=cn=onecamp,ou=services,dc=example,dc=com
LDAP_BIND_PASSWORD=...
LDAP_BASE_DN=ou=people,dc=example,dc=com
LDAP_USER_FILTER=(&(objectClass=person)(|(uid=%s)(mail=%s)))
  • Your own certificate authority. Active Directory's certificate usually comes from the company's own authority. Put its PEM in ./ldap (mounted for the API) and set LDAP_CA_CERT=/app/ldap/<file>.pem. It's read at each sign-in, so a replaced file needs no restart.
  • Email addresses. Each entry needs mail or userPrincipalName. An entry with neither is refused, and the person is told to ask for one to be added.
  • Two-step sign-in is asked for after a directory password, as after an email password.
  • Anyone the filter finds gets an account on first sign-in; narrow the filter to a group if you need to, for example (&(objectClass=user)(memberOf=CN=OneCamp Users,OU=Groups,DC=example,DC=com)(sAMAccountName=%s)).

The _ENABLED and LDAP_USE_TLS switches accept true, 1, yes or on, in any case.

Admins from your directory

LDAP_ADMIN_GROUPS=OneCamp Admins, IT
SAML_ADMIN_GROUPS=OneCamp Admins
OIDC_ADMIN_GROUPS=onecamp-admins

Set the one for the way your team signs in. Name groups by their name or, for LDAP, their full DN, separated by commas. Someone in one of them becomes an admin when they sign in that way; a directory-managed admin taken out of them stops being one at their next directory sign-in. An admin made in OneCamp who also signs in through the directory is never demoted.

SCIM provisioning

Point your identity provider's SCIM app at https://onecamp-backend.example.com/scim/v2 with a SCIM token from Admin → Security.

  • Creating someone the workspace already knows from an import adopts that person, history and all, instead of failing or making a second account.
  • People created inactive (staged before their start date) aren't added to channels until they're activated.
  • Deactivating someone in your provider deactivates them in OneCamp.

Turning passwords off

With single sign-on or the directory in place, you can turn email passwords off:

AUTH_EMAIL_DISABLED=true

The sign-in page hides passwords and password sign-up is refused. Admins keep their password, as the way back in if single sign-on breaks. If nothing else is configured that would let members sign in, OneCamp warns in its log at startup and the admin system check fails.

Before v2.70.0 (v1.55.0 without AI) this setting was read backwards by the sign-in page and ignored elsewhere. If your .env already sets it, check it says what you mean.

When sign-in fails

The sign-in page says which it was:

  • Cancelled at the provider, or left open too long: try again.
  • The address isn't verified with Google or GitHub: verify it there, then sign in again.
  • The address isn't invited: invite the person, add their address to the Sign-up allow-list, or, for a whole company on Google Workspace, its domain as @company.com.
  • The invitation has expired: an admin sends it again from Admin → Invitations.
  • The address uses characters outside plain ASCII: use the account's plain address.
  • There is no room for another person on the free licence's 25.
  • "OIDC is misconfigured on the server" or "SAML is disabled": the API couldn't set the provider up when it started, and its log says why. Run make logs SERVICE=go-service and look for "OIDC init" or "Failed to initialize SAML". Usually make saml-cert hasn't been run, a setting is missing, or the server can't reach SAML_IDP_METADATA_URL or OIDC_ISSUER_URL. Then make restart-api.
  • LDAP says "Invalid directory credentials" for a valid account: OneCamp says this whenever the directory step fails. Check the server can reach LDAP_HOST on LDAP_PORT, the bind account can search LDAP_BASE_DN, and the filter finds exactly one entry.