Sign-in & SSO

For production, Orbtrace keeps no passwords of its own. Everyone signs in through your existing identity provider (SSO) — the same one your team already uses for email or Slack. You configure the provider once, restart Orbtrace, and your colleagues can sign in. This is the recommended path: your IdP's MFA, conditional access, and offboarding all apply automatically.

There is also one break-glass local admin login — a username/password form so a fresh install without an IdP is never locked out. On first boot with no SSO configured, Orbtrace auto-provisions it with a generated, per-install password and forces a password change on the first login. It's covered below, with a clear warning that it is break-glass, not production sign-in (no MFA, no lockout).

This page walks you through:

• What's supported, in one table
• Who becomes the first administrator (and the optional local login)
• Step-by-step setup for each provider
• Running more than one provider in parallel
• Turning a provider off
• The two roles every user has
• What to check when something doesn't work

What's supported

You can wire Orbtrace to any one — or any combination — of these:

Who becomes the first administrator

When you first start Orbtrace, no one has any role yet. The first person who signs in is just a regular user — they can see screens but can't change anything in Admin.

To pin one operator email as the administrator from the start, set this in your deployment:

ORBTRACE_BOOTSTRAP_ADMIN_USERNAME=you@yourcompany.com

The first time that email signs in (through any provider), Orbtrace gives that account the Administrator role. If the account already exists as a regular user, Orbtrace promotes it on the next sign-in. The comparison is case-insensitive, so You@YourCompany.com and you@yourcompany.com both match. Orbtrace re-applies this on every login, so the pinned operator can never accidentally lose admin.

The break-glass local admin (fresh installs)

A fresh install with no SSO configured is never locked out: Orbtrace auto-provisions a local break-glass admin on first boot — username admin@orbtrace.local (or your pinned ORBTRACE_BOOTSTRAP_ADMIN_USERNAME) with a generated, per-install password. There is deliberately no fixed default password — a shared built-in credential on every install would be a critical vulnerability, so the credential is random every time and you are required to set a new password on your first login before Orbtrace will issue a session.

Where to read the generated password:

• Helm — the chart stores it in a Secret (it survives upgrades):

  kubectl -n <namespace> get secret <release>-bootstrap-admin \
    -o jsonpath='{.data.password}' | base64 -d

• Docker Compose / bare JAR — it is printed once in the startup log:

  docker compose logs orbtrace-server | grep "BREAK-GLASS"

Configuring any SSO provider disables the auto-generation (pure-SSO sign-in page). On Helm you can also turn the break-glass admin off explicitly with orbtrace.bootstrapAdmin.enabled=false.

Seeding the credential yourself

Prefer to pick the initial password instead of the generated one? Set both values:

ORBTRACE_BOOTSTRAP_ADMIN_USERNAME=you@yourcompany.com
ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD=a-strong-password

The sign-in page shows a username/password form (next to any SSO buttons). The password is BCrypt-hashed into the database at boot and you'll still be asked to replace it on first login (opt out with ORBTRACE_BOOTSTRAP_ADMIN_FORCE_PASSWORD_CHANGE=false). Once you change it in-app the credential is yours — the env value no longer overrides it on restarts.

Set up Google

You'll create an OAuth client inside Google Cloud Console. Google will give you two values — a client ID and a client secret — which you paste into Orbtrace's .env file.

1. 1

   Open the Google Cloud Console

   Go to console.cloud.google.com and sign in with the Google Workspace account that administers your company domain. Create a project if you don't already have one (any name; it's an internal label).

2. 2

   Configure the OAuth consent screen

   In the left menu, open APIs & Services → OAuth consent screen. Choose Internal (only people in your Workspace can sign in) if your company is on Workspace, otherwise External. Fill in the app name (e.g. "Orbtrace"), support email, and your company's domain. Save.

3. 3

   Create the OAuth client

   Open APIs & Services → Credentials, click Create credentials → OAuth client ID, choose Web application.

   Under Authorized redirect URIs, add exactly this URL — replacing https://orbtrace.example.com with your actual Orbtrace URL:

   https://orbtrace.example.com/login/oauth2/code/google

   Click Create. Google shows you a Client ID and Client Secret. Copy both — you can't see the secret again later.

4. 4

   Paste them into Orbtrace's .env

   Open docker/.env on the server where Orbtrace runs, find these two lines, and paste in the values:

   GOOGLE_CLIENT_ID=<the client ID Google just showed>
   GOOGLE_CLIENT_SECRET=<the client secret Google just showed>

5. 5

   Restart Orbtrace

   From the same folder:

   docker compose up -d --force-recreate orbtrace

   The sign-in page will now show a Continue with Google button. Click it, sign in with your Google account, and you'll arrive on Orbtrace.

Set up Microsoft (Entra ID)

You'll register an application inside the Entra admin centre. Microsoft will give you a client ID, a client secret, and a tenant ID.

1. 1

   Open the Entra admin centre

   Go to entra.microsoft.com and sign in with a Microsoft 365 account that has permission to register applications (Global Administrator, Application Administrator, or Cloud Application Administrator).

2. 2

   Register a new application

   Open Identity → Applications → App registrations → New registration.

   • Name: Orbtrace (or whatever you want users to see during sign-in)
   • Supported account types: "Accounts in this organizational directory only" — limits sign-in to people in your tenant
   • Redirect URI: select Web and enter your URL:

   https://orbtrace.example.com/login/oauth2/code/microsoft

   Click Register. The overview page now shows an Application (client) ID and a Directory (tenant) ID — copy both.

3. 3

   Create a client secret

   Open Certificates & secrets → Client secrets → New client secret. Give it any description, pick an expiry (Microsoft requires one; 24 months is reasonable — set a calendar reminder to renew before then).

   Click Add. Microsoft shows the secret once — copy it now. You can't see it again later.

4. 4

   Grant the necessary permissions

   Open API permissions. The default User.Read is already there and is enough. If your tenant requires admin consent for the default permissions, click Grant admin consent for <tenant name>.

5. 5

   Paste them into Orbtrace's .env

   Open docker/.env and fill in:

   MICROSOFT_CLIENT_ID=<the Application (client) ID>
   MICROSOFT_CLIENT_SECRET=<the client secret value>
   MICROSOFT_TENANT=<the Directory (tenant) ID>

   The tenant ID locks sign-in to your organization. If you want anyone with any Microsoft account to sign in (rare; usually not what you want), use common instead.

6. 6

   Restart Orbtrace

   docker compose up -d --force-recreate orbtrace

   The sign-in page will now show a Continue with Microsoft button.

Set up GitHub

You'll create a GitHub OAuth App inside your organization's settings.

1. 1

   Open your organization's OAuth Apps page

   Sign in to GitHub as the organization owner. Go to your organization → Settings → Developer settings → OAuth Apps → New OAuth App.

   (Personal accounts also work — Settings → Developer settings → OAuth Apps — but for company use the organization-owned app is what you want.)

2. 2

   Fill in the application form

   • Application name: Orbtrace
   • Homepage URL: https://orbtrace.example.com
   • Authorization callback URL:

   https://orbtrace.example.com/login/oauth2/code/github

   Click Register application. GitHub shows the Client ID on the next page.

3. 3

   Generate a client secret

   On the same page, click Generate a new client secret. Copy the value — GitHub shows it once.

4. 4

   Paste them into Orbtrace's .env

   GITHUB_CLIENT_ID=<the client ID>
   GITHUB_CLIENT_SECRET=<the client secret>

5. 5

   Restart Orbtrace

   docker compose up -d --force-recreate orbtrace

   The sign-in page will now show a Continue with GitHub button.

Set up a custom identity provider (OIDC)

This is the path for Keycloak, Authelia, Auth0, Okta, JumpCloud, OneLogin, Ping, and any other identity system. You need three things from your IdP:

1. A Client ID and Client Secret (your IdP gives these when you register Orbtrace as an application)

2. An Issuer URL (sometimes called "OIDC discovery URL" or "metadata URL" — points to your IdP's configuration)

3. The redirect URL to register inside your IdP, which is always:

   https://orbtrace.example.com/login/oauth2/code/oidc

1. 1

   Register Orbtrace as an application inside your IdP

   In your IdP's admin console, create a new OIDC client / application. The exact menu name varies:

   • Keycloak: Realm → Clients → Create client → choose OpenID Connect as the protocol
   • Auth0: Applications → Create application → Regular Web Application
   • Okta: Applications → Create App Integration → OIDC - OpenID Connect → Web Application
   • Authelia: Edit configuration.yml → add an entry under identity_providers.oidc.clients
   • JumpCloud / OneLogin / Ping: look for "OIDC application" or "Web application" templates

   Use the redirect URL above. Most IdPs let you tick which OIDC flow is allowed; choose Authorization code (sometimes labelled "Standard flow"). Make sure the IdP returns the openid, email, and profile scopes.

2. 2

   Copy the issuer URL

   Every OIDC provider publishes its configuration at a well-known address. Common shapes:

   Provider	Issuer URL looks like
   Keycloak	https://sso.example.com/realms/<realm-name>
   Auth0	https://<your-tenant>.auth0.com/
   Okta	https://<your-tenant>.okta.com/oauth2/default
   Authelia	https://auth.example.com
   Microsoft Entra (as OIDC)	https://login.microsoftonline.com/<tenant-id>/v2.0

   If you're not sure: open <your-issuer-url>/.well-known/openid-configuration in a browser. If you see JSON, that's the right URL (without the /.well-known/... suffix). If you see a 404, you have the wrong URL.

3. 3

   Paste everything into Orbtrace's .env

   OIDC_CLIENT_ID=<the client ID your IdP gave>
   OIDC_CLIENT_SECRET=<the client secret your IdP gave>
   OIDC_ISSUER_URI=<the issuer URL from step 2>
   ORBTRACE_OIDC_DISPLAY_NAME=Acme SSO

   ORBTRACE_OIDC_DISPLAY_NAME is the label shown on the sign-in button. Set it to something your team recognises — "Acme SSO", "Keycloak", "Company login". If you leave it blank, the button reads "Continue with Single Sign-On".

4. 4

   Restart Orbtrace

   docker compose up -d --force-recreate orbtrace

   Orbtrace asks your IdP for its configuration once at startup — there's nothing else to wire. The sign-in page will now show your custom button.

Running more than one provider at the same time

Nothing special — fill in the variables for every provider you want, restart, and every configured provider's button shows up on the sign-in page in parallel.

A common combination:

• Custom OIDC (Keycloak, your corporate SSO) — the primary path for employees
• Google — for a couple of contractors who don't have corporate accounts

Both are configured at the same time. Employees click one button, contractors click the other.

Turning a provider off

To hide a provider from the sign-in page: clear its variables in .env and restart.

# Disable Google by clearing both:
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

The button vanishes on the next start. Existing user accounts that were created through that provider stay in Orbtrace — they just can't sign in any more (until you re-enable the provider or move them to another one).

Roles

Orbtrace has exactly two roles. Every user has one or the other.

The first administrator is set by ORBTRACE_BOOTSTRAP_ADMIN_USERNAME (see above). After that, any administrator can promote other users in Admin → Users. Orbtrace prevents you from demoting the last remaining administrator — there's always at least one account that can rescue the others.

When something doesn't work

A short checklist of the most common stumbles.

If something isn't on this list, check the Troubleshooting page or open docker compose logs orbtrace — sign-in errors print a clear one-line reason at WARN level.

Where to go next

• You've just configured your first provider → continue with First login for the five-minute post-sign-in checklist.
• You want the full list of every setting → see Configuration.
• You need to invite or manage users → that lives in Admin → Users inside the app once you're signed in as an administrator.