Improve /authenticate/* URLs

Development
#1

Hi devs,

With https://jira.xwiki.org/browse/XWIKI-11205 we have recently introduced 2 new URLs for “reset password” and “retrieve username” UCs (see https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/13.1RC1/#HMiscellaneous).

Apparently these decisions were taken on a PR but I couldn’t find it (it’s not linked in the JIRA issue). All I could find was a branch but it doesn’t seem to exist so I couldn’t read the history of the discussions. In any case, when introducing some new APIs (and URLs are quite important introductions since they are both public and very visible), I think a proposal would be nice and would allow ensuring we all agree.

EDIT: I just saw that we also introduce public APIs such as ResetPasswordManager. This is also needs agreement since it’s hard to change afterwards.

So I have the following points I’d like to bring:

  1. Why are the new URLs using the authenticate URL Type? I don’t see the relationship with authentication (these URLs are clearly not doing any authentication).
    • Related: Why don’t we have a single URL Type for each action since the actions are quite different: one is about resetting a user password, the other about find a the username of a user based on a provided email address.
    • BTW, I see these actions related a lot more to “user” than to “authentication”, and I’d have put these in the user module instead. For example we should have a setPassword() API in the User API and thus resetting the user password is for me very similar to setting the password and should be together.
  • Question: do we already have a /xwiki/authenticate/* URL for authenticating a user BTW?
  1. I don’t like the new URLs because IMO they cannot be understood just by reading them:
  • /xwiki/authenticate/reset : If I read this I read this is about authenticating a reset. Or maybe resetting an authentication. Reset what? an email? a username? a password? a wiki? the history of a document?
  • /xwiki/authenticate/forgot: Same problem (“I forgot to authenticate?”). Actually a bit worse since it’s now using a verb in the past tense for a future action, very weird :wink:
  1. Question: what happens when an email is associated with several users? (this is the case for me on xwiki.org or myxwiki.org where I have several accounts with the same email). Do we list all usernames? Isn’t that a security breach for an attack for ex?
  2. We seems to be missing documentation: I see on https://extensions.xwiki.org/xwiki/bin/view/Extension/Authentication%20Security%20Module/#HAuthenticateURLresourcetype that we listed the URLs but I don’t see anywhere where we have the screenshots of the UIs.
  3. The Release notes say that if you have custom code in the previous wiki pages you need to port it to Java. Don’t we have templates for the UI for these actions?

About 2) I can suggest some URLs:

  • /xwiki/resetPassword or /xwiki/user/resetPassword
  • /xwiki/retrieveUserName or /xwiki/user/retrieveUserName (alternatives: recover or find instead of retrieve).
  • /xwiki/user/password/reset or /xwiki/user/reset/password (looks a bit more like /xwiki/bin/view/Page with 4 levels)
  • /xwiki/user/username/retrieve or /xwiki/user/retrieve/username

We need to decide quickly because this was introduced in 13.1RC1 and we have only a few days to make changes if we want to do that without causing any problem to anyone (we don’t really have the concept of Unstable for URLs for ex).

WDYT?

PS: Apologies if these were all discussed but when I acted as RM and rewrote the RN for https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/13.1RC1/#HMiscellaneous, I couldn’t help but notice that the new URLs are a bit shaky.

#2

Not sure why you haven’t seen it on the JIRA issue, but it’s there: https://github.com/xwiki/xwiki-platform/pull/1484. Note that actually some decisions were most likely discussed on the chat.

So IMO those actions are all related with authentication, it’s about finding back the password/the username for allowing authentication only. Moreover the links for performing such actions are displayed in the login page of XWiki.

I thought it would have been an over-engineering here to have a dedicated URLs and all the associated components implem for each URLs. It seemed more logical to me to have those URLs under the same resource handler and then to dispatch the actions to the right components.
Also note that on an implementation point of view I find it logical that the URL verb reflect where the resource handler is located in the code and vice-versa.

I don’t quite agree with that assumption: we should indeed have a setPassword() API, but allowing a logged-in user to change her password is quite different than allowing an anonymous user to retrieve her password.

The idea of the resource handler was to allow implementing the authentication with it later on.

I agree they might a bit short, we could use resetPassword and forgetUsername instead. Note that re forget/forgot I actually reused the old names of the page.

I didn’t change the old behaviour of the ForgotUsername page here, so we do display several results in that case, this can be discussed in an issue but it’s not new at the very least.

I don’t think that should go there, it’s more a user documentation related to authentication IMO so should be somewhere in https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/

We have both templates and components. For the forgot username feature, all the logic is handled by the template, while in the case of reset password I actually created ResetPasswordManager to encode most part of the logic, but there’s also a template.

I’m fine with the xwiki/resetPassword and xwiki/retrieveUsername (I think I prefer this one as retrieveUserName, could be retrieveLogin if we want to avoid the ambiguity).