Single sign-on (OIDC)

PostQueen can sign people in through your own identity provider, so they use the account they already have instead of a new password. Any provider that speaks OpenID Connect works: Authentik, Keycloak, Dex, Okta, Microsoft Entra ID, Auth0 and others. This is about signing in to PostQueen. Connecting social networks is separate: see Channel developer apps.

What changes


The sign-in screen	One button for your provider, labeled with the name and logo you set. It replaces the Google, Apple, Farcaster and wallet buttons. Email sign-in stays.
New people	Anyone your provider lets through gets a PostQueen account on first sign-in, even with `DISABLE_REGISTRATION=true`. Control who gets in at the provider.
Requirement	`IS_GENERAL` has to be set, as it is in the Compose file. Without it the screen shows only GitHub, and none of this appears.

Set it up

The example uses Authentik at https://auth.example.com.

Create the application in your provider

Create an OAuth2 or OpenID Connect application of the confidential type, with:

Setting	Value
Redirect URI	`FRONTEND_URL` + `/settings`, for example `https://postqueen.example.com/settings`
Scopes	`openid`, `profile`, `email`
Client authentication	Client secret sent in the request body (`client_secret_post`)

Copy the client ID, the client secret, and the authorization, token and userinfo endpoints. In Authentik they are https://auth.example.com/application/o/authorize/, .../token/ and .../userinfo/.

Set the variables

POSTQUEEN_GENERIC_OAUTH=true
NEXT_PUBLIC_POSTQUEEN_OAUTH_DISPLAY_NAME=Authentik
NEXT_PUBLIC_POSTQUEEN_OAUTH_LOGO_URL=https://postqueen.example.com/sso-logo.png
POSTQUEEN_OAUTH_AUTH_URL=https://auth.example.com/application/o/authorize/
POSTQUEEN_OAUTH_TOKEN_URL=https://auth.example.com/application/o/token/
POSTQUEEN_OAUTH_USERINFO_URL=https://auth.example.com/application/o/userinfo/
POSTQUEEN_OAUTH_CLIENT_ID=your-client-id
POSTQUEEN_OAUTH_CLIENT_SECRET=your-client-secret

Variable	What it is
`POSTQUEEN_GENERIC_OAUTH`	Turns single sign-on on. Any value turns it on, `false` included: remove the line to turn it off.
`NEXT_PUBLIC_POSTQUEEN_OAUTH_DISPLAY_NAME`	The name on the button.
`NEXT_PUBLIC_POSTQUEEN_OAUTH_LOGO_URL`	The icon on the button, any public image URL.
`POSTQUEEN_OAUTH_AUTH_URL`, `POSTQUEEN_OAUTH_TOKEN_URL`, `POSTQUEEN_OAUTH_USERINFO_URL`	Your provider’s three endpoints.
`POSTQUEEN_OAUTH_CLIENT_ID`, `POSTQUEEN_OAUTH_CLIENT_SECRET`	The application’s credentials.

The userinfo response has to include sub and email.

Recreate the container and try it

Recreate the app container so it reads the new values. A plain docker restart or docker compose restart keeps the old container and its old environment.In the folder that holds docker-compose.yaml, recreate only the postqueen service:

docker compose up -d --no-deps --force-recreate postqueen

The database, Redis and Temporal keep running. Avoid docker compose down for a settings change: on a host that runs other Compose services in the same project, it stops them too. On Kubernetes, see Kubernetes with Helm.

The sign-in screen shows your provider’s button, and signing in lands you in PostQueen.

Copying .env.example turns this on by accident. It ships POSTQUEEN_GENERIC_OAUTH="false", and because any value counts as on, the sign-in screen then shows an unconfigured single sign-on button instead of Google. Remove the line unless you use single sign-on.

If it does not work

The button does not appear

IS_GENERAL is not set, or the container was restarted rather than recreated.

The provider says the redirect URI is invalid

The redirect URI registered at the provider is not exactly FRONTEND_URL + /settings: check the scheme, the host and that there is no trailing slash.

Configuration reference: every sign-in button and what shows it
Deploy to a server: closing sign-up with DISABLE_REGISTRATION

Start here

Install

Domain and HTTPS

Configure

Channel developer apps

Operate

Develop

What changes

Set it up

If it does not work

​What changes

​Set it up

​If it does not work

​Related

What changes

Set it up

If it does not work

Related