Authentication services (proposed set)
Exists | Method | URI | Auth filtered? | Body | Parameters | Return value | Description | Differences (from existing methods) |
|---|---|---|---|---|---|---|---|---|
POST | /session | LoginCredentials |
| Session | Normal login | Does not fail if the user has not signed the terms of use. Instead, a boolean is returned along with the session token. The client can use that boolean to throw a TermsOfUseException. Note: trying to make an authenticated request will still fail if the terms haven't been accepted. Terms of use cannot be signed here. | ||
PUT | /session | Session |
|
| Revalidates a session token. | Note: This will still fail (403) if the user has not signed the terms of use. | ||
DELETE | /session |
|
|
| Invalidated token |
| ||
POST | /user | NewUser | sendPasswordmail=true (Not implemented yet) |
| Creates a new user | No longer goes through the auth filter. This was originally done because GET /user was filtered. Parameter will let the client specify if Synapse should sent a "Welcome" email or a "Set your password" email. | ||
POST | /user/password | ChangePasswordRequest |
|
| Changes the user's password, regardless of whether they have accepted the terms of use | Replaces /changePassword and /registeringUserPassword | ||
POST | /user/password/email | Username |
|
| Sends a password reset email (containing a session token) | Replaces /registeringUserEmail, /userPasswordEmail, and /apiPasswordEmail | ||
POST | /termsOfUse | Session |
|
| Accepts the terms of use via a session token | New method | ||
GET | /secretKey |
|
| SecretKey | Gets the user's API key |
| ||
DELETE | /secretKey |
|
|
| Invalidates the user's API key |
| ||
POST | /openIdCallback |
| (OpenID params) acceptsTermsOfUse=false createUserIfNecessary=false | Session | Login via OpenID, with options to create a new user and sign the terms of use | Terms of use cannot be signed here. |
Behavior clarifications
Other than PUT /session, methods that do not pass through the auth filter will no longer fail if the user has not signed the terms of use. PUT /session mimics what the auth filter does, so it still throws TermsOfUseExceptions.
It will be the client's job to throw an appropriate exception if a Session object is returned with "acceptsTermsOfUse" set to false.
It will be possible to explicitly reject the terms of use.
Schema changes
Session will have an extra field "acceptsTermsOfUse"
UserSessionData will hold a Session object rather than a "sessionToken" field
ChangePasswordRequest will be added
SessionToken
Password
RegistrationInfo will be removed
ChangeUserPassword will be removed
Portal changes
Any password email sending will use POST /user/password/email
Any password changing will use POST /user/password
A separate prefix (i.e "register_" or "changePassword_" will no longer be required)
We may want to consider removing the prefix entirely
Login should detect if a user has not signed the terms via the new field (rather than a 403 error)
Redirect/show dialog appropriately
Clicking OK on the dialog should POST /termsOfUse
Should session tokens only be valid for <24 hours?
30 minutes is generally considered a compromise between security and convenience.