The redirect token was sent twice, often by a page that reloads. Sign a new token for each redirect.
Sign readers in with JWT or OIDC
Readers can sign in to your help center with an account they already have. A private help center then lets them in, and group rules decide what they see. There are two ways: a JWT from your own app, or OIDC from an identity provider such as Okta, Auth0 or Azure AD. What it does for your team is in Make your help center private.
Owners and admins set both up in Help Center > Access Control. JWT sign-in works on every plan. OIDC, private help centers and group rules depend on your plan, see Pricing and plans.
JWT: sign in with your product
A reader chooses Continue with your product on the help center's sign-in page. If JWT is the only sign-in method, the help center skips that page and goes straight on.
The help center sends them to your Login URL with a
return_toparameter. Any query string already on your login URL is kept.Your app signs the reader in if needed, signs a JWT with the help center's signing secret, and redirects to
return_towith the token in the fragment:#jwt=TOKEN.The help center checks the token, starts a session that lasts 180 days, and returns the reader to the page they wanted.
import { SignJWT } from 'jose';
const secret = new TextEncoder().encode(process.env.FERNDESK_SIGNING_SECRET);
// Your login URL: the reader is signed in to your app here
app.get('/help-center/sso', requireLogin, async (req, res) => {
const now = Math.floor(Date.now() / 1000);
const token = await new SignJWT({
email: req.user.email,
name: req.user.name,
metadata: { plan: req.user.plan, roles: req.user.roles }
})
.setProtectedHeader({ alg: 'HS256' })
.setSubject(String(req.user.id))
.setIssuedAt(now)
.setExpirationTime(now + 300)
.sign(secret);
res.redirect(req.query.return_to + '#jwt=' + token);
});The callback also accepts the token as a form POST field or a ?jwt= query parameter, and token works as the field name. The fragment keeps the token out of server logs, so prefer it.
Claims
Claim | Required | What it is |
|---|---|---|
| Yes | Your stable user id. It identifies the reader on every sign-in. |
| Yes | The reader's email. |
| Yes | When you signed the token. |
| Yes | When it expires. |
| No | The reader's display name. |
| No | An HTTPS image URL used as the reader's avatar. |
| No | Attributes for group rules, see below. |
Token rules
Sign with HS256. HS384 and HS512 are accepted too.
A token is accepted for at most 15 minutes after its
iat, whateverexpsays, with no allowance for clock drift.A token handed back through the redirect works once.
issandaudare not checked.If a new
subarrives with an email another reader already has, sign-in fails. A knownsubwith a new email updates the reader's email, unless another reader already has that address.
The signing secret
Ferndesk generates the secret: choose Generate secret under Single sign-on. Owners and admins can reveal and regenerate it there or in Settings > Workspace > Developers under Customer sign-in, which is the same secret. Regenerating it stops sign-in until your app uses the new one. Test sign-in runs the whole flow once a secret and a login URL are set.
Sign in without a redirect
To sign a reader in from inside your product, send POST /api/auth/identify on your help center's domain with the JSON body {"jwt": "TOKEN"}. The Widget SDK does this for the widget. Under More options, a Logout URL sends readers who signed in through your app there when they sign out, with return_to added.
Attributes and group rules
Attributes in metadata are stored on the reader and replaced on every sign-in. Group rules match on them, and every condition in a rule must match.
Values can be strings (up to 256 characters), numbers, booleans, or lists of one of those (up to 64 items).
Nested objects are flattened into dot paths, up to 4 levels:
{"features": {"sso": true}}becomesfeatures.sso.Up to 32 attributes after flattening. A JWT with an invalid attribute is refused.
Operator | Matches when |
|---|---|
is, is any of | The attribute equals the value or one of the values. On a list, any item can match. |
contains | A list has the value as an item, or a string contains it. |
is not, is none of, excludes | The opposite of the matching operator, when the attribute is set. |
is set, is not set | The attribute is present or missing. |
A missing attribute matches only is not set. Rule values are typed as text: true and false match booleans, and a number matches a number attribute.
OIDC
Under Visitor sign-in, open Single Sign-On (OIDC) and enter your provider's discovery URL, client ID and client secret. In your provider, allow this redirect URI:
https://<your help center domain><base path>/api/auth/oidc/callbackFerndesk uses the authorization code flow with PKCE, requests
openid,profileandemail, and sends the client secret in the token request body.The discovery URL must be public and list
issuer,authorization_endpoint,token_endpointandjwks_uri. The ID token's issuer must match it, and its audience must be the client ID.The ID token needs
subandemail. The name comes fromname, thenpreferred_username.An existing reader is matched by email only when the provider sets
email_verified.Any other claim, such as
groups, becomes a reader attribute for group rules. Claims about the sign-in itself, such asauth_time,jtiandemail_verified, are not stored.A reader can have up to 32 attributes. Your own claims fill them first, and standard profile claims such as
given_nameandlocaletake any that are left. Invalid claims are dropped.Signing out ends the help center session only, not the provider's.
Troubleshooting
When a redirect sign-in fails, readers see Sign-in didn't work whatever the cause. To see the reason, send the same token to POST /api/auth/identify: its error field holds one of the messages below.
"This sign-in link was already used"
"Invalid or expired token"
The signature doesn't match the signing secret, the token has expired, or it was signed more than 15 minutes ago. Sign it with the current secret right before the redirect, and keep your server clock in sync.
"JWT expired or missing exp claim"
The token has no exp claim. Add one.
"JWT subject does not match the existing help-center user"
Another reader with a different sub already has this email. Keep sub stable for each person.
"JWT metadata is too large or invalid"
An attribute breaks the limits above, for example a null value or a list that mixes types.
OIDC says "Single sign-on didn't complete"
Check the client ID and secret, that the provider allows the redirect URI and the client_secret_post method, and that the ID token has sub and email.