No internet connection

Talkyard Single Sign-On API

By KajMagnus @KajMagnus2020-04-15 13:37:44.737Z2020-04-25 12:02:36.058Z

Talkyard has a Single Sign-On (SSO) API. To use it, you'll write some code, and edit Talkyard settings.

(Note: 1) Currently the SSO API is for Talkyard's forum only — not yet implemented, for blog comments. 2) Later there will be OpenID Connect (OIDC) support too. That's a standardized solution that doesn't require you to write any code. On the other hand you need a login server with OIDC support, for example Keycloak.)

Your server needs to include an Authorization: Basic ... header in its API requests — read more here.

The SSO API works as follows. When a user clicks Log In at your Talkyard forum, Talkyard redirects him/her to your website / your login server. The user then logs in over there. Then, your server sends a request to your Talkyard server (whilst the user and web browser do nothing — all this happens quite fast):

// Your server to Talkyard:
POST /-/v0/sso-upsert-user-generate-login-secret

... with JSON for the user who is going to login. Here's a Typescript interface for that JSON:

interface ExternalUser {
  ssoId: string;
  primaryEmailAddress: string;
  isEmailAddressVerified: boolean;  // must be true
  username?: string;
  fullName?: string;
  avatarUrl?: string;

ssoId is your unique ID for the user, in your user database or login system. It must never change.

isEmailAddressVerified must be true — you must have verified your users' email addresses. Otherwise maybe they could hijack each other's Talkyard accounts somehow.

Talkyard then inserts the user in its database, and returns JSON with a one-time login secret:

{  "loginSecret":  "....." }

Your server then redirects the user's browser to:

GET /-/v0/login-with-secret?oneTimeSecret=....&thenGoTo=/

Talkyard looks at the one-time secret, generates a session ID cookie — and thereafter, your user is Single Sign-On logged in, at Talkyard. Talkyard redirects him/her to the thenGoTo url path, / in the example above.


To configure SSO, go here: https:// your talkyard server /-/admin/settings/login

Scroll down to the Single Sign-On section. Follow the instructions. And if you accidentally lock yourself out — you, being the Talkyard site admin, can get a one time login link emailed to you, if you go here: https:// your talkyard site /-/admin-login

  • 0 replies