← Back to Wiki

Single Sign-On with Authentik, Authelia, Keycloak or Okta

If you already run an identity provider, Outpost can hand login off to it. Anything that speaks standard OpenID Connect discovery works, including Authentik, Authelia, Keycloak, Zitadel, Okta and Entra. It is off unless you configure it, so leaving these unset changes nothing.

At your provider

Create an OAuth2 or OIDC application:

• Redirect URI: https://chat.example.com/auth/oidc/callback on your own host. It has to match exactly, trailing slash and all.
• Grant type: authorization code. Outpost uses PKCE together with a client secret, so create a confidential client rather than a public one.
• Scopes: openid profile email. The email claim is required, and an account cannot be created without it.

In your .env

OIDC_ISSUER=https://auth.example.com/application/o/outpost
OIDC_CLIENT_ID=...
OIDC_CLIENT_SECRET=...
OIDC_DISPLAY_NAME=Authentik      # the button reads "Continue with Authentik"
# OIDC_SCOPES=openid profile email
# OIDC_ALLOW_SIGNUP=false        # existing members only, default is true
# OIDC_REDIRECT_URI=https://...  # only if the server sees a different host than the browser does

OIDC_ISSUER is the base URL whose /.well-known/openid-configuration your provider serves. Paste that URL into a browser to confirm you have the right one. It must be https, or localhost for testing.

Configuration is environment-only on purpose. A client secret is a deployment credential like your database URL, and putting it in a settings table would make reading instance settings enough to walk off with it.

Restart the container, then check the server agrees it is on:

curl https://chat.example.com/auth/oidc/config
# {"enabled":true,"displayName":"Authentik"}

How accounts are matched

• The first account cannot be created this way. Claim the instance with the claim code from its console first, then link or add SSO accounts. Otherwise anyone who can authenticate at your provider could claim an unclaimed instance.
• Existing accounts are matched by email, and only when your provider says the address is verified. After the first link, identity is the provider's own user ID, so changing someone's email at the provider does not strand their account.
• SSO accounts have no password, so the password form and the forgot-password flow do not apply to them. That is the point of using SSO.
• Set OIDC_ALLOW_SIGNUP=false if you want SSO to sign in existing members only, rather than creating an account for anybody your provider will authenticate.

The desktop app

Desktop sign-in opens your real browser rather than a window inside the app, so an existing provider session and your password manager both work, and you can see the provider's actual address bar. The browser returns you to the app through an outpost:// link, which the installer registers.

Two consequences worth knowing. The session token never travels in that link, only a short-lived single-use code the app exchanges. And if your desktop environment does not know the app owns the scheme, the browser will complete the login and nothing will happen, which is a packaging problem rather than a configuration one.

On mobile, use a browser for the sign-in step.

If it does not work

• The button does not appear. One of the three required variables is unset or empty. Check /auth/oidc/config.
• The provider rejects the redirect. The registered URI differs from what Outpost sends, usually by a trailing slash or by http against https.
• An account is not created. The provider is not returning an email claim, or is not marking it verified.
• A reverse proxy is in front and the server sees a different host than the browser does. Set OIDC_REDIRECT_URI explicitly.

Keep at least one password account with owner rights. If your identity provider goes down and everybody signs in through it, nobody can administer the instance.