No internet connection
  1. Home
  2. Ideas

Single-Sign-On and API

By KajMagnus @KajMagnus2018-08-19 13:58:55.825Z2018-08-20 04:17:00.939Z

Here is how Talkyard's API and Single-Sign-On via API can look and work. Would you like to post feedback?

Endpoints and Single-Sign-On

Call the API like so, from your backend application servers:

POST /-/v0/login-or-signup  + json payload, see below
POST /-/v0/create-topic     + json payload
GET  /-/v0/list-topics?categoryId=123

v0 is the API version (version zero, that's Talkyard's current major version: 0.x.y).

/-/v0/login-or-signup returns json that includes the user's ID in Talkyard, and a works-just-once link that you can redirect a user's browser to, to make the browser "become" that user (that is, the browser gets a session cookie, for that user).

SSO can work like so: 1) Talkyard's login and signup buttons redirect to a custom URL at your server, like /login?returnToUrl=${currentTalkyardUrlPathAndQuery}. Then 2) user then logs in at your server (if not already logged in). Thereafter 3) your server calls /-/v0/login-or-signup on the Talkyard server, gets the one-time link to the Talkyard forum, and 4) redirects the user's browser to that one-time-link, and the user in that way gets logged in at Talkyard.

To /-/v0/login-or-signup, you'd post this json:

{
  externalSsoId: '123abc',       // required. E.g. the primary key column in your users database table
  primaryEmailAddress: 'the-user@x.co', // required. The user's email, at your site
  isEmailAddressVerified: true,  // required. You must have verified the user's address, must be true
  username: 'the_username',      // required. The user's username, at your site
  fullName: 'Opt Full Name',     // optional
  avatarUrl: 'https://...,       // optional
  aboutUser: 'I work with ...' , // optional
  isAdmin: false,                // optional. If true, the user will become admin.
  isModerator: false             // optional
};

and then Talkyard checks if there's a user already with the specified external ID, in Talkyard's database. If so, that user gets updated to match the data in the request. If there is none, a new user gets created, that is, a signup happens. In any case, Talkyard responds with json that includes 1) the above-mentioned one-time create-session-cookie link that you then redirect the user's browser to, and 2) the user's ID in Talkyard, if instead you want to do requests on behalf of that user, directly from your backend servers.

Authentication, Authorization and API keys

  • Basic auth, i.e. HTTP headers.
  • The basic auth username is the ID of the user you're doing the request on behalft of.
  • The API key is the basic auth password.
  • Each user can have one or more API keys. (Having more than one active key can make sense, for a while, when rotating keys.)
  • There'll be magic Anyuser API keys that lets you to specify any user id.

The nearest time, there'll be only the Anyuser key, for simplicity. So, initially, you can do requests on behalf of any user, to do anything. For example, submit a request to /-/v0/login-or-signup as the sysbot user, to create a user, and then submit another request, as that new user, to create a topic.

API key management

  • An "API" tab in the Admin Area.

  • A list of keys and to which user each key belongs.

  • Delete and Generate new ... buttons next to each key.

  • To rotate API keys, you'd click Generate new ... — then, a new key is generated. And you get asked: "Delete old key after 24 hours?" and if you chooses to do that, then the old key is automatically deleted, 1 day later. Then, it's impossible to forget to delete the old key, after having updated clients to use the new key instead. (Otherwise one would need to remember oneself to go back, and delete the old key.)

  • A "Revoke all API keys" panic button?

  • Info texts:

    • "Do not push your key to GitHub or somehing like that. All API keys are secret, they are like passwords."

    • Info about how securely store one's key(s) on one's servers.

Misc

  • Maybe would be better to refer to the keys as API passwords? Since that makes it more obvious to "newbies" that they are secrets? And also that's how I'm thinking about using them in the Basic Auth protocol: as passwords, not usernames.

  • The API password will never be included in any URL — that'd be risky, could then get leaked via server request logs.

Later?

  • Maybe a:

    [ ] Automatically create new keys each ___ weeks and send reminder emails to: _______ ; delete old keys after ___ more weeks

    checkbox and input fields, for automatically generating new keys every X weeks, and also deleting the old keys after Y more weeks. Makes it impossible to forget to rotate API keys. Instead, what'll happen if forgotten, is that any API client one forgot to update with the new key, will temporarily stop working (until gets new key).

Your feedback?

What problems can you see with the ideas above? What won't work, needs to be done differently? Or what is too complicated? Or unclear and needs to be explained better? And what's on the right track, seems like ok-will-work?

  • 25 replies

There are 25 replies. Estimated reading time: 40 minutes

  1. C
    Christian Scheuer @chrscheuer2018-08-20 15:01:36.419Z

    This is a really great starting point, IMO.
    A couple of comments.
     

    ==

    v0 is the API version (version zero, that's Talkyard's current major version: 0.x.y).
    

    I would keep the API version and major version separate. You might be able to keep the API version (no breaking changes) even after upgrading to v1. In that case you don't want all consumers of the API to change addresses when not needed. Also, you might want to introduce a new API version at any point in your release cycle, while still maintaining the old API version for backwards compatibility (with maybe at least 6-12 months overlap before the old API version will stop working). This is just a "definition" problem, but an important one. In any case I would just increase the API version whenever there is a breaking change (and, importantly, leave the old endpoints still valid).
     

    ==

    /-/v0/login-or-signup returns json that includes the user's ID in Talkyard, and a works-just-once link that you can redirect a user's browser to, to make the browser "become" that user (that is, the browser gets a session cookie, for that user).

    In the description of the login roundtrip between Talkyard's server I think we're missing the option to tell Talkyard exactly where we want it to go when we redirect the user to the "works-just-once" link.
    Obviously if a user starts on a Talkyard page (maybe they followed a link directly there), they will get redirected to myserver.com/login?returnToUrl=${currentTalkyardUrlPathAndQuery}. But I won't have any use of the parameter returnToUrl here. Since I am supposed to redirect the user to the auth url returned by the /-/v0/login-or-signup call which will authenticate the user. Once I have redirected the user my control is up. So I can't both redirect the user to the URL that will sign them in, AND return them to where they wanted to go.
    In the same way, if the user starts at one of my web server pages (not a Talkyard page) and we want to link the user directly to a specific thread within Talkyard, we can't do this with the current mechanism, since again we could only post a login-or-signup attempt, which doesn't take a redirectTo parameter.
    So, all in all, I think the login-or-signup needs to accept a parameter with the URL that we'd like you to take the user to after signing that person up.

    ==

    This brings me to another thing. By keeping the externalSsoId and internal talkyard user id columns separate, both systems need to keep a record of each other's IDs. That might complicate some tasks..
    Without going into too much detail, I think it's vital that other user-related functions in Talkyard would then work based on the externalSsoId as well - if not, then you force the API consumer to go through a login-or-signup call every time they want to even get information about a user through the API, since they won't know the Talkyard internal user id any other way.
    More importantly, the API also needs to take into account how to deal with users who were not created through the API. Right now those users would have no externalSsoId so there would be no way for us to log them in through this API.
    If this situation is intentional - that is, if SSO as a login method is meant to be exclusive, barring users from being created directly in Talkyard, then it's fine. Then for migrating our existing users, we just need to be able to (at least manually) assign externalSsoId's to existing users in the Admin area, so we can pair them up.
    IF you want signup via Talkyard and signup via SSO to coexist, this design needs to be reworked. I think for simplicity the exclusive design choice makes sense though. I'll be happy to give further details to this discussion if you need it.

    ==

    A question. The username field is required in the input. In our system we have only an UID and a email address as unique columns, no usernames. What we have that is closer to a name is a "full name" property as well. How would we approach this situation? Since our email addresses are guaranteed to be unique in our system, we could use those as the usernames when sent to Talkyard - but I'm not sure if Talkyard accepts that as usernames. The problem with using email addresses are that they are all of a sudden public then. I think most of our customers would have a problem with that.
    This brings us to we could use the Full Names as a basis for the username. But I assume that Talkyard expects a unique username - which again we can't guarantee for our Full Name field.
    One option for us to deal with this would be when a user clicks our "Forum" button:

    1. Check if this user has already registered a Talkyard id in its usercolumn
    2. If it does, log in using our own externalSsoId (but knowing that it won't create a new user), and fill in the username field with what's already recorded
    3. If the user hasn't registered, the user will need to register a new username with Talkyard. But through a series of API calls where we poll Talkyard and ask if this username is already registered? Or we keep our own checklist?

     
    You can see how this quickly becomes complicated, since we would have to implement the concept of a "forum username" and ensure uniqueness for this.
    A slightly better approach seen from a API consumer standpoint would be that it was possible to pass in a null username, and in the case where Talkyard is creating a new user (it didn't know the externalSsoId before) it would simply present us with a "splash" screen before redirecting you all the way. A screen in which the user is asked to choose a forum username.
    In this way, the user would be in "forum-land" when choosing their forum username, which makes sense to me. This would also simplify any validation of usernames that is not just uniqueness - character set limitations, length limitations, etc. By having Talkyard be charge of this, we would keep the logic in one place and not have to sync it across version changes. Ensuring proper validation implementations across systems is a real pain, and could lead to many obscure errors.

    ==

    Maybe would be better to refer to the keys as API passwords? Since that makes it more obvious to "newbies" that they are secrets? > And also that's how I'm thinking about using them in the Basic Auth protocol: as passwords, not usernames.

    I've seen the term API Secret beeing used widely for this specific purpose.

    ==

    1. KajMagnus @KajMagnus2018-08-23 15:33:34.549Z

      Hi Christian,

      Ok and thanks for the comments :- )

      ==

      Separate versioning for the API sounds good. Ok let's do that then.

      ==

      About /-/v0/login-or-signup, and:

      missing the option to tell Talkyard exactly where we want it to go when we redirect the user to the "works-just-once" link

      Ok yes that's a good point. This: "the auth url returned by the /-/v0/login-or-signup" can instead be a one-time-secret-key, say nnnn (instead of a complete url), which you'd include in a URL query param together with a &thenGoTo=/some/page param, when telling the browser where to go next. After getting the response from the login-or-signup API request, you'd send the browser to:

      https://talkyard.server/-/login-sso?oneTimeKey=nnnn&thenGoTo=/some/page
      

      And the Talkyard server then creates a session cookie, and redirects the browser to /some/page.

      (Alternatively, maybe could send the user directly to the destination page, with an extra query param instead? Like so: https://talkyard.server/some/page?oneTimeLoginKey=nnnn)

      So, all in all, I think the login-or-signup needs to accept a parameter with the URL that we'd like you to take the user to after signing that person up.

      Hmm your backend server woud do a POST request to login-or-signup, and then, after getting a response with the nnnn sso key, your backend server would send the browser to the /-/v0/login-sso?oneTimeKey=nnnn&thenGoTo=... url. The thenGoTo url is from the initial your-server.com/login?returnToUrl=${currentTalkyardUrlPathAndQuery} request to your server (or maybe just &thenGoTo=/ if everything starts at your server, and you want to send the user to the topic list page).

      ==

      vital that other user-related functions in Talkyard would then work based on the externalSsoId

      Ok, maybe the OpenAuth username could be like externalSsoId=your-user-id if it's your external id, and talkyardId=4567 if the id is for Talkyard's database? Or maybe 2 would be user id 2 in Talkyard's database and 2@external or 2@your-company-name could be for ids in your database?

      In any case, sounds like important to be able to use your own ids, so you won't need to lookup ids.

      And, when using the API without SSO, then there are no external ids, so then one wants to be able to use the Talkyard user ids.

      More importantly, the API also needs to take into account how to deal with users who were not created through the API. Right now those users would have no externalSsoId so there would be no way for us to log them in through this API.

      I was thinking (and forgot to write) that if an existing user account has the same email address as [an external user that signs up via SSO], then it'll be assumed that those two accounts (i.e. the Talkyard user account and the external account in your database) are for the same person — and the Talkyard user account will be assigned the external id of that external user, and updated with its external id, name and username. Thereafter they'll be synchronized via external id (rather than email address).

      That's also why you need to have verified people's email addresses. (Otherwise someone could steal someone else's Talkyard account.)

      if SSO as a login method is meant to be exclusive, barring users from being created directly in Talkyard

      For Talkyard users who have accounts in the external database, everything is supposed to continue functioning automatically — as long as they use the same email address in both databases.

      be able to (at least manually) assign externalSsoId's to existing users

      I'm thinking that initially, it'll be enough to auto-update Talkyard users, by matching their email addresses with the external users' email addresses?

      Maybe later on it'd be good to be able to edit external ids manually. For example, if someone didn't use the same email address, when signing up at Talkyard, as when signing up with you. Maybe s/he signed in to Talkyard via his/her Facebook account and private email. And created an account with you, using his/her work email. And wants to connect those two accounts.

      IF you want signup via Talkyard and signup via SSO to coexist, this design needs to be reworked

      What I have in mind is that signups directly via Talkyard is completely disabled, and signup is only possible via your website. Otherwise, wouldn't be single sign-on?

      .... At the same time, maybe it'd be nice if people could join the Talkyard forum, without having to create a real customer account at your website? If they want to ask pre-sales questions?

      ... Or maybe it is, or will be, possible to signup at your site, without being a customer? Not sure how things work right now in your case.

      ... If one wants new signups both via Talkyard, and via your website, then I'm wondering if SSO isn't what we should be talking about? Instead maybe something like OpenAuth is what's relevant then, and adding another login method to Talkyard's login dialog (in addition to "Log in with Gmail" etc) ?

      ==

      In our system we have only an UID and a email address as unique columns, no usernames. What we have that is closer to a name is a "full name" property

      Ok, and (as you mentioned) constructing the Talkyard username, from the email address, can be a privacy issue (the email addresses could be reconstructed by trying with the_username@gmail.com or @your.domain.com (right?)).

      Maybe then Talkyard should not require any username, in the login-or-signup request. Instead, if username absent, Talkyard constructs a username from the Full Name. And if neither username or full-name specified, then the user gets a name like unnamed_12345 where 12345 is a random number? (and no parts of the email address are exposed)

      ==

      "API password"

      API Secret

      That sounds good, better than "API password" (because passwords are typically things humans remember and type manually, right). Ok, so "API secret" then.

      ==

      Thanks for the feedback, I find it very useful, and looking forward to hearing your thoughts & feedback about all this :- )

      1. CChristian Scheuer @chrscheuer2018-09-09 04:21:15.229Z

        What I have in mind is that signups directly via Talkyard is completely disabled, and signup is only possible via your website. Otherwise, wouldn't be single sign-on?
        .... At the same time, maybe it'd be nice if people could join the Talkyard forum, without having to create a real customer account at your website? If they want to ask pre-sales questions?
        ... Or maybe it is, or will be, possible to signup at your site, without being a customer? Not sure how things work right now in your case.
        ... If one wants new signups both via Talkyard, and via your website, then I'm wondering if SSO isn't what we should be talking about? Instead maybe something like OpenAuth is what's relevant then, and adding another login method to Talkyard's login dialog (in addition to "Log in with Gmail" etc) ?

        I agree to disable Talkyard signups while having SSO enabled is preferable since it makes the design simpler.
        As long as Talkyard can then redirect to our login page when a user tries to access a Talkyard page without being logged in, then it should all work beautifully.

        ==

        Ok yes that's a good point. This: "the auth url returned by the /-/v0/login-or-signup" can instead be a one-time-secret-key, say nnnn (instead of a complete url), which you'd include in a URL query param together with a &thenGoTo=/some/page param, when telling the browser where to go next. After getting the response from the login-or-signup API request, you'd send the browser to:

        I like this approach.

        ==

        Ok, maybe the OpenAuth username could be like externalSsoId=your-user-id if it's your external id, and talkyardId=4567 if the id is for Talkyard's database? Or maybe 2 would be user id 2 in Talkyard's database and 2@external or 2@your-company-name could be for ids in your database?
        In any case, sounds like important to be able to use your own ids, so you won't need to lookup ids.

        I don't have any preferences for this as we won't be needing much bulk access to those kinds of functions (yet, at least).
        Fwiw I wasn't talking about authentication being a problem with two sets of id's. When you're authenticating as a user you would go through the login-or-signup step anyway. I meant if you are logged in to the API via the admin secret key and you want to perform bulk operations on users, you would need to be able to access them via the externalSsoId as well (if you go with those two distinct columns). Not sure that this should have anything to do with OpenAuth usernames, since OpenAuth usernames would be for the authentication (which I think you are covering in the login-or-signup). These thoughts were meant for acting with non-SSO api functions after having signed in to the API with an admin level secret.

        ==

        I was thinking (and forgot to write) that if an existing user account has the same email address as [an external user that signs up via SSO], then it'll be assumed that those two accounts (i.e. the Talkyard user account and the external account in your database) are for the same person — and the Talkyard user account will be assigned the external id of that external user, and updated with its external id, name and username. Thereafter they'll be synchronized via external id (rather than email address).

        I'm still feeling there are many identity columns at play here if you're keeping track of both talkyardId, externalSsoId and email and all are meant to uniquely identify a user. Isn't there going to be a lot of corner cases where behavior would be undefined, if any of these 3 columns for some reason don't match anymore?
        How would it handle if you're logging in with an externalSsoId that matches one user but an email that matches another? Maybe it should just fail. But something in me thinks the mapping needs to be either a very simple mechanism or a mechanism that's thoroughly described. It's important that emails in those cases wouldn't get silently swapped to other users because the system was automatically converging users... That would pose a security risk.

        ==

        Maybe then Talkyard should not require any username, in the login-or-signup request. Instead, if username absent, Talkyard constructs a username from the Full Name. And if neither username or full-name specified, then the user gets a name like unnamed_12345 where 12345 is a random number? (and no parts of the email address are exposed)

        I like this approach. Users who don't want their full name as forum usernames can still manually edit them in their profiles but by using their full names per default we encourage transparency and authenticity which is always good.
        I still think in the long run, it would be preferred if there was a "welcome new user" page where that user was welcomed to the forum and was allowed to set up a username. Maybe as an opt-in feature/setting. But this is something that can be added on at a later stage if Talkyard starts with the fullname as a basis (and then ensures uniqueness). I will just always favor solutions that are less magic and more explicit. They tend to work better in the long run.

    2. In reply toKajMagnus:
      Matthew Rafuse @halo43562018-08-22 12:46:44.454Z

      Yeah, I agree with this approach as a start, overall. All of the complaints I have Christian raised.

      1. KajMagnus @KajMagnus2018-08-26 11:54:00.988Z

        Ok :- ) I've replied to Christian now

      2. Progress
      3. @KajMagnus marked this topic as Planned 2018-08-31 16:51:22.714Z.
      4. @KajMagnus marked this topic as Started 2018-09-01 14:11:58.184Z.
      5. In reply toKajMagnus:
        KajMagnus @KajMagnus2018-09-16 13:26:03.027Z2018-10-05 07:10:20.317Z

        @chrscheuer and @halo4356 I've implemented a first version of the API and Single Sign-On. Would you like to try it out and give feedback? — This is currently available here at Talkyard.io and SaaS hosted websites, ... The open source installations will auto upgrade this night, or the Monday-Tuesday night. (that's what I have in mind anyway)

        This is how it works, for Single Sign-On:

        Go to the Admin Area (click your username, then Admin). Go to the API tab. Click Create new secret.

        Then, you can try synchronizing one of your users, in your database, with the Talkyard user database, via this update-or-insert request: (currently this only inserts, won't update any fields if the account already exists. If there's no Talkyard account with the specified external id, then any Talkyard user with the same email address, will get connected with the external account (if the email adddress has been verified, in both accounts, and the already existing Talkyard account isn't already connected to an external user).)

        POST /-/v0/sso-upsert-user-generate-login-secret
        
        {
          "externalUserId": "extmagnus",
          "primaryEmailAddress": "noemail@example.com",
          "isEmailAddressVerified": true,
          "username": "extmagnus",
          "fullName": "Ext Magnus"
        }
        

        And include a Basic Authentication header: Authorization: Basic nnnnnnnnnnnn where nnn is talkyardId=2:Your-API-secret base64 encoded. 2 is the ID of the Sysbot user, which you can use, for API requests. (There's also a System user with id 1 — it isn't allowed to do any API requests though.)

        The Talkyard server should respond with 200 OK and:

        { "loginSecret": "zzzzzzzzzzzzzzzzzz" }   // note: 'ssoLoginSecret' renamed to just 'loginSecret'
        

        Now, redirect your user's browser to:

        https://the-talkyard-server/-/v0/login-with-secret?oneTimeSecret=zzzzzzzzzzzzzzzzzz&thenGoTo=/
        

        (note: /-/v0/sso-login renamed to /-/v0/login-with-secret — because will be used for things other than SSO too.)

        This sets a session cookie so the user gets logged in.

        (B.t.w. in case you have any ideas or tips about how to create auto test that verifies that the API, and also examples in the API documentation, works properly, please tell me :- ) I've read about API Blueprint and Swagger.)

        1. CChristian Scheuer @chrscheuer2018-09-16 20:36:03.528Z

          Wonderful news! How do I test it out without messing up my users though? Our forum is pretty much to be considered "in production" right now. Maybe I can just create a few test users with my own email addresses and test from those?

          1. CChristian Scheuer @chrscheuer2018-09-16 20:38:22.175Z

            Also interested in what the next steps in implementing this are. I'm assuming if this all works as expected the next step to have SSO would be to tell Talkyard where to redirect not-logged in users once they try to access a protected forum entry or when they press Login/Signup?

            1. KajMagnus @KajMagnus2018-09-18 02:09:51.666Z

              How do I test it out [...] create a few test users with my own email addresses and test from those?

              Sounds like a good idea to me.

              (... b.t.w. I think fairly often, it's more complicated to test things, than to implement them :- P )

              what the next steps in implementing this are [...] tell Talkyard where to redirect not-logged in users [...] ?

              Yes, I'll add a config value where you can tell Talkyard where to send a not-logged-in-user, if s/he clicks Reply or Log In. I think you'll fill it in with something like https://your-server/your-login-page?thenReturnTo=${currentTalkyardUrlPathAndQuery}. Then, when the user clicks Reply at the Talkyard forum, s/he gets sent to something like https://your-server/your-login-page?thenReturnTo=/a/page/at/talkyard, and after the user has logged in at your place, you'll send it to: https://the-talkyard-server/-/v0/sso-login?oneTimeSecret=zzzzz&thenGoTo=/a/page/at/talkyard

              Also, I'll implement API endpoints people ask for, and add docs and auto docs tests.

              1. Matthew Rafuse @halo43562018-09-28 12:29:47.129Z

                Any word on this feature? It's the only feature we are currently waiting on.

                1. KajMagnus @KajMagnus2018-09-29 10:35:34.695Z

                  Hi Matthew! I think this feature will be available for you on Thursday next week. (How does that sound?) What remains now is (i think) mostly code review and writing e2e tests.

          2. In reply toKajMagnus:
            Matthew Rafuse @halo43562018-09-17 14:13:10.473Z

            I'm not yet seeing the API tab. We may have auto-updating turned off, I'll send a ping to the person running our site.

            1. KajMagnus @KajMagnus2018-09-18 02:15:00.809Z

              Oh I published the on-premise installations update on Monday, then your server updates itself at 04:10 the night to Tuesday (in your time zone I think). That's still some hours into the future, is it. Sorry for the confusion.

              1. Matthew Rafuse @halo43562018-09-20 16:56:06.544Z

                Yep, got it now,

                1. KajMagnus @KajMagnus2018-09-21 08:22:10.012Z

                  Ok. (B.t.w. if you delete an API secret (in the admin area), right now, you need to refresh the page to see that it actually got deleted.)

                  1. Matthew Rafuse @halo43562018-09-21 14:03:36.648Z

                    how exactly can we redirect users who attempt to log in at talkyard to our external site?

                    I'm considering an approach using custom JS to overwrite the login link to navigate to our external site.

                    1. KajMagnus @KajMagnus2018-09-21 17:33:26.437Z

                      I'll add a config value so you can specify to which URL they should be sent — look here: https://www.talkyard.io/-121#post-13 (another post on this page)

                      (that is fairly much what you were thinking about doing, with custom JS?)

                      1. Matthew Rafuse @halo43562018-09-25 11:35:55.006Z

                        Yeah, that's pretty much it.

          3. In reply toKajMagnus:
            KajMagnus @KajMagnus2018-10-04 09:06:28.511Z2018-10-05 07:08:04.162Z

            Hi @chrscheuer and @halo4356 and @jhkings, I just released a new version, with Single Sign-On, now including the previously missing [redirect Login and Reply etc buttons to the SSO page] feature.

            @halo4356 your server should auto upgrade this night, or, if you want to try the new version directly, do:

            sudo -i
            cd /opt/talkyard/
            ./scripts/upgrade-if-needed.sh
            

            To start using SSO, go to your-server/-/admin/settings/login (click Admin in your username menu, then Settings, then Signup and Login). Then scroll to the bottom, and fill in your Single Sign-On URL. Then follow the instructions you'll see there — namely go to your-server/-/sso-test and try to make SSO work.

            Note: I renamed one URL endpoint to /-/v0/login-with-secret instead. Othewise works as described here: https://www.talkyard.io/-121#post-9 on this page. And you need to generate an API secret — the API tab in the admin area.

            Later, when SSO works, check the Enable Single Sign-On checkbox (at the bottom of the Signup and Login settings page). And if you lock yourself out, go to /-/admin-login and type your admin email address, and you'll get a one-time login link (via email) so you can disable SSO and try again.

            Tips:

            1. Matthew Rafuse @halo43562018-10-05 16:42:11.859Z

              Working great - thanks for implementing!

              1. In reply toKajMagnus:
                CChristian Scheuer @chrscheuer2018-10-07 11:23:13.276Z

                Can't wait to enable this. @KajMagnus now that I know that one of the URLs changed I was happy that we hadn't implemented this just yet. I know that this is still somewhat in beta maybe, but is now a good time to implement it on our end and then know that if we enable it there won't be breaking changes (or maybe just a heads up if there will be?)

                1. KajMagnus @KajMagnus2018-10-09 13:00:08.165Z

                  Hi Christian! Actually both URLs work right now, both the old deprected names, and the new. Like so:

                  /-/v0/sso-upsert-user-generate-login-secret 
                        — a good name I think, because there
                        will be "SSO overwrites username / full-name /
                        about-user" config values, that affect
                        how this endpoint behaves, if the user account
                        already exists:  By default, existing fields probably
                        won't be overwritten — unless one enables the
                        "SSO overwrites ..." future config values.
                  
                  /-/v0/upsert-external-user-generate-login-secret
                        — deprecated, still works
                  
                  /-/v0/login-with-secret  — good name
                  /-/v0/sso-login          — deprecated, still works
                  

                  and in the /-/v0/sso-upsert-user-generate-login-secret response, both the fields loginSecret (better name) and ssoLoginSecret (I'd like to remove) are included, set to the same identical secret value.

                  is now a good time to implement it on our end

                  I'll add more end-to-end tests the nearest weeks. If you aren't in a hurry, I think waiting maybe one or two more weeks is a bit safer.

                  a heads up if there will be

                  Yes, I'd like to implement per-category subscriptions, and then I can subscribe you and the others, to an Announcements category, where I'll post info about API changes so you'll get notified a month? two months? in advance.

                  Maybe there could be a list of people who want to reply "OK, we're compatible with this API change" before a non-backwards compatible change goes live? So, if I change something, I can wait for you, and other people on the list, to reply and say "fine with us". ...

                  ... Some time later, this list could be replaced with automatic warnings, shown when one logs in as admin. Like: "You're using this deprecated API endpoint: .... which will be removed after YY-MM-DD. Please instead: ... " combined with a notification email to all admins, from one's server's System user. That is, the software would keep track of which deprecated things are being used, and auto-warn the admins.

                  1. CChristian Scheuer @chrscheuer2018-10-12 11:14:19.075Z

                    These all sound like great ideas. Because of scheduling of our launch we'd prefer to be able to start implementing the SSO this weekend and going into next week. Please make a shout out if something should change :)