Set up single sign-on (SSO) for your help center

Sign readers in to your help center from your app with an SSO URL, using the Messenger or a redirect from your server.

8 min read

When a reader who isn't signed in opens your help center, Notiondesk sends them to a page of your app, your SSO URL. That page signs them in with the Messenger or with a redirect from your server, and they land back on the page they asked for, without a second login.

Quick path: go to Settings > Access, select Guest accounts, then enter a page of your app in SSO URL.

Before you start

  • Your help center uses the Guest accounts access mode.
  • You have an App Secret. Create one in Settings > Access, in the App Secret card. It's shown only once, so store it on your server, for example in NOTIONDESK_APP_SECRET.
  • Your server can sign a user token. Identify logged-in users in Notiondesk Messenger explains the token. In Settings > Widget, the Sync user information card gives signing code in Node.js, Python, PHP and Ruby, with your site_uuid filled in. Store that site_uuid on your server too, for example in NOTIONDESK_SITE_UUID.
Never sign the token in the browser. Anyone who has your App Secret can sign in as any reader of your help center.

Step 1: Add your SSO URL

  1. Go to Settings > Access.
  1. Under Access control, set Access mode to Guest accounts. It saves as soon as you pick it.
  1. In SSO URL, enter the address of the page of your app that signs readers in, for example https://app.example.com/help-sso.
  1. Click Save changes.

The SSO URL must start with https://, use a domain name (not localhost) and be a page of your app, not of your help center. If your help center is on your own domain, use another host, or the same host outside the help center's path: with your help center at example.com/help, example.com/login works.

When Notiondesk sends a reader to your SSO URL, it keeps your own query string and adds return_to, the full address of the help center page the reader asked for. It also adds two parameters the Messenger uses. Leave them on the URL.

Step 2: Sign readers in on your SSO page

Pick the option that fits your app. Both use the same user token.

Option A: with the Messenger

Use this option if your app already runs the Messenger. On your SSO page, load the Messenger with a user token for the signed-in user. The Messenger signs the reader in to your help center and sends them back to the page they asked for. There's nothing else to call.

Make sure your SSO page:

  • Signs the user in to your app first. A visitor without a user token isn't signed in to the help center.
  • Loads the Messenger of the help center the reader came from, with a token signed with that help center's App Secret.
  • Signs the token when the page loads, with an expiry of one hour or less. A later expiry is refused.
  • Opens as a normal page, not inside a frame, and doesn't set the Messenger's apiUrl option.
  • Keeps the full address it was opened with. If your login sends the user to another site or tab first, bring them back to that same address, with all its parameters, before the Messenger loads.

The Messenger SDK documentation covers the React, Vue and script tag installs in its Help center sign-in section.

Option B: with a redirect from your server

Use this option if your app doesn't run the Messenger, or if you'd rather sign readers in on your server.

  1. On your SSO page, read return_to from the address and keep it through your login.
  1. On your server, sign a user token for the signed-in user with your App Secret.
  1. Redirect the browser to https://help.example.com/private/sso/jwt?jwt=TOKEN&return_to=RETURN_TO, with your help center's domain, the token and return_to, both values URL-encoded. With a help center at example.com/help, the address starts with https://example.com/help/private/sso/jwt.

Here's an example in Node.js with Express. requireLogin stands for your own login check: it sends a signed-out user to your login page, then back to this address with its query string.

const jwt = require('jsonwebtoken');

const HELP_CENTER_URL = 'https://help.example.com';

app.get('/help-sso', requireLogin, (req, res) => {
  const now = Math.floor(Date.now() / 1000);
  const token = jwt.sign(
    {
      type: 'site_contact_app',
      iat: now,
      exp: now + 300,
      user_id: String(req.user.id),
      site_uuid: process.env.NOTIONDESK_SITE_UUID,
      email: req.user.email,
      name: req.user.name,
    },
    process.env.NOTIONDESK_APP_SECRET,
    { algorithm: 'HS256' },
  );

  const target = new URL(`${HELP_CENTER_URL}/private/sso/jwt`);
  target.searchParams.set('jwt', token);
  if (req.query.return_to) {
    target.searchParams.set('return_to', req.query.return_to);
  }
  res.redirect(target.toString());
});

Keep these rules in mind:

  • Sign a new token for each redirect. A token signs a reader in once.
  • Give it a short expiry. 5 minutes is enough, and more than one hour is refused. Keep your server clock in sync: a difference of up to 60 seconds is accepted.
  • Keep the token under 8 KB, so keep any custom_attributes small.
  • Pass return_to back unchanged. Without it, or with an address outside your help center, the reader lands on the help center's home page.
  • Redirect from your server. Never put this link in an email, since the token is in the address.

You can also send users straight to this address from your app without an SSO URL, for example from a Help link in your app's menu. Set return_to to the help center page you want them to open.

Step 3: Test it

  1. Open a private browser window and go to a page of your help center that needs sign-in.
  1. Check that you land on your SSO URL, sign in to your app, and come back to the same help center page, signed in.

If it doesn't work, check a token your app signs:

  1. In Settings > Access, under SSO URL, click Check a sign-in token. It appears once an SSO URL is saved.
  1. Paste the token, then click Check token. You'll see whether your help center accepts it, and why not. The token is checked and never stored.

Choose when readers go to your SSO URL

Require login, the switch above SSO URL, is on by default. With it on, every reader who isn't signed in goes to your SSO URL when they open your help center.

With it off, anyone can browse your help center, and only these readers are sent to your SSO URL:

  • Readers who open an article that needs sign-in.
  • Readers who follow a help center link that ends with nd_sign_in=1, such as https://help.example.com/en/articles/billing?nd_sign_in=1. Add it to the help center links inside your app.
  • Readers who click Continue with your account on the help center's sign-in page.

Guests you invited can still choose Use email and password on the sign-in page.

Link readers to guest accounts you invited

A token for a user you never invited signs them in as a new reader. To give a user the access and role of a guest account you invited by email:

  • Include the user's email in the token from the first time you identify them. A user first identified without it keeps a separate reader, without the guest account's access, even if you add the email later.
  • If your app hasn't verified a user's email address, send email_verified: false. That user isn't linked to the guest account. If you leave it out, the email counts as verified. Send it as true or false, not as text: a value like "true" counts as false.
  • A guest account links to one user_id. A second user who signs in with the same email keeps a separate reader.

If the guest's invitation was still pending, it's accepted automatically.

Troubleshooting

ProblemCauseFix
The reader lands on the sign-in page with "We could not sign you in automatically. Try again, or sign in below."The token was refused: it expired, was already used, expires more than one hour ahead, or was signed with another App SecretRun Check a sign-in token, and sign a new token for each redirect
The reader stays on your SSO pageThe Messenger had no user token or an invalid one, the address lost its parameters during your login, the page is in a frame, or apiUrl is setRun Check a sign-in token, and check the list in Option A
The reader is signed in but lands on the home pagereturn_to was missing or isn't a page of your help centerPass return_to back unchanged
Readers are never sent to your SSO URLNo SSO URL is saved, or Require login is offSave an SSO URL, then add nd_sign_in=1 to your help center links or turn on Require login
"Enter a URL that starts with https://" when you saveThe SSO URL isn't an https:// addressUse the https:// address of a page of your app
"Enter a page of your app, not of your help center." when you saveThe SSO URL is on your help center's addressUse another host, or a path outside the help center
Check a sign-in token says "This token is not valid yet."iat is in milliseconds, or your server clock is aheadUse seconds, and sync your server clock
A reader doesn't get the access of the guest account you invitedThe token had no email the first time, or email_verified isn't trueSee "Link readers to guest accounts you invited" above

Common questions

Do readers sign in twice?

No. Readers signed in to your app go through your SSO URL and come back signed in, without a Notiondesk login.

Which option should I choose?

Option A if your app already runs the Messenger on a page you control. Option B if it doesn't, or if your login runs on your server.

Can readers still sign in with an email and password?

Yes. Guests you invited can choose Use email and password on the help center's sign-in page.

How long does a reader stay signed in?

Up to 12 hours. Signing out of your app doesn't sign them out of the help center, so keep that in mind on shared computers.

Who can change the SSO URL?

Workspace owners, Admins and Editors.

How do I turn SSO off?

Clear the SSO URL field and click Save changes. Readers then sign in with their email and password.

Related articles

Was this page helpful?

Still need help? Ask us