From d081aae84795b4f61f57d787bee9cf49eef422f8 Mon Sep 17 00:00:00 2001 From: Pavel Shaydo Date: Fri, 12 Jun 2020 17:44:15 +0200 Subject: [PATCH] document how we do authentication --- docs/userAuthentication.md | 107 +++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/userAuthentication.md diff --git a/docs/userAuthentication.md b/docs/userAuthentication.md new file mode 100644 index 0000000..9bfeb08 --- /dev/null +++ b/docs/userAuthentication.md @@ -0,0 +1,107 @@ +--- +id: authentication +title: Authentication +sidebar_label: Authentication +--- + +To authenticate users of application server we use JWT. When the user logs in, +they send their username and password and appserver returns signed JWT +containing username, timespan of the token validity and audience indicating +what it can be used for. With every request requiring authentication user +includes this JWT in HTTP header as follows: + +``` +Grpc-Metadata-Authorization: Bearer eyJhbGciOiJ... +``` + +Some requests may additionally require a code for second factor authentication. It maybe TOTP code, or recovery code. For these requests the code should be added into `Grpc-Metadata-X-OTP` header: + +``` +Grpc-Metadata-X-OTP: 738854 +``` + +TOTP and recovery codes may be used interchangeably, you can use either in any +request. Each code may be used only once, and you may only use it once in every +30 seconds interval. + +## Login Procedure + +To log in you need to send request to `/api/internal/login` with username and +password. If password is correct the call will return JWT and flag indicating +if second factor authentication is required. If second factor authentication is +not required, then returned JWT can be immediately used to call other APIs. In +case of second factor authentication you need to call +`/api/internal/loging-2fa` and you need include the OTP code and the JWT into +the request. If OTP is valid you will get another JWT token that you can use to +call other APIs. + +## Enabling Two-Factor Authentication + +The following calls handle two-factor authentication configuration: + +### /api/internal/totp-status + +This call returns the current status of two factor authentication, indicating +if it is enabled or not. + +### /api/internal/totp-configuration + +This call generates a random secret for generating TOTP and 10 recovery codes. +It returns the secret as string, URL and QR code, and also it returns the list +of recovery codes. Note, that this call does not enables two-factor +authentication, but just creates the configuration. + +### /api/internal/totp-enable + +This call requires you to include OTP into the header and if it is correct, +then two-factor authentication will be enabled. + +### /api/internal/totp-disable + +This call requires you to include OTP into the header and if it is correct, +then two-factor authentication will be disabled. + +### /api/internal/totp-recovery-codes + +This call requires you to include OTP into the header and if it is correct, +then it returns a list of 10 recovery codes. If you didn't use any recovery +codes, then the list returned every time will be the same, if you used some +codes, then they will be replaced with the new ones. And you can also +explicitely request to regenerate all the codes, if your old list has been lost +and you are concerned that somebody else may use it. + +## Password Recovery + +If user has forgotten their password, they can request password reset. To +request the password reset a call has to be send to +`/api/internal/request-password-reset` with the name of the user. If the user +exists then email will be send to them containing 6 digit code that can be used +to reset their password. This code has to be sent then to +`/api/internal/confirm-password-reset` with username, and new password. For +security reasons we require at least 30 days between password resets. + +## Related DB Tables + +The following tables are used in authentication process: + +### user + +this table contains user id, username, hashed password and the flag indicating +if user is active or not. + +### totp_configuration + +this table contains totp configuration for users including if two-factor +authentication is enabled, the secret used to generate TOTP and the timestamp +for the last code that has been used. The secret is stored encrypted. + +### totp_recovery_codes + +this table contains recovery codes for users. They are stored encrypted, just +like TOTP secret. + +### password_reset + +this table stores information required for resetting password. It stores the 6 +digit recovery code, the date when it was generated and the number attempts +left to enter it correctly.