Set up OpenID Connect (OIDC) single sign-on with any identity provider

SimplyPrint works with any standards-compliant OpenID Connect provider, not just the ones with a dedicated preset. This guide covers the universal setup pattern you can follow with Keycloak, Authentik, Auth0, OneLogin, Ping Identity, and similar providers using the Other preset.

If your provider is Microsoft Entra ID, Google Workspace, or Okta, use the dedicated guides instead, they pre-fill provider-specific defaults: Microsoft Entra ID, Google Workspace, and Okta. For a plain-language overview of how organization OIDC works in SimplyPrint, see the OIDC single sign-on overview.

How OIDC connections work

The connection is the same for every provider. SimplyPrint is the relying party (the app signing users in), and your identity provider is the OIDC server that holds the accounts. SimplyPrint uses the standard authorization-code flow with PKCE.

You only need three things from your provider:

• The issuer URL (the base URL whose /.well-known/openid-configuration document lists all the endpoints).
• A client ID.
• A client secret.

SimplyPrint reads the issuer's discovery document and auto-fills the authorization, token, JWKS, userinfo, and logout endpoints for you. You do not paste those in by hand unless your provider does not publish a discovery document.

Before you start

A few requirements to check:

• You need to be an account admin with the user registration settings permission.
• Each account runs one SSO method at a time, either SAML or OIDC. Turning on OIDC deactivates SAML (your saved SAML config is kept), and vice versa.
• You need admin access to your identity provider so you can register a new application and read back the issuer and credentials.

Step 1: Copy your redirect URI from SimplyPrint

You will register a redirect URI (also called a callback or reply URL) with your provider, so grab it from SimplyPrint first.

1. Go to Settings -> Organization and open User registration & SSO.
2. Tick OpenID Connect (OIDC) single sign-on.
3. Click Configure OIDC single sign-on.
4. Select the Other tab at the top of the modal.
5. Under What you need from us, click Copy next to Redirect URI.

Step 2: Create an OIDC client in your identity provider

The labels differ between providers, but the pattern is the same everywhere.

1. In your provider's admin console, create a new application, client, or integration of type OIDC (sometimes called "OpenID Connect" or "web application").
2. Choose the authorization code grant / flow. This is the standard web-app flow. Avoid "implicit" or "SPA / public client" types, SimplyPrint needs a confidential client with a secret.
3. Set the redirect URI (callback / reply URL) to the value you copied in step 1.
4. Make sure the scopes openid, profile, and email are allowed for the client.
5. Save, then note the client ID and client secret the provider generates.

Finding your issuer URL

The issuer is the base URL, not the discovery URL. If your provider gives you a discovery URL ending in /.well-known/openid-configuration, the issuer is everything before that suffix. Two common examples:

• Keycloak: the issuer is https://<your-host>/realms/<realm-name>. The discovery document lives at https://<your-host>/realms/<realm-name>/.well-known/openid-configuration. Older Keycloak versions include an extra /auth segment: https://<your-host>/auth/realms/<realm-name>.
• Authentik: each provider has its own issuer, usually https://<your-host>/application/o/<application-slug>/.

When in doubt, open <issuer>/.well-known/openid-configuration in a browser. If it returns a JSON document with an issuer field, that issuer value is exactly what you paste into SimplyPrint.

Step 3: Enter the details in SimplyPrint

Back in the OIDC modal on the Other tab, fill in the What we need from you section.

1. Paste your Issuer URL. It must start with https://.
2. Click Check. SimplyPrint fetches the discovery document and shows the resolved endpoints (authorization, token, JWKS, and so on). A green "Discovery document looks good" message confirms the issuer is reachable and valid.
3. Enter your Client ID.
4. Enter your Client secret. Once saved, the field shows Unchanged, leave it blank on future edits to keep the stored secret, or type a new one to replace it.
5. Leave Scopes as the default openid profile email unless your provider needs more.
6. Click Save.

Step 4: Map claims to user fields

SimplyPrint needs to know which claims from your provider hold each user's details. Under Claim mappings, the defaults are:

• email -> email
• given_name -> first name
• family_name -> last name

Most providers send these standard claims, so the defaults usually work as-is. Adjust a row if your provider uses a different claim name.

To map your provider's groups to SimplyPrint user groups, add a mapping from your group claim (commonly groups) to user groups, and make sure your client is configured to include that claim. The concept is the same as SAML group mapping, see SSO user groups and group mapping.

Step 5: Test the connection

Save your settings first, then use Test sign-in to verify everything end to end without affecting any accounts.

1. In the modal, click Test sign-in. SimplyPrint opens a new tab and runs the real OIDC flow against your provider.
2. Sign in with a test user at your provider.
3. SimplyPrint shows the claims it received and flags any required claim that is missing. Nobody is logged in and no account is created, it is a safe dry run.

New members and automatic account creation

When a member signs in for the first time, SimplyPrint creates their account automatically as long as their email is trustworthy. An email is trusted when:

• your provider marks the email as verified, or
• the email's domain is one your account has verified (see verified email domains for SSO), or
• an admin turned off Require verified email in the modal's Advanced section.

If none of those apply, the sign-in is refused with a clear message so no unverified account is created. Verifying your email domains is the recommended fix for providers that do not send a verified-email signal.

Providers without a discovery document

A small number of providers do not publish a /.well-known/openid-configuration document. For those, open the Advanced section in the modal and fill in the endpoints manually:

• Authorization endpoint
• Token endpoint
• JWKS URI
• Userinfo endpoint
• End session endpoint (for single logout)

Leave any of these blank to keep using the discovery document. The Advanced section also holds extra authorization request parameters (such as prompt), an Allowed email domains restriction, and the Require verified email toggle.

The End session endpoint also controls sign-out: when your provider advertises a logout endpoint, SimplyPrint signs the user out of your provider too (RP-initiated logout). If it does not, signing out of SimplyPrint ends only the SimplyPrint session, and the provider session stays active until it expires or the user signs out there.

Troubleshooting

The modal has two debug panels that are your main troubleshooting tools:

• Last received claims shows the most recent claims your provider sent (email addresses are masked). Use it to confirm the claim names match your mappings.
• Last sign-in error shows the most recent failure, such as a missing claim or a token validation problem.

For a full list of errors and fixes, see Troubleshooting OIDC single sign-on.

Related articles

• OpenID Connect (OIDC) single sign-on overview
• Verified email domains for SSO
• Troubleshooting OIDC single sign-on
• Set up OIDC with Microsoft Entra ID
• Set up OIDC with Okta
• Set up single sign-on (SSO) for SimplyPrint
• Linking your existing SimplyPrint account to your SSO account
• Signing in with SSO (organization login)

Updated on: 13/06/2026