Single sign-on (OpenID Connect)

Let your team sign in to Nightship with the company account they already have — Microsoft Entra ID, Okta, Keycloak, or any OpenID Connect provider. No invites: people sign in, get the role and groups your identity provider says they should have, and their builds follow. The SSO add-on is a flat rate on any paid plan.

How it works

You register Nightship as an OpenID Connect web application with your identity provider and enter what it gives you (issuer, client id, client secret) under Admin → SSO. From then on, Join with invite… in the client notices the server uses SSO and offers Sign in with your organisation: the system browser opens your provider’s sign-in, and when it returns, Nightship creates or updates the user from the claims and hands the client a device token. The client secret never leaves your server; the desktop client only listens on a loopback port for the result.

Users are matched by the provider’s stable subject id, created on first sign-in (name from the email’s local part), and updated at every sign-in: role from a mapped app role (or the default role), membership of managed Nightship groups from the provider’s groups claim. Groups you assign locally stay untouched. A device token is good for 24 hours; after that the client asks for a sign-in again. Removing or disabling the user in Nightship cuts access at once. CI keeps using service-account tokens — SSO is for people.

1. Register the application (Microsoft Entra ID)

In the Microsoft Entra admin center: Identity → Applications → App registrations → New registration.

Name: Nightship. Supported account types: Accounts in this organizational directory only.
Redirect URI: platform Web, value https://builds.example.com/api/sso/callback — your server’s URL plus /api/sso/callback.
From the Overview page note the Application (client) ID and the Directory (tenant) ID. The issuer is https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
Certificates & secrets → New client secret → copy the Value now; it is shown once.
App roles → create Nightship.Admin and Nightship.Publisher (allowed member types: Users/Groups). Assign them under Enterprise applications → Nightship → Users and groups. Everyone without a role becomes a member.
Groups in the token: Token configuration → Add groups claim → Security groups, ID token as Group ID — or in the Manifest set "groupMembershipClaims": "SecurityGroup".

Okta: Applications → Create App Integration → OIDC, Web Application; the issuer is your authorization server’s issuer URL; add the groups claim to the ID token and add groups to the scopes below. Keycloak: a confidential client in your realm; issuer https://<host>/realms/<realm>; add a group membership mapper and the groups scope.

2. Enter it in Nightship

In the app, open your server’s Admin page and the SSO tab. Fill in the issuer, the client id and the client secret; leave Scopes at openid profile email for Entra (add groups for Okta, Keycloak or Dex). Click Test connection — Nightship fetches the provider’s discovery document and checks that the issuer matches — then Save. The status line shows the configured issuer; Clear removes the provider again.

Screenshot — Admin → SSO: provider fields, Test connection, Save, and the mapping table

Admin → SSO, in the app.

From the command line, the same:

nightship sso set --issuer https://login.microsoftonline.com/<tenant-id>/v2.0 \
  --client-id <application-id> --client-secret <secret> --server https://builds.example.com
nightship sso test --server https://builds.example.com
nightship sso show --server https://builds.example.com

3. Map roles and groups

Below the provider fields, the Mapping table says what the provider’s claims become here. Add role mapping… takes an app role value (for example Nightship.Admin) and the Nightship role it becomes; Add group mapping… takes a provider group (its object id for Entra, its name for Okta) and the Nightship group it fills. Set the Default role for people with no mapped role, then Save mapping. A mapped Nightship group is marked managed by SSO on the Groups tab: its membership is synced at every sign-in, while channels are assigned to it as always — nothing is pushed into your identity provider.

From the command line:

nightship sso map role Nightship.Admin admin --server https://builds.example.com
nightship sso map role Nightship.Publisher publisher --server https://builds.example.com
nightship sso map group 3f2a…-group-object-id testers --server https://builds.example.com
nightship sso map default member --server https://builds.example.com
nightship sso map list --server https://builds.example.com

4. Sign in

Team members open the app and click Join a server…, enter the server URL — the invite field makes way for Sign in with your organisation. The browser opens, they sign in as usual, the page says “Signed in”, and the client connects: subscriptions for their groups’ channels appear exactly like after an invite. The server’s Users tab marks people who signed in this way. When the 24-hour token runs out, the server’s page in the app offers Sign in again.

Screenshot — Join a server with the “Sign in with your organisation” button

Joining an SSO server, in the app.

From the command line:

nightship login https://builds.example.com

Seats: an SSO user whose mapped role is admin or publisher takes a privileged seat like anyone else. If the licence is full, they sign in as a member and the client says so; free a seat or add one, and the next sign-in applies the mapped role. The SSO add-on itself is checked on the licence: without it the server answers “single sign-on is not licensed” and the Join dialog does not offer it.

← All guides