Skip to Content
Skilder

Single sign-on

Sign members in through your own identity provider, a generic OIDC one or Microsoft Entra ID, on the enterprise image of a self-hosted Skilder.

Pilot release. Self-hosting Skilder is a pilot.

On the enterprise image, people whose email is on your domains sign in through your identity provider with Continue with SSO. You configure it in .env, and the backend applies it at every start. Single sign-on in Configuration is the reference for each variable.

The enterprise image

Single sign-on needs the enterprise backend image. Set it in .env:

.env
SKILDER_BACKEND_IMAGE=backend-ee

Pull it with the registry access Skilder gives you for it (Credentials). With SKILDER_REGISTRY set, copy backend-ee to your mirror first: otherwise docker compose pull fails.

Without any SSO variable, the enterprise image runs exactly as the default one does. To move an install that already runs, follow Switch to the enterprise image and back.

Who signs in how

  • People on your domains are managed by your organization. With enforcement on, they sign in only with Continue with SSO. An account that exists already is linked by its email at its first SSO sign-in: same account, same workspaces.
  • Everyone else keeps their own sign-in: a password, an emailed code or link, or Google, GitHub or Microsoft. A platform administrator off your domains signs in with their password. With SSO only, nobody off your domains signs in, except a platform administrator through break-glass.
  • Newcomers on your domains get an account at their first SSO sign-in and join the install's workspace as a Member, as long as the install holds one workspace. Once it holds two or more, a newcomer needs an invitation, and an SSO sign-in without one is refused. An install where people created workspaces of their own already holds several.
  • Workspaces are created by a platform administrator only. Nobody else gets a workspace of their own, so a newcomer off your domains has an account and no workspace until someone invites them.
  • The invite link admits only addresses on your domains. Invite anyone else by email. This still holds after you switch back to the default image.

Set up an OIDC provider

Register Skilder at your provider

Create a confidential client that uses the authorization code flow, with a client secret. Skilder requests the openid, email and profile scopes, with PKCE. The provider must return each person's email.

Every endpoint the provider's discovery document lists must be on the issuer's own origin. Skilder refuses one on any other.

Set the variables

.env
SKILDER_BACKEND_IMAGE=backend-ee
SSO_OIDC_ISSUER=https://idp.example.com/realms/acme
SSO_OIDC_CLIENT_ID=skilder
SSO_OIDC_CLIENT_SECRET='...'
SSO_DOMAINS=example.com

SSO_OIDC_ISSUER is the issuer exactly as the discovery document names it, over https.

Start Skilder

docker compose pull
docker compose up -d

A missing or malformed value stops the backend at boot, with a line naming the variable: docker compose logs backend.

Register the redirect URI

The backend logs it at every start:

docker compose logs backend | grep instance_sso_connection

Add the redirectUri of that line, <PUBLIC_URL>/api/auth/sso/callback/<id>, to the client's redirect URIs. It stays the same when you change the issuer, the client id or the secret. Moving to Entra and back gives a new one.

Set up Microsoft Entra ID

Entra sign-in goes through a Microsoft app registration of your own.

Register the app

In the Microsoft Entra admin center, open App registrations and click New registration. Choose Accounts in this organizational directory only. Add a Web redirect URI: <PUBLIC_URL>/api/auth/callback/microsoft.

Create a client secret

In Certificates & secrets, add a client secret and copy its value.

Add the email claim (optional)

In Token configuration, add the optional claim xms_edov to the ID token. Skilder reads a person's email claim only when xms_edov confirms it. Without it, Skilder reads their user principal name instead. Either must be on SSO_DOMAINS.

Set the variables

.env
SKILDER_BACKEND_IMAGE=backend-ee
MICROSOFT_SIGNIN_CLIENT_ID=<Application (client) ID>
MICROSOFT_SIGNIN_CLIENT_SECRET='...'
SSO_ENTRA_TENANT_ID=<Directory (tenant) ID>
SSO_DOMAINS=example.com

SSO_ENTRA_TENANT_ID is your organization's tenant id, a GUID. common, organizations, consumers and the personal Microsoft accounts tenant stop the backend at boot.

Start Skilder

docker compose pull
docker compose up -d

The Microsoft button on the sign-in page then signs in through your tenant only: personal Microsoft accounts cannot sign in on this install.

Domains

SSO_DOMAINS lists your email domains, separated by commas. At every start the backend verifies each one, and the accounts on them become managed.

An account stays managed after its domain leaves the list, and after you remove every SSO variable. With enforcement on, the people on a removed domain cannot sign in at all, since no provider serves their address. Before you remove a domain someone still uses, set SSO_ENFORCED=false. Removing a domain signs no one out: their sessions end as any SSO session does, and their agents' access stays.

Removing the provider settings leaves enforcement as it was. If it was on, managed people cannot sign in until you set SSO_ENFORCED=false, so set it before removing them if they need password, emailed code or link sign-in. They still cannot create a workspace. The invite link then admits nobody, since no domain is left: invite people by email.

Sessions and offboarding

A session opened through your provider ends 1 day after its sign-in, however often it is used. The next sign-in goes through your provider again, so a person you disable there loses their Skilder session within a day.

Disabling a person in your provider does not end their agents' access. Their API keys and agent connections keep working until a workspace admin removes them from the workspace.

Enforcement

Enforcement is on by default. While it is on, people on your domains sign in only through your provider: their password, emailed codes and links, and social sign-in are refused. Their API keys keep working.

  • Every start signs them out of each session that did not come through SSO.
  • The start that turns it on also revokes the MCP OAuth tokens of their agents. Each agent signs in again.
  • To turn it off, set SSO_ENFORCED=false and run docker compose up -d backend. Turning it off ends nothing.

Enforcement holds once the install has a workspace. With SKILDER_ONBOARDING_V2_ENABLED on, the install starts without one: single sign-on and enforcement begin when the first workspace is created, and until then the first administrator signs in with their password.

SSO only

SSO_ENFORCED=all closes the install to everything but your provider: every address signs in only through it, whatever its domain. It needs a provider: without one, the backend stops at boot.

  • The sign-in page shows the email field and Continue with SSO, nothing else.
  • An address off your domains cannot sign in at all, nor get an account: no provider serves it. A platform administrator off your domains signs in only with break-glass.
  • The start that turns it on signs every account out of each session that did not come through SSO and revokes the MCP OAuth tokens of their agents. API keys keep working. Every later start signs out of non-SSO sessions again.
  • To go back, set SSO_ENFORCED=true, or false, and run docker compose up -d backend. Going back ends nothing: people off your domains sign in their own way again.

First start with SSO

Set the SSO variables before the first docker compose up -d of the Quick start, then create the first administrator on the setup page:

  • With an email on SSO_DOMAINS, the page then shows Continue with SSO. Your SSO sign-in links to the account you just created, which stays the platform administrator. The password you set is the break-glass password: enforcement refuses it while break-glass is off. With OIDC, register the redirect URI before you continue.
  • With an email off SSO_DOMAINS, the page notes it under the email field, then signs you in with the password, as without SSO. That administrator signs in outside your identity provider, so its multi-factor authentication and offboarding do not apply to them. With SSO only, the page refuses such an email: use one on your domains.

Create the first administrator with an email on SSO_DOMAINS. An administrator off your domains does still sign in when your identity provider fails, but with a password your identity provider does not govern: do not keep one as your fallback. Break-glass covers an outage, with the password you set here, and stays off the rest of the time.

Break-glass

When your identity provider fails, enforcement keeps out every platform administrator on your domains. Break-glass lets them back in with their password. A platform administrator off your domains never needs it, except with SSO only, where it is their one way in.

Turn it on

Add SKILDER_BREAK_GLASS=1 to .env (true works too), then run docker compose up -d backend.

Sign in with the password

On the sign-in page, enter a platform administrator's email, click Use a password and sign in. With SSO only, the page shows Use a password again while break-glass is on. Every other account, and every other sign-in method, stays refused. Each break-glass sign-in is logged as a break_glass_sign_in warning and recorded.

While break-glass is on, each restart signs you out: sign in again after it.

Turn it off once SSO works

Remove the line from .env and run docker compose up -d backend. That start ends the break-glass session and revokes the MCP OAuth tokens the administrator's agents got during it.

A break-glass sign-in is kept on record for 90 days. Turn break-glass off within 90 days of signing in: tokens from an older sign-in are not revoked, and you revoke them in Connected apps of your profile.

An identity provider on your network

An identity provider on a private address works like any other:

  • HTTPS. The issuer is https. When your own certificate authority issued its certificate, add that CA to SKILDER_CA_BUNDLE.
  • Outbound proxy. With an outbound proxy, list the provider's host in NO_PROXY so the backend reaches it directly, for example NO_PROXY=idp.corp.example.com. Through the proxy works too, when the proxy allows it.
  • Browsers. Members' browsers are sent to the provider, so it must be reachable from their network.

Check it worked

Open <PUBLIC_URL>/admin/sso as a platform administrator. The SSO page shows what the backend applied at its last start:

RowShows
ProviderOpenID Connect or Microsoft Entra ID.
Issuer, Client id, Redirect URIFor OIDC. Register the redirect URI at your provider.
Entra tenant idFor Entra.
DomainsSSO_DOMAINS, as applied.
EnforcementOn, on for every address with SSO only, or off, as sign-in applies it. While no workspace exists, it reads off.
Platform admins outside SSOThe platform administrators whose email is on none of your domains: they sign in outside your identity provider, or, with SSO only, through break-glass alone. None when every one is on them.

A warning at the top says when break-glass is on. With no provider settings, the page reads SSO is not configured, and says when enforcement is still on. It changes nothing: edit .env and restart the backend.

Then sign out, and sign in with Continue with SSO with an address on your domains.

On this page