Skip to main content

Setting up Single Sign-On (OIDC)

Paperparrot now supports single sign on through whatever OpenID Connect provider you've already configured for Paperless (Authelia, Authentik, Keycloak, Zitadel, or any other standards-compliant OIDC provider), instead of a username/password or API token.

Only generic OpenID Connect providers are supported. Providers that are plain OAuth2 without OIDC (for example GitHub) can't be used here as they don't issue an ID token or support a PKCE-only public client, which the app's login flow requires. Google has the same problem in practice (it requires a client secret even with PKCE), so it isn't supported either. In that case, you should use token based authentication instead.

1. Add the app's redirect URIs to your IdP client​

The app reuses the same client your Paperless-ngx server is already configured with, it does not register its own. In your identity provider's admin console, open that client's settings and add these as additional allowed redirect URIs (on top of whatever Paperless-ngx's own web callback already is):

  • https://paperparrot.me/oidc-callback: used automatically on iOS 17.4+ / macOS 14.4+
  • paperparrot://oidc-callback: used as a fallback on older OS versions

You should only add the second one if you expect devices with older OS versions to use SSO.

2. Make sure the client allows a public/PKCE token exchange​

Paperparrot performs its own Authorization Code + PKCE exchange directly against your IdP and it does not support client secrets. Make sure your IdP is configured to accept a PKCE code exchange for this client without requiring a client secret (most self-hosted IdPs support this per-client, sometimes labeled "public client" or "client authentication: off", alongside the confidential setup Paperless itself uses). Check your IdP's own documentation for the exact setting.

Also make sure the client is allowed to request the openid, profile, and email scopes.