Docs / Single sign-on (SSO)
Docdeploymill://docs/sso-setup

Single sign-on (SSO)

deploymill supports enterprise single sign-on so your team signs in through your identity provider (IdP) — Okta, Entra ID, Google Workspace, or any standard OIDC/SAML provider — instead of a per-user deploymill password. Once SSO is set up for your domain, teammates who sign in with a matching email address are automatically joined to your org.

How SSO is configured: operator-managed

Be aware up front: SSO connection setup is done by the deploymill operator, not self-serve from the dashboard. Configuring SSO means handing deploymill an IdP secret (an OIDC client secret, or a SAML signing certificate / private keys), and those secrets are infrastructure-level trust — like the platform's own provider keys. They're stored server-side only and are never exposed to an MCP client, returned by any API, or written to a log. So there is deliberately:

  • No MCP tool to register an SSO connection, and
  • No tenant self-serve flow in the dashboard to enter IdP credentials.

To turn SSO on for your org, you give the operator your IdP details (below) and they register the connection. What you can see in the dashboard is a read-only status page confirming the connection — see The SSO status page.

SSO is modeled provider-neutrally: a connection is either OIDC or SAML, and no vendor name is baked into the configuration. OIDC is the common path; the walkthrough below uses Okta as the example.

Domain auto-join

An SSO connection claims one or more email domains (e.g. acme.com). When a user signs in through SSO with an email in a claimed domain:

  • If they're not yet a member of the org that claims the domain, deploymill

    automatically creates their membership with the member role (the least-privileged default — auto-joined users never land as admin or owner). An admin can promote them afterward from /account/org.

  • If they're already a member, nothing changes — they just sign in.

A given email domain can be claimed by at most one org, so auto-join is never ambiguous.

SSO enforcement

By default, having an SSO connection doesn't force anyone to use it — password and "Continue with Google" sign-in still work for the claimed domain. SSO enforcement changes that: when enabled for your org, any sign-in attempt with an email in a claimed, enforced domain is blocked from the password/Google paths and steered to your IdP instead. This is how you guarantee everyone on your domain authenticates through your identity provider.

Like the connection itself, the enforcement flag is operator-set — ask the operator to enable it for your org. The SSO status page shows whether enforcement is on.

Signing in with SSO

There are two ways a user reaches the SSO flow:

  • They click "Sign in with SSO" on the sign-in page (which routes to

    /sign-in/sso) and enter their work email; deploymill resolves the domain to your IdP and redirects them there.

  • If enforcement is on for their domain, even an attempt to use

    password/Google is redirected into the SSO flow automatically.

After the IdP authenticates them, they land back in deploymill, are auto-joined to your org (if they weren't already a member), and are signed in.

Okta setup walkthrough (OIDC)

This is the information you collect from Okta and hand to the deploymill operator. The operator then registers the connection.

  1. Create an OIDC app in Okta. In the Okta admin console, create a new

    OIDC – Web Application integration (Authorization Code flow).

  2. Set the sign-in redirect URI (callback URL). Point it at deploymill's SSO

    callback:

   https://<your-deploymill-host>/api/auth/sso/callback/<providerId>

The <providerId> is the stable connection id the operator assigns your org (for example acme-oidc). Confirm the exact value with your operator before you save the Okta app, since it must match on both sides.

  1. Collect the credentials. From the Okta app, note:

      https://<your-org>.okta.com — deploymill fetches discovery from {issuer}/.well-known/openid-configuration),

      • Decide your claimed domain(s). Tell the operator which email domain(s)

        this connection should claim (e.g. acme.com) — this is what drives domain auto-join, and it must not already be claimed by another org.

      • Hand it to the operator. They register the OIDC connection (issuer, client

        id, client secret, claimed domain, and the providerId). The client secret goes straight into server-side storage and is never echoed back.

      • (Optional) Ask for enforcement. If you want everyone on the domain forced

        through Okta, ask the operator to enable SSO enforcement for your org.

      SAML works the same way (operator-registered, secret-free status page), with the operator supplying the IdP issuer/entityId, the SSO entry point, and the signing certificate (or IdP metadata XML) instead of an OIDC client id/secret.

      The SSO status page

      Admins and owners can view a read-only SSO status page at /account/org/sso (linked from /account/org; plain members don't see it). It confirms, without ever revealing any secret:

      • whether SSO is configured for your org,
      • the provider type (OIDC or SAML),
      • the issuer and connection id,
      • the claimed email domain(s), and
      • whether enforcement is on.

      Because configuration is operator-managed, this page is view-only — there's nothing to edit here. To change the connection, the claimed domains, or the enforcement flag, contact your operator.

      Where to go next

      • Team management — roles, invites, and the seat limit

        (auto-joined SSO users land as member and can be promoted here).