OIDC SSO setup

Overview

Fencer supports any identity provider (IdP) that speaks OpenID Connect (OIDC) for single sign-on. This guide covers the general setup process. If your IdP has a dedicated guide (see the sidebar), follow that instead — it includes provider-specific field names and screenshots.

OIDC is an alternative to SAML for SSO. Choose whichever protocol your identity provider supports best. If you need automated user provisioning (SCIM), pair OIDC with the SCIM setup described in the General SAML & SCIM guide — SCIM works with either SSO protocol.

Prerequisites

• An administrator account in your identity provider with permission to create OIDC applications.
• A Fencer organization administrator role.
• A plan that includes single sign-on and SCIM. Without it, the Single Sign-On section of Settings > Authentication shows Upgrade to unlock.

Step 1: Start the connection on the Fencer side

1. In Fencer, navigate to Settings > Authentication and find the Single Sign-On section.
2. Click Configure SSO (or Add OpenID Connect connection if you already have a SAML connection). In the Add SSO connection dialog, select OpenID Connect as the Protocol.
3. Copy the Redirect URI shown at the top of the form. You will paste it into your IdP in Step 2.

Keep this dialog open. You will return to it in Step 3.

Step 2: Create the OIDC application in your IdP

Create a new OIDC (or “OAuth 2.0 / OpenID Connect”) application in your identity provider and configure it with the settings below. Field names vary by provider — match the intent of each setting to whatever your IdP calls it.

Setting	Value
Application type	Web application
Grant type	Authorization Code
Sign-in redirect URI	https://app.fencer.dev/accounts/oidc/oidc-<your-org-uid>/login/callback/
Sign-out redirect URI	Not required — leave blank or set to https://app.fencer.dev/
Scopes	openid, email, profile

Caution

The sign-in redirect URI must match exactly, including the trailing slash. Copy it from the Fencer connection form, or build it from your Organization ID (shown on Settings > Organization, starting with org_). If the URI does not match, your IdP will reject the authentication callback.

Example redirect URI:

If your Organization ID is org_abc123, the sign-in redirect URI is:

https://app.fencer.dev/accounts/oidc/oidc-org_abc123/login/callback/

After creating the application, your IdP will provide:

• A Discovery URL (also called “Issuer URL” or “OpenID Configuration URL”) — typically ends in /.well-known/openid-configuration or is the base URL that Fencer appends this path to automatically.
• A Client ID.
• A Client Secret.

Copy all three values.

Step 3: Finish the connection on the Fencer side

1. Return to the Add SSO connection dialog in Fencer.
2. Paste the Discovery URL into the OIDC Discovery URL field. Fencer fetches the provider’s OpenID configuration automatically to resolve authorization and token endpoints.
3. Paste the Client ID and Client Secret into their respective fields.
4. Under Provisioning, Just-in-Time provisioning is on by default: users who sign in through SSO for the first time get an account and join your organization with the Default role for new users (Administrator, Team Member, Read Only, or a custom role). Optionally, restrict it to specific Allowed email domains (comma-separated; leave empty to allow all domains). Turn Just-in-Time provisioning off to admit only people who are already members, by invitation or by SCIM.
5. Check Enable SSO so users can sign in with this connection. Leave Enforce SSO off until you have tested the connection; turning it on requires every member to sign in through SSO.
6. Click Save Configuration.
7. On the connection card, click Test Connection. Fencer redirects you through your IdP. On success, you return to Settings > Authentication with a confirmation banner.

Note

Test Connection appears once the connection is enabled. When you edit the connection later, leave Client Secret blank to keep the current secret.

Step 4 (optional): Send each user’s Fencer role

To manage roles from your IdP, add a custom claim called role to the ID token or the userinfo response. Its value is the role, as a string — for example "role": "member". The claim name and the values are fixed; the values are the same as for SAML, see The role attribute. Fencer reads the userinfo response first and falls back to the ID token, and applies the claim at every sign-in with the same rules.

Linking existing users to SSO

After enabling OIDC SSO, existing users who were created before SSO was configured need to link their accounts. Fencer does not automatically bind SSO identities to existing accounts by email — each user must explicitly link their SSO identity once.

• For users: A Link your account to SSO banner appears in Fencer for unlinked users. While signed in with their usual method (password or social login), the user clicks Link SSO Account, confirms on the next page, and signs in with the IdP. Once linked, only an administrator can unlink the SSO identity.
• For admins: The Members tab of Admin > Team shows each user’s SSO link status next to their status. Admins can send a reminder email to a user who has not linked yet with Send SSO Linking Reminder in the member’s actions menu.
• New users provisioned via SCIM or created through JIT (just-in-time) provisioning are linked automatically — no action needed.

Caution

Until a user links their SSO identity, they cannot sign in through SSO — even if their email matches. This is a security measure to prevent unauthorized account binding.

Troubleshooting

• “Redirect URI mismatch” or “invalid redirect_uri” errors. The sign-in redirect URI configured in your IdP does not match what Fencer expects. Verify that the URI is exactly https://app.fencer.dev/accounts/oidc/oidc-<your-org-uid>/login/callback/ — including the scheme, trailing slash, and your Organization ID. Watch for typos in the oidc- prefix.

• “Discovery URL could not be fetched” or timeout errors. Fencer could not reach your IdP’s OpenID configuration endpoint. Verify the Discovery URL is correct and publicly accessible. If your IdP is behind a firewall, ensure it allows inbound requests from Fencer’s servers.

• “Invalid client” or “unauthorized_client” errors. The Client ID or Client Secret is incorrect. Double-check both values in your IdP’s application settings. Some IdPs regenerate the secret when you view it — copy the value carefully.

• “Email domain not allowed for SSO” when a user tries to sign in. The connection has an Allowed email domains restriction that excludes the user’s domain. Either add the domain to the allow list, or pre-provision the user via SCIM or invitation so JIT is bypassed.

• “SSO identifier does not match a linked account.” The user exists in Fencer but has not linked their SSO identity. They need to complete the SSO linking flow — a Link your account to SSO banner guides them through it. Admins can also send a linking reminder from Admin > Team.

• Users are not receiving expected claims (name, email). Ensure the OIDC application in your IdP includes the openid, email, and profile scopes. Some IdPs require explicit scope configuration per application.

Related pages

• SSO and Authentication
• General SAML & SCIM setup
• Team and Member Management
• Roles and Permissions