IT4Change/gradido
3
0
Fork 0
mirror of https://github.com/IT4Change/gradido.git synced 2025-12-13 07:45:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleaned login_server.api.md to be more precise and well structured

Browse Source
This commit is contained in:
Ulf Gebhardt 2021-04-01 21:05:51 +02:00
parent 3c0999f163
commit 2fc45c94ef
No known key found for this signature in database
GPG Key ID: 81308EFE29ABFEBD
1 changed files with 291 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

464
docu/login_server.api.md
View File

@ -1,236 +1,321 @@
# login server api
# Login Server API
Gradido js-Frontend vereinfachte Zusammenarbeit mit Login-Server und Community-Server
This document describes the login server API. The login server is written in C++ and mixes front with backend.
The primary task of the login server is to store and handle the private keys of the users securely.
Es ist mit einer Zusatz-Option möglich das Login und Registrieren via ajax-Request passiern kann.
Dafür muss in der Login-Server Config
## Configuration
You can configure the login server to handle login and register requests via http call, by setting the following config option:
```ini
unsecure.allow_passwort_via_json_request = 1
unsecure.allow_passwort_via_json_request = 1
```
gesetzt sein.
To disable CORs restrictions you can set:
mit:
```ini
unsercure.allow_cors_all = 1
```
Wird bei allen JSON-Requests zum Header hinzugefügt:
- Access-Control-Allow-Origin:*
- Access-Control-Allow-Headers: "Access-Control-Allow-Headers, Origin,Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers"
This will result in all JSON-Request headers to contain:
In diesen Beispielen gehe ich jetzt davon aus, das du das gesamte Gradido Projekt mit Docker gebaut hast und auf dem lokalen Rechner laufen lässt.
Login
Einloggen über:
## unsecureLogin
POST http://localhost/login_api/unsecureLogin
```json
data: {"email": "max.musterman@gmail.de", "password": "123abcDE&"}
```
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: "Access-Control-Allow-Headers, Origin,Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers"
```
Wenn alles okay ist erhältst du zum Beispiel:
## Error handling
// TODO
## Login
To login you can use the `unsecureLogin` request
### Request
`POST http://localhost/login_api/unsecureLogin`
with:
```json
{"state":"success", "session_id": -127182, "clientIP":"52.68.96.58"}
{
"email": "max.musterman@gmail.de",
"password": "123abcDE&"
}
```
- clientIP: should be the same as where the js-client is running, else maybe a man-in-the-middle attacks is happening or
### Response
In case of success returns:
```json
{
"state":"success",
"session_id": -127182,
"clientIP":"123.123.123.123"
}
```
- `clientIP`: should be the same as where the js-client is running, else maybe a man-in-the-middle attacks is happening or
nginx was wrong configured.
- session_id: can be also negative
- `session_id`: can be also negative
Anmelden
Registrieren kannst du einen neuen Benutzer mit:
## Create user
Register a new User
### Request
`POST http://localhost/login_api/createUser`
## createUser
with:
POST http://localhost/login_api/createUser
```json
data: {
{
"email":"max.musterman@gmail.de",
"first_name":"Max",
"last_name":"Musterman" ,
"emailType": 2,
"password":"123abcDE&"
"password":"123abcDE&",
"login_after_register":true
}
}
```
- emailType: control email-text sended with email verification code
- `emailType`: control email-text sended with email verification code
- 2: default, if user has registered directly
- 5: if user was registered by an admin
- login_after_register: if set to true auto-login after create user was successfull, means session cookie is set and session_id returned
- `login_after_register`: if set to true auto-login after create user was successfull, means session cookie is set and session_id returned
### Response
In case of success returns:
Wenn alles okay ist erhältst du:
```json
{"state":"success"}
{
"state":"success"
}
```
Dann wurde für den Benutzer ein neues Konto angelegt, seine Schlüssel generiert und ihm eine Bestätigungs-Email geschickt.
Now a new user is registered, its keys were generated and it can be logged in. A confirmation EMail has been sent to the user as well.
// TODO return type if `login_after_register=true` is used
## Logout
To logout an logged in session:
### Request
`POST http://localhost/login_api/logout`
with:
Abmelden
POST http://localhost/login_api/logout
```json
data: {"session_id": -127182}
{
"session_id": -127182
}
```
Wenn alles okay ist erhältst du:
### Response
In case of success returns:
```json
{"state":"success"}
{
"state":"success"
}
```
## Update User Data
Update first name, last name, user language and enable/disable user
Language currently supported de and en
User will be disabled if he wants a account delete but has transactions.
Until transactions are saved in real blockchain, we need this data because the public key
is in db only saved in state_users so we wenn delete this entry, validating all transactions not longer possible.
Disabled User cannot login and cannot receive transactions.
In update Object only one of the sets needs to be there.
## Update user data
This request allows you to update first name, last name, user language and enable/disable user.
Additionally the user's password can be changed if the following option is set:
Update password can only be used if in Login-Server config:
```ini
unsecure.allow_passwort_via_json_request = 1
```
is set
POST http://localhost/login_api/updateUserInfos
### Request
`POST http://localhost/login_api/updateUserInfos`
with:
```json
{"session_id": -127182, "email": "max.musterman@gmail.de", "update": {
"User.first_name": "Max",
"User.last_name" : "Musterman",
"User.disabled": 0,
"User.language": "de"
"User.password": "1234"
}
}
```
also valid
```json
{"session_id": -127182, "email": "max.musterman@gmail.de", "update": {
"User.last_name" : "Musterman"
}
{
"session_id": -127182,
"email": "max.musterman@gmail.de",
"update": {
"User.first_name": "Max",
"User.last_name" : "Musterman",
"User.disabled": 0,
"User.language": "de"
"User.password": "1234"
}
}
```
It returns if everything is okay
Notes:
- `user.language`: currently supports `de` and `en` only
- User will be disabled if he wants his account deleted, but has transactions. Until transactions are saved in real blockchain, we need this data because the public key is in db only saved in state_users so if we delete this entry, validating all transactions is no longer possible.
- Disabled Users can neither login nor receive transactions.
- It is not required to provide all fields of `update`, it can be a subset depending on what you intend to change.
### Response
In case of success:
```json
{"state":"success", "valid_values": 4, "errors":[]}
{
"state":"success",
"valid_values": 4,
"errors": [...]
}
```
- valid_values: should contain count of entrys in update if no error occured (User.password will not be counted)
- errors: contain on error string for every entry in update, which type isn't like expected
- password:
- `valid_values`: should contain count of entries in update if no error occurred (User.password will not be counted)
- `errors`: contain on error string for every entry in update, which type isn't like expected
- `password`:
- "new password is the same as old password": no change taking place
- "password changed, coludn"t load private key for re-encryption": password was successfully changed, is at the moment only a warning as long as user_backups are unencrypted, safe to ignore
- "stored pubkey and private key didn't match": error by re-encryption keys, no changes saved
- "User.password isn't valid": if password validation failed, followed by reasons why (additional array in array)
example:
```json
{"errors":[
"User.password isn't valid",[
"Passwort: Dein Passwort ist zu kurz!\n",
"Passwort: Bitte gebe ein gültiges Password ein mit mindestens 8 Zeichen, Groß- und Kleinbuchstaben, mindestens einer Zahl und einem Sonderzeichen (@$!%*?&+-_) ein!\n"
]
],
"state":"success",
"valid_values":0
}
```
## Retrieve User Data
Retrieve different user data, in ask only one field is needed, or every possible combination
from the available fields
Example:
```json
{
"errors": [
"User.password isn't valid",
[
"Passwort: Dein Passwort ist zu kurz!\n",
"Passwort: Bitte gebe ein gültiges Password ein mit mindestens 8 Zeichen, Groß- und Kleinbuchstaben, mindestens einer Zahl und einem Sonderzeichen (@$!%*?&+-_) ein!\n"
]
],
"state":"success",
"valid_values":0
}
```
## Retrieve user data
Retrieve different user data.
You can query a subset of data or all of it at once.
Normal Users can only retrieve data for themselves, admins (login-server admin) can retrieve data for every user.
Normal User can only retrieve data for himself, admins (login-server admin) can retrieve data from every user
Email is also the email address of user from which data are asked
POST http://localhost/login_api/getUserInfos
### Request
`POST http://localhost/login_api/getUserInfos`
with:
```json
{"session_id": -127182, "email": "max.musterman@gmail.de", "ask": [
"EmailVerificationCode.Register",
"loginServer.path",
"user.pubkeyhex",
"user.first_name",
"user.last_name",
"user.disabled",
"user.email_checked",
]
}
```
returns if no error occured:
```json
{"state": "success", "userData": {
"EmailVerificationCode.Register": "2718271129122",
"pubkeyhex": "131c7f68dd94b2be4c913400ff7ff4cdc03ac2bda99c2d29edcacb3b065c67e6",
"first_name": "Max",
"last_name": "Musterman",
"disabled": 0,
"email_checked": 1
}, "server": {
"loginServer.path": "http://localhost/account"
},
"errors": []
{
"session_id": -127182,
"email": "max.musterman@gmail.de",
"ask": [
"EmailVerificationCode.Register",
"loginServer.path",
"user.pubkeyhex",
"user.first_name",
"user.last_name",
"user.disabled",
"user.email_checked",
]
}
```
Return only the fields which are defined in ask
- EmailVerificationCode.Register: return the email verification code for check email (create one if none exist), work only if logged in user is admin and the email isn't from him
- loginServer.path: the redirect path to login-server, for example for login with login-server html frontend
- user.pubkeyhex: public key of user in hex-format
- user.first_name: first name of user
- user.last_name: last name of user
- user.disabled: User will be disabled if he wants a account delete but has transactions.
Until transactions are saved in real blockchain, we need this data because the public key
is in db only saved in state_users so we wenn delete this entry, validating all transactions not longer possible.
Disabled User cannot login and cannot receive transactions.
- email_checked: If user has clicked on link in verification email (register), can only transfer gradidos if email_checked is 1
### Response
In case of success:
- errors: array of strings if error occure
```json
{
"state": "success",
"userData": {
"EmailVerificationCode.Register": "2718271129122",
"pubkeyhex": "131c7f68dd94b2be4c913400ff7ff4cdc03ac2bda99c2d29edcacb3b065c67e6",
"first_name": "Max",
"last_name": "Musterman",
"disabled": 0,
"email_checked": 1
},
"server": {
"loginServer.path": "http://localhost/account"
},
"errors": []
}
```
Return only the fields which are defined in request
- `EmailVerificationCode.Register`: return the email verification code for check email (create one if none exist), work only if logged in user is admin and the email isn't from him
- `loginServer.path`: the redirect path to login-server, for example for login with login-server html frontend
- `user.pubkeyhex`: public key of user in hex-format
- `user.first_name`: first name of user
- `user.last_name`: last name of user
- `user.disabled`: User will be disabled if he wants a account delete but has transactions. Until transactions are saved in real blockchain, we need this data because the public key
is in db only saved in state_users so if we delete this entry, validating all transactions is no longer possible. Disabled User cannot login and cannot receive transactions.
- `email_checked`: If user has clicked on link in verification email (register), can only transfer gradidos if email_checked is 1
- `errors`: array of strings if error occure
## Login by Email Verification Code
Used for replace http://localhost/account/checkEmail
Can be used to set check_email to 1 (will be done automaticly if called with valid email verification code of type register or registerDirect)
Can be used for password reset (additional step required: call update user info with new password)
Login while confirming your EMail. This API call is used to replace http://localhost/account/checkEmail (HTML).
GET http://localhost/login_api/loginViaEmailVerificationCode?emailVerificationCode=382738273892983
If successful `check_email` will be set to 1 in the database.
// TODO why would I want to do this?
// TODO ??? (will be done automaticly if called with valid email verification code of type register or registerDirect)
// TODO ??? Can be used for password reset (additional step required: call update user info with new password)
### Request
`GET http://localhost/login_api/loginViaEmailVerificationCode?emailVerificationCode=382738273892983`
### Response
In case of success returns:
return
```json
{"state":"success", "email_verification_code_type":"resetPassword","info":[],"session_id":1853761475}
{
"state":"success", "email_verification_code_type":"resetPassword",
"info":[],
"session_id":1853761475
}
```
- email_verification_code_type
- resetPassword: for password resets, will be deleted immediately, is a only one use code
- registerDirect: code generated by register for check email
- register: code generated by auto-register via elopage for check email
- info can contain additional info strings
- `email_verification_code_type`
- `resetPassword`: for password resets, will be deleted immediately, is a only one use code
- `registerDirect`: code generated by register for check email
- `register`: code generated by auto-register via elopage for check email
- `info`: can contain additional info strings
- "user hasn't password": if user hasn't set a password yet (for example if he was registered via elopage)
- "email already activated": if email was already checked
- session_id: session_id for new session
- `session_id`: session_id for new session
## Send Emails
Let send Login-Server Password reset E-Mail to User
Can be also used for admin interface to resend email verification code
## Send E-Mails
Lets you send Login-Server Password reset E-Mail to an user.
Can be also used for the admin interface to resend email verification codes
### Request
`POST http://localhost/login_api/sendEmail`
with:
POST http://localhost/login_api/sendEmail
```json
{"email": "max.musterman@gmail.de", "email_text":7, "email_verification_code_type":"resetPassword" }
{
"email": "max.musterman@gmail.de",
"email_text":7, "email_verification_code_type":"resetPassword"
}
```
also valid:
```json
{"email": "max.musterman@gmail.de", "email_text":"user reset Password", "email_verification_code_type":"resetPassword" }
{
"email": "max.musterman@gmail.de",
"email_text":"user reset Password", "email_verification_code_type":"resetPassword" }
```
// TODO this makes no sense, why two fields email_text & code_type?
or:
```json
{"session_id": -127182, "email": "max.musterman@gmail.de", "email_text":5, "email_verification_code_type":"register" }
{
"session_id": -127182,
"email": "max.musterman@gmail.de",
"email_text":5,
"email_verification_code_type":"register"
}
```
- session_id: not needed for resetPassword emails
- email_type: choose which email text should be used (number or string can be used)
- `session_id`: not needed for resetPassword emails
- `email_type`: choose which email text should be used (number or string can be used)
- "email user verification code" (2): default text used when new user has registered
- "email user verification code resend" (3): text used when user hasn't activated his account 7 days after register
- "email user verification code resend after long time" (4): text used when user hasn't activated his account more than 7 days after register
@ -238,31 +323,40 @@ or:
- "email admin user verification code resend" (6): used if admin trigger sending the email with email verification code again
- "user reset Password" (7): used for reset password email text
- "email custom tex" (8): used if custom email text should be used (than email_custom_text and email_custom_subject must also be filled)
- email_verification_code_type
- `email_verification_code_type`
- resetPassword: for password resets, will be deleted immediately, is a only one use code, can be used without session_id
- registerDirect: code generated by register for check email, can only be used by admins for another user
- register: code generated by auto-register via elopage for check email, can only be used by admins for another user
- email_custom_text (optional): can be used to send email with custom text
- `email_custom_text`: (optional) can be used to send email with custom text
placeholder for email text, will be replaced
- [first_name] first name
- [last_name] last name
- [duration] time span since user has created account (ex.: 10 Days) with largest unit, day is last unit
- [link] login-server checkEmail link with email verification code (ex.: http://localhost/account/checkEmail/382738273892983)
- [code] email verification code if you like to use your one link
- email_custom_subject (optional): for custom email the subject
- `email_custom_subject`: (optional) for custom email the subject
return
```json
{"state":"success"}
```
if everything is okay
return
```json
{"state":"warning", "msg":"email already sended"}
```
if emails was successfully sended but was already sended in past also.
### Response
In case of success returns:
return with "state":"error" and additional "msg" if error occured (no email sended):
```json
{
"state":"success"
}
```
or:
```json
{
"state":"warning",
"msg":"email already sended"
}
```
(if emails was successfully sent but was already sent before)
Furthermore following error cases can take place:
A result with `"state":"error"` and an additional `"msg"` if an error occurred (no email sended):
- "email already send less than a hour before": User has already get a password reset email and haven't used the link yet
- "not supported email type": with "email_verification_code_type":"resetPassword" only email type 7 or 8 allowed
- "admin needed": only admins can send email verification emails because this emails normally sended out automaticly
@ -272,18 +366,28 @@ return with "state":"error" and additional "msg" if error occured (no email send
- "invalid verification code type": could not parse email verification code type
- "json exception": error parsing input json, more infos can be found in details
## Check Running Transactions / password encryption
Check if transactions on login-server for user are processed
GET http://localhost/login_api/getRunningUserTasks?email=max.musterman%40gmail.de
**OR**
POST http://localhost/login_api/getRunningUserTasks
### Request
`GET http://localhost/login_api/getRunningUserTasks?email=max.musterman%40gmail.de`
or:
`POST http://localhost/login_api/getRunningUserTasks`
with:
```json
{"email":"max.musterman@gmail.de"}
{
"email":"max.musterman@gmail.de"
}
```
return
### Response
In case of success returns:
```json
{
"state":"success",
@ -295,21 +399,33 @@ return
}
}
```
return only entrys which > 0
return only entries which > 0
- password creation: after register or password change, login possible after tasks is finish
- sign transaction: after check transaction in backend, before transaction is in db
- prepare transaction: after sending transaction to login-server, before they can be checked
- ready for sign transaction: transactions ready for signing from user
## Check Session State
GET http://localhost/login_api/checkSessionState?session_id=-127182
Check if a given session is still valid
### Request
`GET http://localhost/login_api/checkSessionState?session_id=-127182`
### Response
In case of success returns:
return if session is still open
```json
{"state":"success"}
```
else return
```json
{"state":"not found", "msg": "session not found"}
{
"state":"success"
}
```
or:
```json
{
"state":"not found",
"msg": "session not found"
}
```