Talkyard Single Sign-On API
Talkyard has a Single Sign-On (SSO) API. To use it, you'll write some code, and edit Talkyard settings.
This page is about SSO when accessing the Talkyard site directly, but you can also add SSO to embedded comments at your website, if any, see: How to add Blog Comments Single Sign-On (SSO).
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
Linked from:
- F@fas
HI, I see from other forum posts that OIDC is implemented. What is the status of SSO for blog comments please?
KajMagnus @KajMagnus2021-05-08 09:45:54.641ZHI @fas, what type of SSO for embedded comments, do you have in mind?
- Embedded comments via Talkyard's custom Single Sign-On works but one needs to click "Log in" even if already logged in at your user management system.
- Or do you use OIDC? I didn't try that yet with blog comments. I would think it'll just work — and if it doesn't, shouldn't take long to fix any issues — however one would still need to click "Log in" once extra, even if already logged in.
- And / or did you have in mind to include some HMAC signed (or even encrypted somehow) user identity in the generated blog post page, so that Talkyard got to know who the user was, directly? — Then, no extra "Log in" click needed. (This is, I think, how Disqus and others work)
Hello @KajMagnus
Yes I was thinking along the lines of your HMAC user identify already embedded so no login is necessary. The extra login click and user selection wouldn't work well in my case.
Is this sort of thing possible? I'm OK using the custom sso solution, although OIDC is also an option.
- KajMagnus @KajMagnus2021-05-11 08:21:36.663Z
I've started making this work. I think there'll be something for you to try out in 1 – 3 weeks.
I have in mind to use PASTEO tokens (if you happen to know what that is).
If one of your members logs in once, and then again later, but then with a different email address, then, what would you want Talkyard to do? E.g. update the user's email address in Talkyard's database? Or only do that, if you've explicitly configured this via some admin setting?
- CIn reply toKajMagnus⬆:Christian Scheuer @chrscheuer
Hi @KajMagnus
Great timing you just added this. We're so happy with the SSO API obviously, making our integration extremely easy!
I wondered, given than we're using the ssoId as the unique identifier for users, how would we go about if the user on our side requests to change their email address?
The unique ID we're offering to you would remain the same, but would the SSO API automatically make sure to change the user's email on your side? Or would it throw an error if we suddenly provide a new email?
Now that our community is growing quite rapidly, users changing emails is becoming more and more common, and currently, in part due to not knowing how the forum would handle this, we don't support users changing emails at all. That creates a HUGE amount of extra manual work every time a user wants to change their emails (we essentialy have them sign up again and transfer their data), so looking to eliminate that work by actually implementing the feature.
Would we need a new API from TY to set the user's new email address? Or what are your thoughts?
- KajMagnus @KajMagnus2021-05-08 09:53:56.078Z
how would we go about if the user on our side requests to change their email address?
There could be configuration settings that tell Talkyard to update the email address, if it's different, when a user logs in.
not knowing how the forum would handle this, we don't support users changing emails at all.
I don't think Ty is able to update one's email yet (but it's going to do, if configured to do so).
have them sign up again and transfer their data
Oops that indeed sounds like lots of work
Would we need a new API from TY to set the user's new email address?
I'll have a closer look, but I think what's needed is a config value that tells Ty to update the email. And that I make Ty run an SQL statement to update the email if needed, + e2e tests.
- CChristian Scheuer @chrscheuer
Thanks for looking into this.
Let me know what you find out. This would indeed be very good for us to get automated sooner rather than later :)
- KajMagnus @KajMagnus2021-05-11 08:23:39.153Z
Ok :- ) Seems I'm doing this now, together with making blog comments Single Sign-On work, it's the same part of the code base.
I wonder if updating the email address, should maybe be the default behavior, hmm.
- CChristian Scheuer @chrscheuer
Are email addresses used for anything unique in TY? We need to think about the possible failure cases and how to handle it if this is handled as part of the normal sso login api
- CChristian Scheuer @chrscheuer
Oops I was typing this on my phone but thanks for looking into it now :)
- CChristian Scheuer @chrscheuer
I can't figure out if it's good or bad to handle auto-email changing as part of the SSO login.
click to show
- TIn reply toKajMagnus⬆:@Thor
Hey! Looking to provide a forum on our platform. Would this be able to work when our users log in with auth0?
To clarify, if a user logs into our platform, with auth0, we want them to be automatically logged into talkyard
- KajMagnus @KajMagnus2021-06-22 19:12:34.296Z
Hello, Auth0 supports OIDC and Talkyard too — here's docs about OIDC: How to enable OIDC login. So, yes, Auth0 (and Okta) should work with Talkyard. Currently tested only with Azure and a bit with Keycloak though.
OIDC works for logging in to a Talkyard forum (which seems to be what you're looking for),
but not yet for for logging in to embedded blog comments. - In reply toThor⬆:KajMagnus @KajMagnus2021-06-22 19:25:09.385Z
To clarify, if a user logs into our platform, with auth0, we want them to be automatically logged into talkyard
The way that works, is that the user clicks Log In, in the Talkayrd forum, and then gets redirected to Auth0,
where s/he gets to confirm that s/he wants to login to Talkyard, and share his/her name and email address with Talkyard (for reply notifications).
Thereafter, s/he gets sent back to Talkyard, now logged in.So, there's a confirmation step (I think there are with almost all SSO solutions), otherwise it's automatic.
Thanks for the reply. To confirm, if a user goes to our platform (web app, not the talkyard page) and logs in with auth0, then went to our talkyard forum, they would need to click log in again?
Apologies if I was unclear in the first comment. We want them to log into our web app (not talkyard) via auth0, but then when they go to our talkyard page, they will be automatically logged in without having to click log in again. Is that possible?
- KajMagnus @KajMagnus2021-06-23 15:03:11.112Z
they would need to click log in again?
they will be automatically logged in without having to click log in again. Is that possible?Now I start wondering if you're maybe interpreting "click login" as "having to type one's username and password etc" again. If so, no, they don't need to do that.
If instead you mean avoiding a single click on the "Log in" button — then, you could add some Javascript that automatically redirects them to Auth0, so they didn't need to click themselves.
I'm not sure if it's worth the time, though, to do that. It'd save them a second (a mouse click) per year or per lifetime, and, I wonder if it could make them confused if they don't see what's happening.Maybe I just made things confusing by mentioning details about how it works. — Talkyard uses standard OIDC / OAuth2, the same as other software that has OIDC / OAuth2 Single Sign-On.